Class: Float

• Inheritance
• Description
• Related information
• Class protocol
  • binary storage
  • class initialization
  • constants
  • croquet
  • instance creation
  • queries
• Instance protocol
  • arithmetic
  • binary storage
  • coercing & converting
  • comparing
  • mathematical functions
  • printing
  • printing & storing
  • private
  • private-accessing
  • queries
  • special access
  • testing
  • tracing
  • trigonometric
  • truncation & rounding

Inheritance:

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

Package:

stx:libbasic

Category:

Magnitude-Numbers

Version:

rev: 1.173 date: 2010/02/10 17:45:57

user: cg

file: Float.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

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

Floats give you 64 bit floats.
In contrast to ShortFloats and LongFloats.

WARNING:
    The layout of Float 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 float-checks by an identity compare with the Float-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).

Notice, that Floats are defined as Byte-array to prevent the garbage collector
from going into the value ... otherwise I needed a special case in many places.

Also notice, that ST/X Floats are what Doubles are in ST-80 - this may change
in one of the next versions (at least on machines, which provide different float
and double types in their C-compiler).
The reason for doung this was to be compatible to both Digitalk and ParcPlace smalltalk
implementations
(ParcPlace uses a 4-byte Float and an 8-byte Double class, in contrast to
 Digitalk, which has an 8-byte Float class).
Thus, by providing an 8-byte Float class, code would not loose precicion
(although some memory is wasted when porting from VW).
As Digitalk is dead now, things could (should) now be made to be compatible with VW.
Notice that ST/X provides an alias called Double, and an extra ShortFloat class, which has 4-byte
instances.

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

Representation:
        64bit double precision IEE floats
        53 bit mantissa,
        11 bit exponent,
        15 decimal digits (approx)

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

Related information:

    Number
    ShortFloat
    LongFloat
    Fraction
    FixedPoint
    Integer
    Complex
    FloatArray
    DoubleArray

Class protocol:

 binaryDefinitionFrom: aStream manager: manager

 readBinaryIEEEDoubleFrom: aStream

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

 readBinaryIEEEDoubleFrom: aStream into: aFloat

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

 storeBinaryIEEEDouble: aFloat on: aStream

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

 initialize

 NaN

return the constant NaN (not a Number).
Do not use (yet) - for now, this is only defined for a
few selected architectures.

 e

return the constant e as Float

 ln2

dont expect this many valid digits on all machines;

 pi

return the constant pi as Float

 sqrt2

dont expect this many valid digits on all machines;

 unity

return the neutral element for multiplication (1.0) as Float

 zero

return the neutral element for addition (0.0) as Float

 decodeFromIslandCopierStream: byteStream

 basicNew

return a new float - here we return 0.0
- floats are usually NOT created this way ...
Its implemented here to allow things like binary store & load
of floats. (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 Float 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 high speed string decomposition into numbers,
especially for mass-data.

 fromSchemaString: aString

Answer a float. Convert the schema string into a format dolphin can work with.
Throw an error if the string is a lexical representation that I cant convert to a float, (so I can catch INF,-INF,NaN)

 fromVAXFloatBytes: b1 b2: b2 b3: b3 b4: b4

creates a double, given the four vax float bytes to an ieee double.
For NaNs and Infinity, nil is returned.

 readFrom: aStringOrStream onError: exceptionBlock

read a float from a string

 exponentCharacter

 hasSharedInstances

return true if this class has shared instances, that is, instances
with the same value are identical.
Although not really shared, floats should be treated
so, to be independent of the implementation of the arithmetic methods.

 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 11 bits are available:
seeeeeee eeeemmmm mmmmmmmm mmmmmmmm mmmmmmmm mmmmmmmm mmmmmmmm mmmmmmmm

 numBitsInMantissa

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

 precision

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

 radix

answer the radix of a Floats 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.

 storeBinaryDefinitionOn: stream manager: manager

store the receiver in a binary format on stream.
This is an internal interface for binary storage mechanism.

 asDouble

ST80 compatibility: return a double with receivers value.
our floats are the identical to ST80 doubles

 asFloat

return a float with same value - thats me

 asInteger

return an integer with same value - might truncate

 asLongFloat

return a longFloat with same value as receiver

 asShortFloat

return a shortFloat with same value as receiver.
CAVEAT: should raise an error if the receiver exceeds the float range.

 asTrueFraction

Answer a fraction or integer that EXACTLY represents self,
a double precision IEEE floating point number.
Floats are stored in the same form on all platforms.
(Does not handle gradual underflow or NANs.)
By David N. Smith with significant performance
improvements by Luciano Esteban Notarfrancesco.
(Version of 11April97)

 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

 exp

return e raised to the power of the receiver

 ln

return the natural logarithm of myself.
Raises an exception, if the receiver is less or equal to zero.

 log10

return the base-10 logarithm of myself.
Raises an exception, if the receiver is less or equal to zero.

 raisedTo: aNumber

return self raised to the power of aNumber

 sqrt

return the square root of myself.
Raises an exception, if the receiver is less than zero.

 schemaDisplayString

Answer a valid XMLSchema lexical representation of the float

 printString

return a printed representation of the receiver;
if not specified otherwise (by setting DefaultPrintFormat),
6 valid digits are printed.
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.

 absDecimalPrintOn: aStream digits: digits

Place a string representation of the receiver's abs value
on <aStream> using <digits> significant digits, using decimal notation.
This is a helper for printf.

 absPrintOn: aStream digits: digits

Place a string representation of the receiver's abs value on <aStream> using
<digits> significant digits.
This is a helper for printf.

 absScientificPrintOn: aStream digits: digits

Place a string representation of the receiver's abs value on <aStream> using <digits> significant
digits, using scientific notation.
This is a helper for printf.

 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.

 basicSize

return the size in bytes of the float.

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 float's 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.

 isInfinite

return true, if the receiver is an infinite float (Inf).
These are not created by ST/X float operations (they raise an exception);
however, inline C-code could produce them ...
Redefined here for speed

 isLiteral

return true, if the receiver can be used as a literal constant in ST syntax
(i.e. can be used in constant arrays)

 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, 64 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

 traceInto: aRequestor level: level from: referrer

double dispatch into tracer, passing my type implicitely in the selector

 arcCos

return the arccosine of the receiver (as radians).
Raises an exception, if the receiver is not in -1..1

 arcCosh

return the hyperbolic arccosine of the receiver.

 arcSin

return the arcsine of myself (I am interpreted as radians).
Raises an exception, if the receiver is not in -1..1

 arcSinh

return the hyperbolic arcsine of the receiver.

 arcTan

return the arctangent of the receiver (as radians)

 arcTan2: x

return the atan2(self,x)

 arcTan: denominator

 arcTanh

return the hyperbolic arctangent of the receiver.

 cos

return the cosine of the receiver (interpreted as radians)

 cosh

return the hyperbolic cosine of the receiver

 sin

return the sine of the receiver (interpreted as radians)

 sinh

return the hyperbolic sine of the receiver

 tan

return the tangens of the receiver (interpreted as radians)

 tanh

return the hyperbolic tangens of the receiver

 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 integer nearest the receiver towards negative infinity as a float.
This is much like #floor, 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.

 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.