Class: ShortFloat

• Inheritance
• Description
• Related information
• Class protocol
  • binary storage
  • constants
  • instance creation
  • queries
• Instance protocol
  • arithmetic
  • coercing & converting
  • comparing
  • printing & storing
  • private accessing
  • special access
  • testing
  • truncation & rounding

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--ArithmeticValue
         |
         +--Number
            |
            +--LimitedPrecisionReal
               |
               +--ShortFloat

Package:

stx:libbasic

Category:

Magnitude-Numbers

Version:

rev: 1.103 date: 2009/12/18 14:41:46

user: cg

file: ShortFloat.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

ShortFloats represent rational numbers with limited precision.
They use the C-compilers 'float' format, which is usually the IEE single float format.

In contrast to Floats (which use the C-compilers 64bit 'double' format),
ShortFloats give you 32 bit floats.

Notice, that ST/X Floats are what Doubles are in ST-80 and ShortFloats are
ST-80's Floats respectively.
This may change in one of the next versions (at least on machines, which
provide different float and double types in their C-compiler.

WARNING:
    The layout of shortFloat instances is known by the runtime system and the compiler;
    you may not add instance variables here.
    Also, subclassing is complicated by the fact, that the VM creates floats/shortFloats,
    and does some of its float-checks by an identity compare with the ShortFloat-class.
    (i.e. your subclasses instances may not be recognized as float-like objects,
     thus mixed mode arithmetic will always coerce them, effectively slowing things down).
    This may be changed, to use a flag bit in the class.

Mixed mode arithmetic:
    shortFloat op shortFloat   -> shortFloat
    shortFloat op fix         -> shortFloat
    shortFloat op fraction    -> shortFloat
    shortFloat op integer     -> shortFloat
    shortFloat op longFloat   -> longFloat
    shortFloat op float       -> float
    shortFloat op complex     -> complex

Representation:
        32bit single precision IEE floats
        23 bit mantissa,
        8 bit exponent,
        6 decimal digits (approx)

Range and Precision of Storage Formats: see LimitedPrecisionReal >> documentation

Related information:

    Number
    Float
    LongFloat
    Fraction
    FixedPoint
    Integer
    Complex
    FloatArray
    DoubleArray

Class protocol:

 readBinaryIEEESingleFrom: aStream

read a float value from the binary stream, aStream,
interpreting the next bytes as an IEEE formatted 4-byte float

 readBinaryIEEESingleFrom: aStream into: aFloat

read a float value from the binary stream, aStream,
interpreting the next bytes as an IEEE formatted 4-byte float

 storeBinaryIEEESingle: aFloat on: aStream

store aFloat as an IEEE formatted 4-byte float
onto the binary stream, aStream

 e

return the constant e as ShortFloat

 pi

return the constant pi as ShortFloat

 unity

return the neutral element for multiplication (1.0) as ShortFloat

 zero

return the neutral element for addition (0.0) as ShortFloat

 basicNew

return a new shortFloat - here we return 0.0
- shortFloats are usually NOT created this way ...
Its implemented here to allow things like binary store & load
of shortFloats. (but even this support will go away eventually, its not
a good idea to store the bits of a float - the reader might have a
totally different representation - so floats will eventually be
binary stored in a device independent format.

 fastFromString: aString at: startIndex

return the next ShortFloat from the string starting at startIndex.
No spaces are skipped.

This is a specially tuned entry (using a low-level C-call), which
returns garbage if the argument string is not a valid float number.
It has been added to allow higher speed string decomposition into numbers,
especially for mass-data.

 readFrom: aStringOrStream

read a shortFloat from a string

 readFrom: aStringOrStream onError: exceptionBlock

read a shortFloat from a string

 exponentCharacter

 isBuiltInClass

return true if this class is known by the run-time-system.
Here, true is returned for myself, false for subclasses.

 isIEEEFormat

return true, if this machine represents floats in IEEE format.
Currently, no support is provided for non-ieee machines
to convert their floats into this (which is only relevant,
if such a machine wants to send floats as binary to some other
machine).
Machines with non-IEEE format are VAXed and IBM370-type systems
(among others). Today, most systems use IEEE format floats.

 numBitsInExponent

answer the number of bits in the exponent
This is an IEEE float, where 8 bits are available:
seeeeeee emmmmmmm mmmmmmmm mmmmmmmm

 numBitsInMantissa

answer the number of bits in the mantissa.
This is an IEEE float, where 23 bits (the hidden one is not counted here) are available:
seeeeeee emmmmmmm mmmmmmmm mmmmmmmm

 precision

answer the precision of a ShortFloat (in bits)
This is an IEEE float, where only the fraction from the normalized mantissa is stored
and so there is a hidden bit and the mantissa is actually represented by 24 binary digits
(although only 23 are needed in the binary representation)

 radix

answer the radix of a ShortFloats exponent
This is an IEEE float, which is represented as binary

Instance protocol:

 * aNumber

return the product of the receiver and the argument.

 + aNumber

return the sum of the receiver and the argument, aNumber

 - aNumber

return the difference of the receiver and the argument, aNumber

 / aNumber

return the quotient of the receiver and the argument, aNumber

 abs

return the absolute value of the receiver
reimplemented here for speed

 negated

return myself negated

 uncheckedDivide: aNumber

return the quotient of the receiver and the argument, aNumber.
Do not check for divide by zero (return NaN or Infinity).
This operation is provided for emulators of other languages/semantics,
where no exception is raised for these results (i.e. Java).
Its only defined if the arguments type is the same as the receivers.

 asFloat

return a Float with same value as the receiver.
Redefined for performance (machine can do it faster)

 asInteger

return an integer with same value - might truncate

 asLongFloat

 asShortFloat

return a ShortFloat with same value as the receiver - thats me

 coerce: aNumber

convert the argument aNumber into an instance of the receivers class and return it.

 generality

return the generality value - see ArithmeticValue>>retry:coercing:

 < aNumber

return true, if the argument is greater

 <= aNumber

return true, if the argument is greater or equal

 = aNumber

return true, if the argument represents the same numeric value
as the receiver, false otherwise

 > aNumber

return true, if the argument is less

 >= aNumber

return true, if the argument is less or equal

 hash

return a number for hashing; redefined, since floats compare
by numeric value (i.e. 3.0 = 3), therefore 3.0 hash must be the same
as 3 hash.

 ~= aNumber

return true, if the arguments value are not equal

 printString

return a printed representation of the receiver
LimitedPrecisonReal and its subclasses use #printString instead of
#printOn: as basic print mechanism.

 printfPrintString: formatString

non-standard: return a printed representation of the receiver
as specified by formatString, which is defined by printf.
If you use this, be aware, that specifying doubles differs on
systems; on SYSV machines you have to give something like %lf,
while on BSD systems the format string has to be %F.
Also, the resulting string may not be longer than 255 bytes -
since thats the (static) size of the buffer.
This method is NONSTANDARD and may be removed without notice.
WARNNG: this goes directly to the C-printf function and may therefore me inherently unsafe.
Please use the printf: method, which is safe as it is completely implemented in Smalltalk.

 storeString

return a printed representation of the receiver;
all valid digits are printed.
LimitedPrecisonReal and its subclasses use #storeString instead of
#storeOn: as basic print mechanism.

 basicAt: index

return an internal byte of the float.
The value returned here depends on byte order, float representation etc.
Therefore, this method should be used strictly private.

Notice:
the need to redefine this method here is due to the
inability of many machines to store floats in non-double aligned memory.
Therefore, on some machines, the first 4 bytes of a float are left unused,
and the actual float is stored at index 5 .. 12.
To hide this at one place, this method knows about that, and returns
values as if this filler wasnt present.

 basicAt: index put: value

set an internal byte of the float.
The value to be stored here depends on byte order, float representation etc.
Therefore, this method should be used strictly private.

Notice:
the need to redefine this method here is due to the
inability of many machines to store floats in non-double aligned memory.
Therefore, on some machines, the first 4 bytes of a float are left unused,
and the actual float is stored at index 5 .. 12.
To hide this at one place, this method knows about that, and returns
values as if this filler wasnt present.

 exponent

extract a normalized floats exponent.
The returned value depends on the float-representation of
the underlying machine and is therefore highly unportable.
This is not for general use.
This assumes that the mantissa is normalized to
0.5 .. 1.0 and the floats value is mantissa * 2^exp

 mantissa

extract a normalized floats mantissa.
The returned value depends on the float-representation of
the underlying machine and is therefore highly unportable.
This is not for general use.
This assumes that the mantissa is normalized to
0.5 .. 1.0 and the floats value is mantissa * 2^exp

 isFinite

return true, if the receiver is a finite float
i.e. not NaN and not infinite.

 isNaN

return true, if the receiver is an invalid float (NaN - not a number).
These are not created by ST/X float operations (they raise an exception);
however, inline C-code could produce them ...

 isNegativeZero

many systems have two float.Pnt zeros

 negative

return true if the receiver is less than zero

 numberOfBits

return the size (in bits) of the real;
typically, 32 is returned here,
but who knows ...

 positive

return true if the receiver is greater or equal to zero

 strictlyPositive

return true if the receiver is greater than zero

 ceiling

return the smallest integer which is greater or equal to the receiver.

 ceilingAsFloat

return the smallest integer-valued float greater or equal to the receiver.
This is much like #ceiling, but avoids a (possibly expensive) conversion
of the result to an integer.
It may be useful, if the result is to be further used in another float-operation.

 floor

return the integer nearest the receiver towards negative infinity.

 floorAsFloat

return the float which represents the next lower
integer nearest the receiver towards negative infinity.
Much like floor, but returns a float result - useful if the result
will be used in another float operation, to avoid costy int-conversion.

 fractionPart

extract the after-decimal fraction part.
such that (self truncated + self fractionPart) = self

 rounded

return the receiver rounded to the nearest integer

 roundedAsFloat

return the receiver rounded to the nearest integer as a float.
This is much like #rounded, but avoids a (possibly expensive) conversion
of the result to an integer.
It may be useful, if the result is to be further used in another float-operation.

 truncated

return the receiver truncated towards zero as an integer

 truncatedAsFloat

return the receiver truncated towards zero as a float.
This is much like #truncated, but avoids a (possibly expensive) conversion
of the result to an integer.
It may be useful, if the result is to be further used in another
float-operation.