eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ShortFloat':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: ShortFloat


Inheritance:

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

Package:
stx:libbasic
Category:
Magnitude-Numbers
Version:
rev: 1.295 date: 2023/08/22 11:03:43
user: cg
file: ShortFloat.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


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

In contrast to Floats (which use the C-compiler's 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. The reason was to make ST/X's floats compatible
to bothe VisualWorks and other Smalltalks, which use C-doubles for the Float class
(i.e. VisualST and V'Age).
Thus, STX's Float precision is not worse than that of other ST's.

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

Math functions return double precision results.

Representation:
        32bit single precision IEEE floats
        23 bit mantissa + 1 hidden bit, providing a precision of 24bits,
        8 bit exponent,
        6 decimal digits (approx.)

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


[aliases:]
    FloatE  (ANSI)
    Float32

copyright

COPYRIGHT (c) 1996 by Claus Gittinger All Rights Reserved This software is furnished under a license and may be used only in accordance with the terms of that license and with the inclusion of the above copyright notice. This software may not be provided or otherwise made available to, or used by, any other person. No title to or ownership of the software is hereby transferred.

Class protocol:

accessing
o  defaultPrintFormat
'.6' by default, I will print up to 6 digits

o  defaultPrintFormat: aFormatString
the formatString must be of the form '.n'.

binary storage
o  readBinaryIEEESingleFrom: aStream
read a float value from the binary stream, aStream,
interpreting the next bytes as an IEEE formatted 4-byte float.
The bytes are read in the native byte order (i.e.lsb on intel)

o  readBinaryIEEESingleFrom: aStream MSB: msbFirst
read a float value from the binary stream, aStream,
interpreting the next bytes as an IEEE formatted 4-byte float.
The bytes are read in the soecified byte order

o  readBinaryIEEESingleFrom: aStream into: aBasicNewShortFloat
read a float value from the binary stream, aStream,
interpreting the next bytes as an IEEE formatted 4-byte float.
The bytes are read in the native byte order (i.e.lsb on intel)

o  readBinaryIEEESingleFrom: aStream into: aBasicNewShortFloat MSB: msb
read a float value from the binary stream, aStream,
interpreting the next bytes as an IEEE formatted 4-byte float.
If msb is true, the stream bytes are most-significant-first.

o  storeBinaryIEEESingle: aFloat on: aStream
store aFloat as an IEEE formatted 4-byte float
onto the binary stream, aStream.
The bytes are written in the native byte order (i.e.lsb on intel)

o  storeBinaryIEEESingle: aFloat on: aStream MSB: msb
store aFloat as an IEEE formatted 4-byte float
onto the binary stream, aStream.
If msb is true, the stream bytes are written most-significant-first.

class initialization
o  initialize
print up to 6 valid digits

Usage example(s):

     Epsilon := nil
     self initialize.
     Epsilon -> 1.192093e-07

coercing & converting
o  coerce: aNumber
convert the argument aNumber into an instance of the receiver (class) and return it.

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

constants
o  NaN
return a shortFloat which represents not-a-Number (i.e. an invalid number)

Usage example(s):

     self NaN

o  e
return the constant e as ShortFloat

o  eBias
Answer the exponent's bias;
that is the offset of the zero exponent when stored

Usage example(s):

     1.0 asShortFloat numBitsInExponent 8
     1.0 asShortFloat eBias             127
     1.0 asShortFloat emin              -126
     1.0 asShortFloat emax              127
     1.0 asShortFloat fmin              1.175494e-38
     1.0 asShortFloat fmax              3.402823e+38

     1.0 numBitsInExponent 11
     1.0 eBias             1023
     1.0 emin              -1022
     1.0 emax              1023
     1.0 fmin              2.2250738585072E-308
     1.0 fmax              1.79769313486232E+308

o  halfPi
return the constant pi/2 as ShortFloat

o  infinity
return a shortFloat which represents positive infinity (for my instances)

o  ln10
return the constant natural logarithm log(10) as a shortFloat

Usage example(s):

     ShortFloat ln10

o  ln2
return the natural logarithm of 2 as a shortFloat

Usage example(s):

     self ln2

o  negativeInfinity
return a shortFloat which represents negative infinity (for my instances).
Warning: do not compare equal against infinities;
instead, check using isFinite or isInfinite

o  phi
return the constant phi as ShortFloat

o  pi
return the constant pi as ShortFloat

o  sqrt2
return the constant sqrt(2) as ShortFloat

Usage example(s):

Sqrt2 := Float sqrt2 asShortFloat

o  sqrt3
return the constant sqrt(3) as ShortFloat

Usage example(s):

Sqrt3 := Float sqrt3 asShortFloat

o  sqrt5
return the constant sqrt(5) as ShortFloat

Usage example(s):

Sqrt5 := Float sqrt5 asShortFloat

o  unity
return the neutral element for multiplication (1.0) as ShortFloat

o  zero
return the neutral element for addition (0.0) as ShortFloat

instance creation
o  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.

o  basicNew: size
(comment from inherited method)
return an instance of myself with anInteger indexed variables.
If the receiver-class has no indexed instvars, this is only allowed
if the argument, anInteger is zero.
** Do not redefine this method in any class **

o  fastFromString: aString at: startIndex
return the next ShortFloat from the string starting at startIndex.
No spaces are skipped.
Raises an exception, if the startIndex is not valid.
Returns garbage if the argument string is not a valid short float number.

This is a specially tuned entry (using a low-level C-call to atof).
It has been added to allow high speed string decomposition
into numbers, especially for mass-data (reading millions of floats).
This is roughly 5 times faster than the full-blown inherited fromString:

Usage example(s):

     ShortFloat fastFromString:'123.45' at:1
     ShortFloat fastFromString:'123.45' at:2
     ShortFloat fastFromString:'123.45E4' at:1
     ShortFloat fastFromString:'hello123.45E4' at:6
     ShortFloat fastFromString:'12345' at:1
     ShortFloat fastFromString:'12345' at:2
     ShortFloat fastFromString:'12345' at:3
     ShortFloat fastFromString:'12345' at:4
     ShortFloat fastFromString:'12345' at:5
     ShortFloat fastFromString:'12345' at:6
     ShortFloat fastFromString:'12345' at:0
     ShortFloat fastFromString:'hello123.45E4' at:1

Usage example(s):

     (Time toRun:[
        1000000 timesRepeat:[
            ShortFloat fastFromString:'123.45' at:1
        ]
     ]) / 1000000 200ns

o  fromIEEE32Bit: anInteger
creates a float, given the four native float bytes as an integer

Usage example(s):

     ShortFloat fromIEEE32Bit:(#[64 73 15 219] asInteger)
     #[64 73 15 219] floatAt:1 MSB:true.                        3.14159   

o  fromInteger: anInteger
return a new short float, given an integer value

Usage example(s):

     ShortFloat fromInteger:123                               -> 123.0
     ShortFloat fromInteger:(12 factorial)                    -> 4.790016e+08
     ShortFloat fromInteger:(100 factorial)                   -> 9.33262154439442e+157
     (100 factorial) asShortFloat                             -> 9.33262154439442e+157 -- floats are inexact
     100 factorial - ((100 factorial) asShortFloat asInteger) -- floats are inexact

queries
o  defaultPrintPrecision
the default number of digits when printing

Usage example(s):

     ShortFloat defaultPrintPrecision
     Float defaultPrintPrecision
     LongFloat defaultPrintPrecision

o  defaultPrintfPrecision
the default number of digits when printing with printf's %f format.
Notice, that the C-language standard states that this should be 6;
however, we can adjust it on a per-class basis.

o  emax
The largest exponent value allowed by instances of this class.

Usage example(s):

     1.0 asShortFloat fmax  -> 1.189731495357231765E+4932
     1.0 asShortFloat fmin  -> 3.362103143112093506E-4932
     1.0 asShortFloat emin  -> -16381
     1.0 asShortFloat emax  -> 128

o  emin
The smallest exponent value allowed by (normalized) instances of this class.

Usage example(s):

     1.0 asShortFloat fmax  -> 3.402823e+38
     1.0 asShortFloat fmin  -> 1.175494e-38
     1.0 asShortFloat emin  -> -126
     1.0 asShortFloat emax  -> 127

o  epsilon
return the maximum relative spacing of instances of mySelf
(i.e. the value-delta of the least significant bit)
according to ISO C standard;
Ada, C, C++ and Python language constants;
Mathematica, MATLAB and Octave; and various textbooks
see https://en.wikipedia.org/wiki/Machine_epsilon

Usage example(s):

     ShortFloat epsilon  => 1.19209e-07

o  exponentCharacter
return the character used to print between mantissa an exponent.
Also used by the scanner when reading numbers.

o  fmax
The largest exponent value allowed by instances of this class.

Usage example(s):

     1.0 asShortFloat fmax  -> 3.402823e+38
     1.0 asShortFloat fmin  -> 1.175494e-38
     1.0 asShortFloat emin  -> -125
     1.0 asShortFloat emax  -> 128

o  fmaxDenormalized
the largest denormalized value which can be represented
by instances of this class.
Should actually be sent to the instance,
because of IEEEFloat, which has instance-specific representation

o  fmin
the smallest normalized non-zero value which can be represented
by instances of this class;
should actually be sent to the instance,
because of IEEEFloat, which has instance-specific representation

Usage example(s):

     1.0 asShortFloat fmax              -> 3.40282346638529E+38
     1.0 asShortFloat fmin              -> 1.175494e-38
     1.0 asShortFloat fminDenormalized  -> 1.401298e-45
     1.0 asShortFloat emin  -> -125
     1.0 asShortFloat emax  -> 128

o  fminDenormalized
the smallest non-zero value which can be represented
by instances of this class;
should actually be sent to the instance,
because of IEEEFloat, which has instance-specific representation

Usage example(s):

     ShortFloat fmin              -> 1.175494e-38
     ShortFloat fminDenormalized  -> 1.401298e-45

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

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

Usage example(s):

     1.0 asShortFloat numBitsInExponent

o  numBitsInMantissa
answer the number of bits in the mantissa (the significant).
This is an IEEE single (binary32), where 23 bits are available
The hidden bit is not counted here:
seeeeeee emmmmmmm mmmmmmmm mmmmmmmm

Usage example(s):

     1.0 asShortFloat numBitsInExponent 8
     1.0 asShortFloat numBitsInMantissa 23
     1.0 asShortFloat precision         24
     1.0 asShortFloat decimalPrecision  7
     1.0 asShortFloat eBias             127
     1.0 asShortFloat emin              -126
     1.0 asShortFloat emax              127
     1.0 asShortFloat fmin              1.17549435082229E-38
     1.0 asShortFloat fmax              3.40282346638529E+38

o  precision
answer the precision (the number of bits in the mantissa) 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)
the hidden bit is included here

Usage example(s):

     self numBitsInMantissa
     self precision

o  radix
answer the radix of a ShortFloat's exponent
This is an IEEE float, which is represented as binary


Instance protocol:

arithmetic
o  * aNumber
return the product of the receiver and the argument.

o  + aNumber
return the sum of the receiver and the argument, aNumber

o  - aNumber
return the difference of the receiver and the argument, aNumber

o  / aNumber
return the quotient of the receiver and the argument, aNumber

o  abs
return the absolute value of the receiver
reimplemented here for speed

Usage example(s):

     3.0 asShortFloat abs
     -3.0 asShortFloat abs

o  negated
return myself negated

Usage example(s):

     0 negated
     0.0 negated
     0.0 asShortFloat negated

o  rem: aNumber
return the floating point remainder of the receiver and the argument, aNumber

o  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).
It is only defined if the argument's type is the same as the receiver's.

Usage example(s):

      0.0 asShortFloat uncheckedDivide:0
      1.0 asShortFloat uncheckedDivide:0.0

coercing & converting
o  asFloat
return a Float (i.e. an IEEE double) with same value as the receiver.
Redefined for performance (machine can do it faster)

Usage example(s):

     1.0 asShortFloat asFloat

o  asInteger
return an integer with same value - might truncate

Usage example(s):

     12345.0 asShortFloat asInteger
     1e15 asShortFloat asInteger

o  asLongFloat
return a LongFloat with same value as the receiver

o  asQuadFloat
( an extension from the stx:libbasic2 package )
return a QuadFloat with same value as the receiver

o  asShortFloat
return a ShortFloat with same value as the receiver - that's me

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

comparing
o  < aNumber
return true, if the argument is greater

o  <= aNumber
return true, if the argument is greater or equal

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

o  > aNumber
return true, if the argument is less

o  >= aNumber
return true, if the argument is less or equal

o  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.

Usage example(s):

     1.2345 hash
     1.2345 asShortFloat hash
     1.0 hash
     1.0 asShortFloat hash
     0.5 asShortFloat hash
     0.25 asShortFloat hash
     0.5 hash
     0.25 hash

o  isAlmostEqualTo: aNumber nEpsilon: nE
return true, if the argument, aNumber represents almost the same numeric value
as the receiver, false otherwise.

nE is the number of minimal float distances, that the numbers may differ and
still be considered equal.

For background information why floats need this
read: http://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/

Usage example(s):

	67329.234 asShortFloat isAlmostEqualTo:67329.23401 asShortFloat nEpsilon:1  -> true
	1.0 asShortFloat isAlmostEqualTo:1.0000001 asShortFloat nEpsilon:1          -> true
	1.0 asShortFloat isAlmostEqualTo:1.0000001 nEpsilon:1                       -> true
	1.0 asShortFloat isAlmostEqualTo:1.000001 nEpsilon:1                        -> false
	1.0 asShortFloat isAlmostEqualTo:-1.0 nEpsilon:1                            -> false
	1.0 asShortFloat isAlmostEqualTo:1 nEpsilon:1                               -> true
	0.0 asShortFloat isAlmostEqualTo:0.0000001 asShortFloat nEpsilon:1          -> true
	0.0 asShortFloat isAlmostEqualTo:0.000001 asShortFloat nEpsilon:1           -> false
	0.0 asShortFloat isAlmostEqualTo:self epsilon nEpsilon:1                    -> true
	0.0 asShortFloat - 1.192093e-07 asShortFloat

o  ~= aNumber
return true, if the arguments value are not equal

copying
o  deepCopy
return a deep copy of myself
- because storing into floats is not recommended/allowed, its ok to return the receiver

o  deepCopyUsing: aDictionary postCopySelector: postCopySelector
return a deep copy of myself
- because storing into floats is not recommended/allowed, its ok to return the receiver

o  shallowCopy
return a shallow copy of the receiver

o  simpleDeepCopy
return a deep copy of the receiver
- because storing into floats is not recommended/allowed, its ok to return the receiver

double dispatching
o  lessFromLongFloat: aNumber
aLongFloat does not know how to compare to the receiver -
Return true if aLongFloat < self.
retry the operation by coercing to higher generality

mathematical functions
o  fastInverseSqrt
return a rough but fast approximation of (1 / self sqrt).
The error is some 1%, which is ok for many 3D computations or physics simulations.
Do not use this for now: it is non-portable and probably not speeding things up
much, unless inlined into the sender code.
The code is here as a reminder and might be later used as a hint for the inliner
(to speed up 3D computations, for example).
see: http://betterexplained.com/articles/understanding-quakes-fast-inverse-square-root/

Usage example(s):

     10.0 asShortFloat fastInverseSqrt  
     (1 / 10.0 asShortFloat sqrt)       

Usage example(s):

     |a b t0 t1 t2|

     a := 345 asShortFloat.
     'measure an empty loop'.
     t0 := Time millisecondsToRun:[
        1000000 timesRepeat:[
        ]
     ].
     t1 := Time millisecondsToRun:[
        1000000 timesRepeat:[
            a fastInverseSqrt
        ]
     ].
     t2 := Time millisecondsToRun:[
        1000000 timesRepeat:[
            (1 / a sqrt)
        ]
     ].
     Transcript show:'empty: '; showCR:t0.
     Transcript show:'fast: '; showCR:t1.
     Transcript show:'regular: '; showCR:t2.

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

Usage example(s):

     0 asFloat ln
     Number trapInfinity:[ 0 asFloat ln ]

     10 asFloat ln       2.30258509299405
     10 asShortFloat ln  2.302585
     10 asLongFloat ln   2.302585092994045684
     10 asQDouble ln     2.30258509299404568402

     50 asFloat ln       3.91202300542815
     50 asShortFloat ln  3.912023
     50 asLongFloat ln   3.912023005428146059
     50 asQDouble ln     3.91202300542814605862

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

Usage example(s):

     0 asShortFloat log10
     Number trapInfinity:[ 0 asShortFloat log10 ]

     10 asFloat log10       1.0
     10 asShortFloat log10  1.0
     10 asLongFloat log10   1.0
     10 asQDouble log10     1.00000000000000000000000000000000000000000

     50 asFloat log10       1.69897000433602
     50 asShortFloat log10  1.69897
     50 asLongFloat log10   1.698970004336018805
     50 asQDouble log10     1.69897000433601880478626110527550697323181

printing & storing
o  printOn: aStream
append a printed representation of the receiver to
the argument, aStream.

I use #printString instead of #printOn: as basic print mechanism.

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

Usage example(s):

     self pi printString.              '3.141593'
     1.234 asShortFloat printString.   '1.234'
     1.0 asShortFloat printString.     '1.0'
     1e10 asShortFloat printString.    '1e+10'
     1.2e3 asShortFloat printString.   '1200.0'
     1.2e30 asShortFloat printString.  '1.2e+30'
     (1.0 uncheckedDivide:0) asShortFloat printString.   
     (0.0 uncheckedDivide:0) asShortFloat printString.   

     self pi printString.
     DefaultPrintFormat := '.3'.
     self pi printString.
     DefaultPrintFormat := '.7'.

     DecimalPointCharacterForPrinting := $,.
     1.234 asShortFloat printString.
     1.0 asShortFloat printString.
     1e10 asShortFloat printString.
     1.2e3 asShortFloat printString.
     1.2e30 asShortFloat printString.
     (1.0 uncheckedDivide:0) asShortFloat printString.
     (0.0 uncheckedDivide:0) asShortFloat printString.
     DecimalPointCharacterForPrinting := $.

o  printStringWithFormat: format
return a printed representation of the receiver;
fmt must be of the form: .nn, where nn is the number of digits.
To print 6 valid digits, use printStringWithFormat:'.6'
For Floats, the default used in printString, is 15 (because its a double);
for ShortFloats, it is 6 (because it is a float)

o  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 the format string must be correct and something like %f.
Also, the resulting string may not be longer than 1000 bytes -
since that's the (static) size of the buffer.

This method is NONSTANDARD and may be removed without notice.

WARNING: 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.

Usage example(s):

     ShortFloat pi printfPrintString:'%%lg -> %lg'
     ShortFloat pi printfPrintString:'%%lf -> %lf'
     ShortFloat pi printfPrintString:'%%7.5lg -> %7.5lg'
     ShortFloat pi printfPrintString:'%%G -> %G'
     ShortFloat pi printfPrintString:'%%F -> %F'
     ShortFloat pi printfPrintString:'%%7.5G -> %7.5G'
     ShortFloat pi printfPrintString:'%%7.5F -> %7.5F'

o  storeOn: aStream
append a printed representation of the receiver to
the argument, aStream.

I use #storeString instead of #storeOn: as basic store mechanism.

o  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.

Usage example(s):

	0.1 asShortFloat storeString
	((Array new:10 withAll:0.1 asShortFloat) inject:0 into:[:v :sumSoFar| sumSoFar + v]) storeString
	1.0 asShortFloat storeString
	1.234 asShortFloat storeString
	1e10 asShortFloat storeString
	1.2e3 asShortFloat storeString
	1.2e30 asShortFloat storeString
	Float pi asShortFloat storeString
	(1.0 uncheckedDivide:0) asShortFloat storeString
	(0.0 uncheckedDivide:0) asShortFloat storeString

     notice that the storeString is NOT affected by DecimalPointCharacterForPrinting:

	DecimalPointCharacterForPrinting := $,.
	1.234 asShortFloat storeString.
	1.0 asShortFloat storeString.
	1e10 asShortFloat storeString.
	1.2e3 asShortFloat storeString.
	1.2e30 asShortFloat storeString.
	(1.0 uncheckedDivide:0) asShortFloat storeString.
	(0.0 uncheckedDivide:0) asShortFloat storeString.
	DecimalPointCharacterForPrinting := $.

private accessing
o  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.

o  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.

o  byteAt: index
(comment from inherited method)
return the byte at index.
This is only allowed for non-pointer indexed objects
(i.e. byteArrays, wordArrays, floatArrays etc.).
The receiver's indexed instvars are treated as an uninterpreted
collection of bytes.
Only useful with binary storage.

o  byteAt: index put: newByte
(comment from inherited method)
set the byte at index.
This is only allowed for non-pointer indexed objects
(i.e. byteArrays, wordArrays, floatArrays etc.).
The receiver's indexed instvars are treated as an uninterpreted
collection of bytes.
Only useful with binary storage.

o  signBit
return the sign bit (1 for negative).
notice that floats can represent a negative zero,
and signBit handles that,
whereas sign would return 0 for both positive and negative zeros

Usage example(s):

     1.0 asShortFloat signBit        -> 0
     -1.0 asShortFloat signBit       -> 1
     ShortFloat zero signBit         -> 0
     ShortFloat negativeZero signBit -> 1

queries
o  exponentBits
return the bits of my exponent.
These might be biased.

Usage example(s):

     1.0 asShortFloat exponentBits   127
     10.0 asShortFloat exponentBits  130
     0.125 asShortFloat exponentBits 124
     0.1 asShortFloat exponentBits   123
     0.0 asShortFloat exponentBits   0
     ShortFloat fmin exponentBits    1
     ShortFloat fminDenormalized exponentBits 0

o  hasIEEEFormat
(comment from inherited method)
HalfFloat isIEEEFormat true
ShortFloat isIEEEFormat true
Float isIEEEFormat true
LongFloat isIEEEFormat true
QuadFloat isIEEEFormat true
OctaFloat isIEEEFormat true
QDouble isIEEEFormat false
LargeFloat isIEEEFormat false

o  mantissaBits
return the bits of my mantissa (excl. any hidden bit).
I.e. this returns the normalized mantissaBits as an integer

Usage example(s):

     1.0 asShortFloat mantissaBits   0
     10.0 asShortFloat mantissaBits  2097152
     0.125 asShortFloat mantissaBits 0
     0.1 asShortFloat mantissaBits   5033165

o  mantissaWithHiddenBits
return the bits of my mantissa (incl. any hidden bit).
I.e. this returns the denormalized mantissaBits.

Usage example(s):

     0 asShortFloat mantissaWithHiddenBits     0
     1.0 asShortFloat mantissaWithHiddenBits   8388608
     10.0 asShortFloat mantissaWithHiddenBits  10485760
     0.125 asShortFloat mantissaWithHiddenBits 8388608
     0.1 asShortFloat mantissaWithHiddenBits   13421773
     ShortFloat fmin mantissaWithHiddenBits    8388608
     ShortFloat fminDenormalized mantissaWithHiddenBits

o  nextFloat: countULPs
answer the next float count places (ulps) after (or before if count is negative) myself.
One ulp is the distance to the next/previous representable float,
and this returns the float which is countUlps away from me.
Notice that ulps depend on the receiver: an ulp away from 1e100 has a different
value than 1 ulp away from 1e-100.
Thus, ulps are perfect for 'almost equal' comparisons.

Usage example(s):

     (1.0 asShortFloat nextFloat:2) storeString
     (67329.234 asShortFloat nextFloat:1) storeString
     (ShortFloat fmaxDenormalized nextFloat:1) storeString
     (ShortFloat fmin nextFloat:-1) storeString
     (0.0 asShortFloat nextFloat:1) storeString
     (0.0 asShortFloat nextFloat:-1) storeString
     ShortFloat NaN nextFloat:100000
     ShortFloat infinity nextFloat:100000
     ShortFloat fmax nextFloat:1
     ShortFloat fmax nextFloat:100

o  ulpFrom: anotherFLoat
the distance in ULPs between two floats (anotherFloat - self)

Usage example(s):

     (1.0 nextFloat:1) ulpFrom:1.0
     (1.0 asShortFloat nextFloat:1) ulpFrom:1.0 asShortFloat
     1.0 ulpFrom:(1.0 nextFloat:1)
     (1.0 asShortFloat nextFloat:1) ulpFrom:1.0 asShortFloat
     1.0 ulpFrom:(1.0 nextFloat:10)
     (1.0 asShortFloat nextFloat:10) ulpFrom:1.0 asShortFloat

special access
o  exponent
extract a normalized float's (unbiased) 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

Usage example(s):

     4.0 asShortFloat exponent      => 3
     2.0 asShortFloat exponent      => 2
     1.0 asShortFloat exponent
     0.5 asShortFloat exponent      => 0
     0.25 asShortFloat exponent     => -1
     0.00000011111 asShortFloat exponent

     ShortFloat NaN exponent         -> error

o  mantissa
extract a normalized float's mantissa (as ShortFloat).
That is a float of the same type as the receiver,
such that:
(f mantissa) * (2 ^ f exponent) = f
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

Usage example(s):

     0.0 asShortFloat exponent
     0.0 asShortFloat mantissa

     1.0 asShortFloat exponent   -> 1
     1.0 asShortFloat mantissa   -> 0.5
     1e1000 asShortFloat mantissa

     0.5 asShortFloat exponent
     0.5 asShortFloat mantissa

     0.25 asShortFloat exponent
     0.25 asShortFloat mantissa

     0.00000011111 asShortFloat exponent
     0.00000011111 asShortFloat mantissa

     self assert:(1.0 asShortFloat mantissa * (2 raisedTo:1.0 asShortFloat exponent)) = 1.0 asShortFloat.
     self assert:(100.0 asShortFloat mantissa * (2 raisedTo:100.0 asShortFloat exponent)) = 100.0 asShortFloat.
     self assert:(10e15 asShortFloat mantissa * (2 raisedTo:10e15 asShortFloat exponent)) = 10e15 asShortFloat.
     self assert:(10e-15 asShortFloat mantissa * (2 raisedTo:10e-15 asShortFloat exponent)) = 10e-15 asShortFloat.

     ShortFloat NaN mantissa   -> error
     ShortFloat NaN exponent   -> error

testing
o  isFinite
return true, if the receiver is a finite float (not NaN and not +/-INF)

Usage example(s):

        1.0 asShortFloat isFinite
        (0.0 asShortFloat uncheckedDivide: 0.0) isFinite
        (1.0 asShortFloat uncheckedDivide: 0.0) isFinite

o  isFloat32
Answer whether the receiver is a 32bit single precision float.
Always true here.

o  isInfinite
return true, if the receiver is an infinite float (+Inf or -Inf).
These are not usually created by ST/X float operations (they raise an exception);
however, inline C-code could produce them.

Usage example(s):

        1.0 asShortFloat isInfinite
        ShortFloat NaN isInfinite
        ShortFloat infinity isInfinite
        ShortFloat negativeInfinity isInfinite
        (0.0 asShortFloat uncheckedDivide: 0.0 asShortFloat) isInfinite  false
        (1.0 asShortFloat uncheckedDivide: 0.0 asShortFloat) isInfinite  true
        (-1.0 asShortFloat uncheckedDivide: 0.0 asShortFloat) isInfinite true
 
        (0.0  uncheckedDivide: 0.0 ) isInfinite  false
        (1.0  uncheckedDivide: 0.0 ) isInfinite  true
        (-1.0  uncheckedDivide: 0.0 ) isInfinite true

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

Usage example(s):

     1.0 asShortFloat isNaN
     (0.0 asShortFloat uncheckedDivide: 0.0) isNaN
     (0.0 asShortFloat uncheckedDivide: 0.0 asShortFloat) isNaN

o  isNegativeZero
many systems have two float.Pnt zeros

Usage example(s):

     0.0 asShortFloat isNegativeZero   false
     -0.0 asShortFloat isNegativeZero  true

o  isShortFloat
return true, if the receiver is some kind of short floating point number (iee single precision)

o  isZero
return true, if the receiver is zero

o  negative
return true if the receiver is less than zero.
-0.0 is positive for now.

Usage example(s):

        0.0 asShortFloat negative
        -0.0 asShortFloat negative
        1.0 asShortFloat negative
        -1.0 asShortFloat negative
        (1.0 uncheckedDivide: 0.0) asShortFloat negative
        (-1.0 uncheckedDivide: 0.0) asShortFloat negative

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

Usage example(s):

     1.2 numberOfBits
     1.2 asShortFloat numberOfBits

o  positive
return true if the receiver is greater or equal to zero (not negative)
0.0 and -0.0 are positive for now.

Usage example(s):

        0.0 asShortFloat positive
        -0.0 asShortFloat positive
        1.0 asShortFloat positive
        -1.0 asShortFloat positive
        (1.0 uncheckedDivide: 0.0) asShortFloat positive
        (-1.0 uncheckedDivide: 0.0) asShortFloat positive

o  strictlyPositive
return true if the receiver is greater than zero

truncation & rounding
o  ceiling
return the smallest integer which is greater or equal to the receiver.

Usage example(s):

     0.5 asShortFloat ceiling
     -0.5 asShortFloat ceiling

o  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.

Usage example(s):

     0.5 asShortFloat ceilingAsFloat
     -0.5 asShortFloat ceilingAsFloat
     -1.5 asShortFloat ceilingAsFloat

o  floor
return the integer nearest the receiver towards negative infinity.

Usage example(s):

     0.5 asShortFloat floor
     -0.5 asShortFloat floor

o  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.

Usage example(s):

     0.5 asShortFloat floorAsFloat
     -0.5 asShortFloat floorAsFloat

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

Usage example(s):

     1.6 asShortFloat fractionPart + 1.6 asShortFloat truncated
     -1.6 asShortFloat fractionPart + -1.6 asShortFloat truncated

     1.0 asShortFloat fractionPart
     0.5 asShortFloat fractionPart
     0.25 asShortFloat fractionPart
     3.14159 asShortFloat fractionPart
     12345673.14159 asShortFloat fractionPart           - not enough precision
     123456731231231231.14159 asShortFloat fractionPart - not enough precision

o  integerAndFractionParts
return the integer and the fraction part of the receiver as a pair
of floats (i.e. the result of the modf function)
Adding the parts gives the original value

Usage example(s):

     0.5 asShortFloat integerAndFractionParts
     -0.5 asShortFloat integerAndFractionParts
     12345.6789 asShortFloat integerAndFractionParts
     -12345.6789 asShortFloat integerAndFractionParts

o  rounded
return the receiver rounded to the nearest integer

Usage example(s):

     0.4 asShortFloat rounded
     0.5 asShortFloat rounded
     0.6 asShortFloat rounded
     -0.4 asShortFloat rounded
     -0.5 asShortFloat rounded
     -0.6 asShortFloat rounded
     1e32 asShortFloat rounded

o  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.

Usage example(s):

     0.4 asShortFloat rounded
     0.5 asShortFloat rounded
     0.6 asShortFloat rounded
     -0.4 asShortFloat rounded
     -0.5 asShortFloat rounded
     -0.6 asShortFloat rounded

     0.4 asShortFloat roundedAsFloat
     0.5 asShortFloat roundedAsFloat
     0.6 asShortFloat roundedAsFloat
     -0.4 asShortFloat roundedAsFloat
     -0.5 asShortFloat roundedAsFloat
     -0.6 asShortFloat roundedAsFloat

o  truncated
return the receiver truncated towards zero as an integer

Usage example(s):

     0.5 asShortFloat truncated
     -0.5 asShortFloat truncated
     0.5 asShortFloat truncatedAsFloat
     -0.5 asShortFloat truncatedAsFloat

o  truncatedAsFloat
return the receiver truncated towards zero as a short 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.

Usage example(s):

     0.5 asShortFloat truncated
     -0.5 asShortFloat truncated
     0.5 asShortFloat truncatedAsFloat
     -0.5 asShortFloat truncatedAsFloat



ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Fri, 13 Dec 2024 14:09:21 GMT