eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Integer':
Home

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

Class: Integer

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--ArithmeticValue
         |
         +--Number
            |
            +--Integer
               |
               +--LargeInteger
               |
               +--SmallInteger
Package:
stx:libbasic
Category:
Magnitude-Numbers
Version:
rev: 1.423 date: 2019/07/22 17:46:19
user: cg
file: Integer.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


abstract superclass for all integer numbers.
See details in concrete subclasses LargeInteger and SmallInteger.

Mixed mode arithmetic:
    int <op> int         -> int
    int <op> fraction    -> fraction
    int <op> float       -> float
    int <op> fix         -> fix; scale is fix's scale

Related information:

    Number
    LargeInteger
    SmallInteger
    Float
    ShortFloat
    Fraction
    FixedPoint

Class protocol:

Compatibility-Squeak
o  readFrom: aStringOrStream base: aBase
for squeak compatibility

Signal constants
o  bcdConversionErrorSignal
return the signal which is raised when bcd conversion fails
(i.e. when trying to decode an invalid BCD number)

class initialization
o  initialize
(comment from inherited method)
setup the signals

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

constants
o  epsilon
return the maximum relative spacing of instances of mySelf
(i.e. the value-delta of the least significant bit)

usage example(s): 

     2 sqrt_withAccuracy:(Integer epsilon)
     2 sqrt_withAccuracy:1

o  unity
return the neutral element for multiplication (1)

o  zero
return the neutral element for addition (0)

instance creation
o  byte1: b1 byte2: b2 byte3: b3 byte4: b4
Squeak compatibility:
Return an Integer given four value bytes.
The returned integer is either a Small- or a LargeInteger
(on 32bit systems - on 64bit systems, it will be always a SmallInteger)

usage example(s): 

     (Integer byte1:16r10 byte2:16r32 byte3:16r54 byte4:16r76) hexPrintString
     (Integer byte1:16r00 byte2:16r11 byte3:16r22 byte4:16r33) hexPrintString

o  fastFromString: aString at: startIndex
return the next unsigned Integer from the string
as a decimal number, starting at startIndex.
The number must be in the native machine's int range
(i.e. 64bit or 32bit depending on the cpu's native pointer size);
However, for portability, only use it for 32bit numbers (uint32s).
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 small integer number.
It has been added to allow high speed string decomposition into numbers,
especially for mass-data.

usage example(s): 

     Integer fastFromString:'12345' at:1
     Integer fastFromString:'12345' at:2
     Integer fastFromString:'12345' at:3
     Integer fastFromString:'12345' at:4
     Integer fastFromString:'12345' at:5
     Integer fastFromString:'1234512345' at:1
     Integer fastFromString:'2147483647' at:1
     Integer fastFromString:'-12345' at:1

     Integer fastFromString:'4294967295' at:1
     Integer fastFromString:'12345' at:6
     Integer fastFromString:'12345' at:0

     Time millisecondsToRun:[
        100000 timesRepeat:[
            Integer readFrom:'12345'
        ]
     ]

usage example(s): 

     Time millisecondsToRun:[
        100000 timesRepeat:[
            Integer fastFromString:'12345' at:1
        ]
     ]

o  fromBCDBytes: aByteArray
given a byteArray in BCD format, return an appropriate integer.
The byteArray must contain the BCD encoded decimal string,
starting with the most significant digits.
This conversion is useful for some communication protocols,
or control systems, which represent big numbers this way...

usage example(s): 

     Integer fromBCDBytes:#[16r12 16r34 16r56]
     Integer fromBCDBytes:#[16r12 16r34 16r56 16r78]
     Integer fromBCDBytes:#[16r12 16r34 16r56 16r78 16r90]
     Integer fromBCDBytes:#[16r98 16r76 16r54]
     Integer fromBCDBytes:#[16r98 16r76 16r54 16r32]
     Integer fromBCDBytes:#[16r98 16r76 16r54 16r32 16r10]
     Integer fromBCDBytes:#[16r12 16r34 16r56 16r78 16r90 16r12 16r34 16r56 16r78 16r90]

o  fromSwappedBCDBytes: aByteArray
given a byteArray in BCD format, return an appropriate integer.
The byteArray must contain the BCD encoded decimal string,
starting with the LEAST significant digits.
This conversion is useful for some communication protocols,
or control systems (e.g. SMC), which represent big numbers this way...

usage example(s): 

     Integer fromSwappedBCDBytes:#[16r12 16r34 16r56]
     Integer fromSwappedBCDBytes:#[16r12 16r34 16rF6]
     Integer fromSwappedBCDBytes:#[16r12 16r34 16r56 16r78]
     Integer fromSwappedBCDBytes:#[16r12 16r34 16r56 16r78 16r90]
     Integer fromSwappedBCDBytes:#[16r98 16r76 16r54]
     Integer fromSwappedBCDBytes:#[16r98 16r76 16r54 16r32]
     Integer fromSwappedBCDBytes:#[16r98 16r76 16r54 16r32 16r10]
     Integer fromSwappedBCDBytes:#[16r12 16r34 16r56 16r78 16r90 16r12 16r34 16r56 16r78 16r90]

o  new: numberOfBytes neg: negative
for ST-80 compatibility:
Return an empty Integer (uninitialized value) with space for
numberOfBytes bytes (= digitLength). The additional argument
negative specifies if the result should be a negative number.
The digits can be stored byte-wise into the result, using digitAt:put:

o  readFrom: aStringOrStream
return the next Integer from the (character-)stream aStream
as decimal number.

NOTICE:
This behaves different from the default readFrom:, in returning
0 (instead of raising an error) in case no number can be read.
It is unclear, if this is the correct behavior (ST-80 does this)
- depending on the upcoming ANSI standard, this may change.

usage example(s): 

     Integer readFrom:(ReadStream on:'foobar')
     Integer readFrom:(ReadStream on:'123foobar')
     Integer readFrom:(ReadStream on:'foobar') onError:nil

o  readFrom: aStringOrStream allowRadix: allowRadix onError: exceptionBlock
return the next Integer from the (character-)stream aStream,
possibly handling initial XXr for arbitrary radix numbers and initial sign.
Also, all initial whitespace is skipped.
If the string does not represent a valid integer number,
return the value of exceptionBlock.

usage example(s): 

     Integer readFrom:'12345'      onError:['wrong']
     Integer readFrom:'-12345'     onError:['wrong']
     Integer readFrom:'+12345'     onError:['wrong']
     Integer readFrom:'16rFFFF'    onError:['wrong']
     Integer readFrom:'12345.1234' onError:['wrong']
     Integer readFrom:'foo'        onError:['wrong']
     Integer readFrom:'foo'

o  readFrom: aStringOrStream onError: exceptionBlock
return the next Integer from the (character-)stream aStream,
handling initial XXr for arbitrary radix numbers and initial sign.
Also, all initial whitespace is skipped.
If the string does not represent a valid integer number,
return the value of exceptionBlock.

usage example(s): 

     Integer readFrom:'12345'      onError:['wrong']
     Integer readFrom:'-12345'     onError:['wrong']
     Integer readFrom:'+12345'     onError:['wrong']
     Integer readFrom:'16rFFFF'    onError:['wrong']
     Integer readFrom:'12345.1234' onError:['wrong']
     Integer readFrom:'foo'        onError:['wrong']
     Integer readFrom:'foo'

     Integer readFrom:'16rFFFF'    allowRadix:false onError:['wrong']

o  readFrom: aStringOrStream radix: radix
return the next UNSIGNED Integer from the (character-)stream aStream in radix;
(assumes that the initial XXr has already been read).
No whitespace-skipping is done.
Returns 0 if no number available.

NOTICE:
This behaves different from the default readFrom:, in returning
0 (instead of raising an error) in case no number can be read.
It is unclear, if this is the correct behavior (ST-80 does this)
- depending on the upcoming ANSI standard, this may change.

o  readFrom: aStringOrStream radix: radix onError: exceptionBlock
return the next UNSIGNED Integer from the (character-)stream aStream in radix;
(assumes that the initial XXr has already been read).
No whitespace-skipping is done.
Returns the value of exceptionBlock, if no number is available.

usage example(s): 

     Integer readFrom:(ReadStream on:'12345') radix:10
     Integer readFrom:(ReadStream on:'FFFF') radix:16
     Integer readFrom:(ReadStream on:'1010') radix:2
     Integer readFrom:(ReadStream on:'foobar') radix:10
     Integer readFrom:(ReadStream on:'foobar') radix:10 onError:nil
     Integer readFrom:'gg' radix:10 onError:0
     Integer readFrom:'' radix:10 onError:'wrong'

     |s|
     s := String new:1000 withAll:$1.
     Time millisecondsToRun:[
        1000 timesRepeat:[
            s asInteger
        ]
     ]

o  readFromRomanString: aStringOrStream
convert a string or stream containing a roman representation into an integer.
Raises a RomanNumberFormatError, if the inputs format is completely wrong.
Raises BadRomanNumberFormatError if it's wrong, but could be parsed.
Notifies via NaiveRomanNumberFormatNotification, if its a bit wrong (naive format).
Will read both real and naive roman numbers (see printRomanOn: vs. printRomanOn:naive:),
however, a notification is raised for naive numbers (catch it if you are interested in it).

usage example(s): 

     Integer readFromRomanString:'I'
     Integer readFromRomanString:'II'
     Integer readFromRomanString:'III'
     Integer readFromRomanString:'IV'
     Integer readFromRomanString:'clix'
     Integer readFromRomanString:'MIX'
     Integer readFromRomanString:'MCMXCIX'

   Naive cases (which are accepted):
     Integer readFromRomanString:'IIII'
     Integer readFromRomanString:'VIIII'
     Integer readFromRomanString:'CLXXXXVIIII'

    Error case (not proceedable):
     Integer readFromRomanString:'LC'

    Error case (proceedable):
     Integer readFromRomanString:'MCCCCCCCCXXXXXXIIIIII'

     BadRomanNumberFormatError ignoreIn:[
         Integer readFromRomanString:'MCCCCCCCCXXXXXXIIIIII'
     ]

usage example(s): 

naive cases:
     #(
        'MCMXCIX'           1999
        'MCMXCVIIII'        1999
        'MCMLXXXXIX'        1999
        'MDCCCCXCIX'        1999
        'MDCCCCXCVIIII'     1999
        'MDCCCCLXXXXIX'     1999
        'MDCCCCLXXXXVIIII'  1999
     ) pairWiseDo:[:goodString :expectedValue |
        (Integer readFromRomanString:goodString onError:nil) ~= expectedValue ifTrue:[self halt].
     ]

usage example(s): 

error cases:
      #(
        'XIIX'
        'VV'
        'VVV'
        'XXL'
        'XLX'
        'LC'
        'LL'
        'DD'
     ) do:[:badString |
        (Integer readFromRomanString:badString onError:nil) notNil ifTrue:[self halt].
     ]

usage example(s): 

good cases:
     #( 'I'     1
        'II'    2
        'III'   3
        'IV'    4
        'V'     5
        'VI'    6
        'VII'   7
        'VIII'  8
        'IX'    9
        'X'     10
        'XI'    11
        'XII'   12
        'XIII'  13
        'XIV'   14
        'XV'    15
        'XVI'   16
        'XVII'  17
        'XVIII' 18
        'XIX'   19
        'XX'    20
        'XXX'   30
        'L'     50
        'XL'    40
        'LX'    60
        'LXX'   70
        'LXXX'  80
        'CXL'   140
        'CL'    150
        'CLX'   160
        'MMM'                   3000
        'MMMM'                  4000
        'MMMMCMXCIX'            4999
        'MMMMMMMMMCMXCIX'       9999
     ) pairWiseDo:[:goodString :expectedValue |
        (Integer readFromRomanString:goodString onError:nil) ~= expectedValue ifTrue:[self halt].
     ]

usage example(s): 

      1 to:9999 do:[:n |
        |romanString|

        romanString := String streamContents:[:stream | n printRomanOn:stream].
        (Integer readFromRomanString:romanString onError:nil) ~= n ifTrue:[self halt].
     ]

o  readFromRomanString: aStringOrStream onError: exceptionalValue
convert a string or stream containing a roman representation into an integer.
Raises an exception, if the inputs format is wrong.
Does allow reading of naive (more than 3 in a row) and
bad (not using L and D) roman numbers.
(Such numbers can be seen on some medevial buildings.

usage example(s): 

     Integer readFromRomanString:'I'    onError:nil
     Integer readFromRomanString:'II'   onError:nil
     Integer readFromRomanString:'III'  onError:nil
     Integer readFromRomanString:'IV'   onError:nil
     Integer readFromRomanString:'clix' onError:nil
     Integer readFromRomanString:'MCMXCIX' onError:nil

   Naive cases (which are accepted):
     Integer readFromRomanString:'IIII' onError:nil
     Integer readFromRomanString:'VIIII' onError:nil
     Integer readFromRomanString:'CLXXXXVIIII' onError:nil

   Error cases:
     Integer readFromRomanString:'LC'   onError:nil

usage example(s): 

error cases:
      #(
        'XIIX'
        'VV'
        'VVV'
        'XXL'
        'XLX'
        'LC'
        'LL'
        'DD'
     ) do:[:badString |
        (Integer readFromRomanString:badString onError:nil) notNil ifTrue:[self halt].
     ]

usage example(s): 

naive (but handled) cases:
      #(
        'IIII'   4
        'VIIII'  9
        'XIIII'  14
        'XVIIII' 19
     ) pairWiseDo:[:goodString :expectedValue |
        (Integer readFromRomanString:goodString onError:nil) ~= expectedValue ifTrue:[self halt].
     ]

usage example(s): 

good cases:
     #( 'I'     1
        'II'    2
        'III'   3
        'IV'    4
        'V'     5
        'VI'    6
        'VII'   7
        'VIII'  8
        'IX'    9
        'X'     10
        'XI'    11
        'XII'   12
        'XIII'  13
        'XIV'   14
        'XV'    15
        'XVI'   16
        'XVII'  17
        'XVIII' 18
        'XIX'   19
        'XX'    20
        'XXX'   30
        'L'     50
        'XL'    40
        'LX'    60
        'LXX'   70
        'LXXX'  80
        'CXL'   140
        'CL'    150
        'CLX'   160
        'MMM'                   3000
        'MMMM'                  4000
        'MMMMCMXCIX'            4999
        'MMMMMMMMMCMXCIX'       9999
     ) pairWiseDo:[:goodString :expectedValue |
        (Integer readFromRomanString:goodString onError:nil) ~= expectedValue ifTrue:[self halt].
     ]

usage example(s): 

      1 to:9999 do:[:n |
        |romanString|

        romanString := String streamContents:[:stream | n printRomanOn:stream].
        (Integer readFromRomanString:romanString onError:nil) ~= n ifTrue:[self halt].
     ]

usage example(s): 

reading naive numbers:

      1 to:9999 do:[:n |
        |romanString|

        romanString := String streamContents:[:stream | n printRomanOn:stream naive:true].
        (Integer readFromRomanString:romanString onError:nil) ~= n ifTrue:[self halt].
     ]

o  readFromString: aString radix: base onError: exceptionBlock
return the next UNSIGNED Integer from the (character-)aString in radix;
(assumes that the initial XXr has already been read).
No whitespace-skipping is done.
Expects that NO garbage is at the end of the string.
Returns the value from exceptionBlock, if no valid integer is in the string.

usage example(s): 

     Integer readFromString:'1234' radix:10 onError:[nil] 
     Integer readFromString:'-1234' radix:10 onError:[nil]  - I only read unsigned numbers
     Integer readFromString:' 1234' radix:10 onError:[nil]  - I do not skip whitespace
     Integer readFromString:'1234 ' radix:10 onError:[nil]  - I do not accept anything after the number

prime numbers
o  flushPrimeCache
cleanup after using a primeCache.
See comment in initializePrimeCacheUpTo:limit

usage example(s): 

     Integer initializePrimeCacheUpTo:1000000
     Integer flushPrimeCache.

o  initializePrimeCacheUpTo: limit
if many operations are to be done using primes, we can keep them around...
You will need n/8/2 bytes to keep fast info about primes up to n
(i.e. 100Mb is good for primes up to 1.6*10^9)

usage example(s): 

     Integer initializePrimeCacheUpTo:1000000.
     Integer initializePrimeCacheUpTo:10000000.
     Integer initializePrimeCacheUpTo:100000000.
     Integer initializePrimeCacheUpTo:1000000000.
     Integer flushPrimeCache.

usage example(s): 

     Integer flushPrimeCache.
     Transcript showCR:(
        Time millisecondsToRun:[ 1 to:100000 do:[:n | n isPrime] ]
     ).
     Integer initializePrimeCacheUpTo:100000.
     Transcript showCR:(
        Time millisecondsToRun:[ 1 to:100000 do:[:n | n isPrime] ]
     ).
     Integer flushPrimeCache.

o  largePrimesUpTo: max do: aBlock
Evaluate aBlock with all primes up and including maxValue.
The Algorithm is adapted from http://www.rsok.com/~jrm/printprimes.html
It encodes prime numbers much more compactly than #primesUpTo:
38.5 integer per byte (2310 numbers per 60 byte) allow for some fun large primes.
(all primes up to SmallInteger maxVal can be computed within ~27MB of memory;
the regular #primesUpTo: would require 4 *GIGA*bytes).
Note: The algorithm could be re-written to produce the first primes (which require
the longest time to sieve) faster but only at the cost of clarity.

usage example(s): 

     Integer largePrimesUpTo:1000000 do:[:i | i > 900000 ifTrue:[self halt] ]
     (Integer primesUpTo:1000000) inspect

o  primeCacheSize
see comment in initializePrimeCacheUpTo:limit

o  primesUpTo5000
return a table of primes up to 5000.
Primes are heavily used to compute good container sizes in Set and Dictionary,
and in some cryprographic algorithms.

o  primesUpTo: max
Return a list of prime integers up to and including the given integer.

usage example(s): 

     Integer primesUpTo: 100
     Integer primesUpTo: 13
     (Integer primesUpTo: 100) select:[:p | p between:10 and:99]

o  primesUpTo: max do: aBlock
Compute aBlock with all prime integers up to and including the given integer.
See comment in initializePrimeCacheUpTo:limit

usage example(s): 

     Integer primesUpTo: 100
     Integer primesUpTo:20000 do:[:p | ]

queries
o  hasSharedInstances
return true if this class has shared instances, that is, instances
with the same value are identical.
Although not always shared (LargeIntegers), these should be treated
so, to be independent of the number of bits in a SmallInt

o  isAbstract
Return if this class is an abstract class.
True is returned for Integer here; false for subclasses.
Abstract subclasses must redefine this again.

Instance protocol:

Compatibility-Dolphin
o  & aNumber
( an extension from the stx:libcompat package )
return the bitwise-and of the receiver and the argument, anInteger.
Same as bitAnd: - added for compatibility with Dolphin Smalltalk.
Notice:
PLEASE DO NOT USE & for integers in new code; it makes the code harder
to understand, as it may be not obvious, whether a boolean-and a bitWise-and is intended.
For integers, use bitAnd: to make the intention explicit.
Also, consider using and: for booleans, which is does not evaluate the right part if the left is false.

usage example(s): 

     14 | 1
     9 & 8

o  highWord
return the high 16 bits of a 32 bit value

usage example(s): 

     (16r12345678 highWord) hexPrintString
     (16r12345678 lowWord) hexPrintString

o  lowWord
return the low 16 bits of a 32 bit value

usage example(s): 

     (16r12345678 lowWord) hexPrintString
     (16r12345678 highWord) hexPrintString

o  mask: integerMask set: aBoolean
Answer the result of setting/resetting the specified mask in the receiver.

usage example(s): 

turn on the 1-bit:
         |v|

         v := 2r0100.
         v mask:1 set:true

     turn off the 1-bit:
         |v|

         v := 2r0101.
         v mask:1 set:false

o  maskClear: aMaskInteger
return an integer with all bits cleared which are set in aMaskInteger.
An alias for bitClear: for compatibility.

usage example(s): 

     3 maskClear:1

o  maskSet: aMaskInteger
return an integer with all bits set which are set in aMaskInteger.
An alias for bitSet: for compatibility.

o  printStringRadix: aRadix padTo: sz
return a printed representation of the receiver in a given radix,
padded with zeros (at the left) up to size.
If the printString is longer than size,
it is returned unchanged (i.e. not truncated).
See also printStringRadix:size:fill:

usage example(s): 

     1024 printStringRadix:16 padTo:4
     16rABCD printStringRadix:16 padTo:3
     1024 printStringRadix:2 padTo:16
     1024 printStringRadix:16 padTo:8

o  | aNumber
return the bitwise-or of the receiver and the argument, anInteger.
Same as bitOr: - added for compatibility with Dolphin Smalltalk.
Notice:
PLEASE DO NOT USE | for integers in new code; it makes the code harder
to understand, as it may be not obvious, whether a boolean-or a bitWise-or is intended.
For integers, use bitOr: to make the intention explicit.
Also, consider using or: for booleans, which is does not evaluate the right part if the left is true.

usage example(s): 

     14 | 1
     9 & 8

Compatibility-Squeak
o  anyBitOfMagnitudeFrom: startBitIndex to: stopBitIndexArg
Tests for any magnitude bits in the interval from start to stopArg.

o  asByteArray
return my hexBytes in MSB.
Do not use:
This is a very stupid squeak-compatibility method,
as normally, you'd expect the bytes to be ordered in the machine's native order

o  asByteArrayOfSize: size
return my hexBytes in MSB, optionally padded at the left with zeros

usage example(s): 

     123 asByteArrayOfSize:1 #[123]
     123 asByteArrayOfSize:2 #[0 123]
     123 asByteArrayOfSize:4 #[0 0 0 123]

     255 asByteArrayOfSize:1 #[255]

     256 asByteArrayOfSize:1
     256 asByteArrayOfSize:2
     256 asByteArrayOfSize:4
     256 asByteArrayOfSize:8

o  atRandom
return a random number between 1 amd myself

usage example(s): 

     100 atRandom
     1000 atRandom

o  atRandom: aRandomGenerator
return a random number between 1 and myself

usage example(s): 

     100 atRandom:(Random new)
     1000 atRandom:(Random new)

o  bitShiftMagnitude: shift
-1 bitShiftMagnitude:1
-2 bitShift:-1
-2 bitShift:-1

o  printLeftPaddedWith: padChar to: size base: base
prints left-padded

usage example(s): 

     1234 printPaddedWith:$0 to:4 base:16
     1234 printLeftPaddedWith:$0 to:4 base:16
     128 printLeftPaddedWith:$0 to:2 base:16

o  printPaddedWith: padChar to: size base: base
attention: prints right-padded; see printLeftPadded.

usage example(s): 

     1234 printPaddedWith:$0 to:4 base:16

o  printStringBase: base
return my printString in a base;
same as printStringRadix:

usage example(s): 

     1234 printStringBase:16

o  printStringHex
return my printString in base 16;
same as printStringRadix:

usage example(s): 

     4096 printStringHex

o  printStringRoman
return my roman printString;
almost the same as romanPrintString:

o  raisedTo: exp modulo: mod

Compatibility-V'Age
o  << aNumber
V'Age compatibility: left shift

usage example(s): 

     1 << 5
     64 << -5

o  >> aNumber
V'Age compatibility: right shift

usage example(s): 

     1 >> -5
     64 >> 5

Javascript support
o  js_asBoolean
( an extension from the stx:libjavascript package )

o  js_not
( an extension from the stx:libjavascript package )

bcd conversion
o  decodeFromBCD
return a number representing the value of the BCD encoded receiver.

usage example(s): 

     16r1234567890123 decodeFromBCD
     16r1073741823 decodeFromBCD
     16r1073741824 decodeFromBCD
     16r1073741825 decodeFromBCD

     16r55 decodeFromBCD
     16r127 decodeFromBCD
     16r800000 decodeFromBCD
     16r8000000 decodeFromBCD
     16r80000000 decodeFromBCD
     16r800000000 decodeFromBCD
     16r127567890 decodeFromBCD
     16r1234567890 decodeFromBCD

     16r5A decodeFromBCD
     16rFF decodeFromBCD

o  encodeAsBCD
return a BCD encoded number representing the same value as the
receiver.

usage example(s): 

     55 encodeAsBCD hexPrintString
     127 encodeAsBCD hexPrintString
     127 encodeAsBCD hexPrintString
     8912345 encodeAsBCD hexPrintString
     89123456 encodeAsBCD hexPrintString
     891234567 encodeAsBCD hexPrintString
     900000000 encodeAsBCD hexPrintString
     1073741823 encodeAsBCD hexPrintString
     1073741824 encodeAsBCD hexPrintString
     1073741825 encodeAsBCD hexPrintString
     1891234567 encodeAsBCD hexPrintString
     8912345678 encodeAsBCD hexPrintString
     1234567890 encodeAsBCD hexPrintString

bit operators
o  allMask: aMaskInteger
return true if all 1-bits in aMaskInteger are also 1 in the receiver

usage example(s): 

2r00001111 allMask:2r00000001

usage example(s): 

2r00001111 allMask:2r00011110

usage example(s): 

2r00001111 allMask:2r00000000

o  anyMask: aMaskInteger
return true if any 1-bits in anInteger is also 1 in the receiver.
(somewhat incorrect, if the mask is zero)

usage example(s): 

2r00001111 anyMask:2r00000001

usage example(s): 

2r00001111 anyMask:2r11110000

o  bitAnd: aMaskInteger
return the bitwise-and of the receiver and the argument, anInteger.
This is a general and slow implementation, walking over the bytes of
the receiver and the argument.

usage example(s): 

     (16r112233445566778899 bitAnd:16rFF                ) printStringRadix:16
     (16r112233445566778899 bitAnd:16rFFFFFFFFFFFFFFFF00) printStringRadix:16
     (16r112233445566778899 bitAnd:16rFF0000000000000000) printStringRadix:16
     (16r112233445566778899 bitAnd:16r00000000000000FFFF) printStringRadix:16

o  bitClear: aMaskInteger
return the bitwise-and of the receiver and the complement of the argument, anInteger,
returning the receiver with bits of the argument cleared.
(i.e. the same as self bitAnd:aMaskInteger bitInvert).
This is a general and slow implementation, walking over the bytes of
the receiver and the argument.

o  bitCount
return the number of 1-bits in the receiver

usage example(s): 

      2r100000000000000000000000000000000000000000000000000000000001 bitCount
      2r111111111111111111111111111111111111111111111111111111111111111111 bitCount
      100 factorial bitCount -> 207
      1000 factorial bitCount -> 3788

o  bitDeinterleave: n
extract count integers from an n-way Morton number as a vector;
This is the inverse operation from bitInterleave: - see comment there.
i.e. if count is 3,
and the receiver's bits are
cN bN aN ... c2 b2 a2 c1 b1 a1 c0 b0 a0
then the result will be a vector containing the numbers a,b,c with bits:
aN ... a2 a1 a0
bN ... b2 b1 b0
cN ... c2 c1 c0.

usage example(s): 

     (2r1100 bitInterleaveWith:2r1001) -> 2r11100001
     (2r11000110 bitInterleaveWith:2r10011100 and:2r10100101) -> 2r111100001010010111100001.

     2r11100001 bitDeinterleave:2
     
     (2r11000110 bitInterleaveWith:2r10011100 and:2r10100101) 
     (198 bitInterleaveWith:156 and:165) bitDeinterleave:3

o  bitInterleaveWith: anInteger
generate a Morton number (-> https://en.wikipedia.org/wiki/Morton_number_(number_theory))
by interleaving bits of the receiver (at odd positions if counting from 1)
with bits of the argument (at even bit positions).

Thus, if the bits of the receiver are
aN ... a2 a1 a0
and those of the argument are:
bN ... b2 b1 b0
the result is
bN aN ... b2 a2 b1 a1 b0 a0.

Morton numbers are great to linearize 2D coordinates
eg. to sort 2D points by distances

usage example(s): 

     (2r11000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 
     bitInterleaveWith:2r10010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000) 
        -> 2r1101001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

     (2r11000101000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 
     bitInterleaveWith:2r10010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000) 
        -> 2r1101001000010001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

o  bitInterleaveWith: integer1 and: integer2
generate a Morton3 number (-> https://en.wikipedia.org/wiki/Morton_number_(number_theory))
by interleaving bits of the receiver with bits of the arguments.
Thus, if the bits of the receiver are
aN ... a2 a1 a0
and those of the integer1 are:
bN ... b2 b1 b0
and those of the integer2 are:
cN ... c2 c1 c0
the result is
cN bN aN ... c2 b2 a2 c1 b1 a1 c0 b0 a0.

Morton3 numbers are great to linearize 3D coordinates
eg. to sort 3D points by distances

usage example(s): 

     (2r1100 bitInterleaveWith:2r1001 and:2r1010) printStringRadix:2 -> '111 001 100 010'

     (2r11000110 bitInterleaveWith:2r10011100 and:2r10100101) printStringRadix:2 -> '111 001 100 010 010 111 001 100'
     (1 bitInterleaveWith:1 and:16)
     
     ((1<<31) bitInterleaveWith:(1<<31) and:(1<<31)) bitDeinterleave:3
     ((1<<31) bitInterleaveWith:(1<<63) and:(1<<95)) bitDeinterleave:3

o  bitInvert
return a new integer, where all bits are complemented.
This does not really make sense for negative largeIntegers,
since the digits are stored as absolute value.
Q: is this specified in a language standard ?

usage example(s): 

     16rff bitInvert bitAnd:16rff
     16rffffffff bitInvert
     16rff00ff00 bitInvert hexPrintString

o  bitInvertByte
return a new integer, where the low 8 bits are masked and complemented.
This returns an unsigned version of what bitInvert would return.
(i.e. same as self bitInvert bitAnd:16rFF)

usage example(s): 

     16rff bitInvert
     16rff bitInvertByte

o  bitOr: aMaskInteger
return the bitwise-or of the receiver and the argument, anInteger.
This is a general and slow implementation, walking over the bytes of
the receiver and the argument.
It is redefined in concrete subclasses (especially SmallInteger) for performance.

usage example(s): 

        16rFFFFFFFFFFFFFFFFFFFF0 bitOr:1.0
        16rFFFFFFFFFFFFFFFFFFFF0 bitOr:1.0s1
        16rFFFFFFFFFFFFFFFFFFFF0 bitOr:1.1

o  bitReversed
swap (i.e. reverse) bits in an integer
i.e. a.b.c.d....x.y.z -> z.y.x...b.a.d.c.
Warning:
do not use this without care: it depends on the machine's
word size; i.e. a 64bit machine will return a different result as a 32bit machine.
Better use one of the bitReversedXX methods.
This my vanish or be replaced by something better

usage example(s): 

     2r1001 asLargeInteger bitReversed printStringRadix:2
     2r10011101 asLargeInteger bitReversed printStringRadix:2
     2r111110011101 asLargeInteger bitReversed printStringRadix:2
     2r11111001110100000000000000000000000000000000000000000001  bitReversed printStringRadix:2
     -1 asLargeInteger bitReversed printStringRadix:2

o  bitReversed16
swap (i.e. reverse) the low 16 bits in an integer
the high bits are ignored and cleared in the result
i.e. xxx.a.b.c.d....x.y.z -> 000.z.y.x...b.a.d.c.

usage example(s): 

     16r8000 bitReversed16  
     16r87654321 bitReversed16 printStringRadix:2
     16rFEDCBA987654321 bitReversed16 printStringRadix:2

o  bitReversed32
swap (i.e. reverse) the low 32 bits in an integer
the high bits are ignored and cleared in the result
i.e. xxx.a.b.c.d....x.y.z -> 000.z.y.x...b.a.d.c.

usage example(s): 

     16r80000000 bitReversed32
     2r11111001110100000000000000000000000000000000000000000001  bitReversed32 printStringRadix:2
     -1 asLargeInteger bitReversed32 printStringRadix:2

o  bitReversed64
swap (i.e. reverse) the low 64 bits in an integer
the high bits are ignored and cleared in the result
i.e. xxx.a.b.c.d....x.y.z -> 000.z.y.x...b.a.d.c.

usage example(s): 

     16r80000000 bitReversed32
     16r80000000 bitReversed64
     16r8000000000000000 bitReversed64
     2r11111001110100000000000000000000000000000000000000000001  bitReversed32 printStringRadix:2
     -1 asLargeInteger bitReversed32 printStringRadix:2

o  bitReversed8
swap (i.e. reverse) the low 8 bits in an integer
the high bits are ignored and cleared in the result
i.e. xxx.a.b.c.d....x.y.z -> 000.z.y.x...b.a.d.c.

usage example(s): 

     2r1001 asLargeInteger bitReversed8 printStringRadix:2
     2r10011101 asLargeInteger bitReversed8 printStringRadix:2
     2r111110011101 asLargeInteger bitReversed8 printStringRadix:2
     2r11111001110100000000000000000000000000000000000000000001  bitReversed8 printStringRadix:2
     -1 asLargeInteger bitReversed8 printStringRadix:2

o  bitShift: shiftCount
return the value of the receiver shifted by shiftCount bits;
leftShift if shiftCount > 0; rightShift otherwise.

Notice: the result of bitShift: on negative receivers is not
defined in the language standard (since the implementation
is free to choose any internal representation for integers)
However, ST/X preserves the sign.

o  bitTest: aMaskInteger
return true, if any bit from aMask is set in the receiver.
I.e. true, if the bitwise-AND of the receiver and the argument, anInteger
is non-0, false otherwise.
This is a general and slow implementation, walking over the bytes of
the receiver and the argument.
It is redefined in concrete subclasses (especially SmallInteger) for performance.

usage example(s): 

     16r112233445566778899 bitTest:16rFF
     16r112233445566778800 bitTest:16rFF
     16r112233445566778899 bitTest:16rFFFFFFFFFFFFFFFF00
     16r112233445566778899 bitTest:16rFF0000000000000000
     16r112233445566778899 bitTest:16r00000000000000FFFF
     16r1234567800000000 bitTest:16r8000000000000000
     16r8765432100000000 bitTest:16r8000000000000000
     16r12345678 bitTest:16r80000000
     16r87654321 bitTest:16r80000000

o  bitXor: anInteger
return the bitwise-or of the receiver and the argument, anInteger.
This is a general and slow implementation, walking over the bytes of
the receiver and the argument.
It is redefined in concrete subclasses (especially SmallInteger) for performance.

usage example(s): 

     (16r112233445566778899 bitXor:16rFF                ) printStringRadix:16 '112233445566778866'
     (16r112233445566778899 bitXor:16rFFFFFFFFFFFFFFFF00) printStringRadix:16 'EEDDCCBBAA99887799'
     (16r112233445566778899 bitXor:16rFF0000000000000000) printStringRadix:16 'EE2233445566778899'
     (16r112233445566778899 bitXor:16r112233445566778800) printStringRadix:16

o  changeMask: mask to: aBooleanOrNumber
return a new number where the specified mask-bit is on or off,
depending on aBooleanOrNumber.
The method's name may be misleading: the receiver is not changed,
but a new number is returned. Should be named #withMask:changedTo:

usage example(s): 

     (16r3fffffff changeMask:16r80 to:0) hexPrintString
     (16r3fff0000 changeMask:16r80 to:1) hexPrintString

o  even
return true if the receiver is even

usage example(s): 

     16r112233445566778899 even
     16r112233445566778800 even
     1 even
     2 even

o  highBit
return the bitIndex of the highest bit set.
The returned bitIndex starts at 1 for the least significant bit.
Returns 0 if no bit is set.
Notice for negative numbers, the returned value is undefined (actually: nonsense),
because for 2's complement representation, conceptionally all high bits are 1.
But because we use a sign-magnitude representation, you'll get the high bit of
the absolute magnitude.

usage example(s): 

     0 highBit
     -1 highBit
     (1 bitShift:1) highBit
     (1 bitShift:30) highBit
     (1 bitShift:31) highBit
     (1 bitShift:32) highBit
     (1 bitShift:33) highBit
     (1 bitShift:64) highBit
     (1 bitShift:1000) highBit
     (1 bitShift:1000) negated highBit
     ((1 bitShift:64)-1) highBit

o  highBitOfMagnitude
return the high bit index of my magnitude bits

usage example(s): 

     17 highBit    -> 5
     -17 highBit   -> 63 (actually undefined)
     -17 highBitOfMagnitude -> 5

o  leftShift: shiftCount
return the value of the receiver shifted left by shiftCount bits;
leftShift if shiftCount > 0; rightShift otherwise.

Notice: the result of bitShift: on negative receivers is not
defined in the language standard (since the implementation
is free to choose any internal representation for integers)
However, ST/X preserves the sign.

usage example(s): 

     16r100000000 leftShift:1
     16r100000000 negated leftShift:1

o  lowBit
return the bitIndex of the lowest bit set. The returned bitIndex
starts at 1 for the least significant bit.
Returns 0 if no bit is set.

usage example(s): 

     0 lowBit
     1 lowBit
     (1 bitShift:1) lowBit
     (1 bitShift:1) highBit
     (1 bitShift:30) lowBit
     (1 bitShift:30) highBit
     (1 bitShift:31) lowBit
     (1 bitShift:31) highBit
     (1 bitShift:32) lowBit
     (1 bitShift:32) highBit
     (1 bitShift:33) lowBit
     (1 bitShift:33) highBit
     (1 bitShift:64) lowBit
     (1 bitShift:64) highBit
     (1 bitShift:1000) lowBit
     (1 bitShift:1000) highBit
     ((1 bitShift:64)-1) lowBit
     ((1 bitShift:64)-1) highBit

o  noMask: aMaskInteger
return true if no 1-bit in anInteger is 1 in the receiver

usage example(s): 

     2r00001111 noMask:2r00000001
     2r00001111 noMask:2r11110000

o  odd
return true if the receiver is odd

usage example(s): 

     16r112233445566778899 odd
     16r112233445566778800 odd
     1 odd
     2 odd

o  rightShift: shiftCount
return the value of the receiver shifted right by shiftCount bits;
rightShift if shiftCount > 0; leftShift otherwise.

Notice: the result of bitShift: on negative receivers is not
defined in the language standard (since the implementation
is free to choose any internal representation for integers)
However, ST/X preserves the sign.

usage example(s): 

     16r100000000 rightShift:1
     16r100000000 negated rightShift:1

     16r100000000 rightShift:2
     16r100000000 negated rightShift:2

     16r100000000 rightShift:3
     16r100000000 negated rightShift:3

     ((16r100000000 rightShift:1) rightShift:1) rightShift:1
     ((16r100000000 negated rightShift:1) rightShift:1) rightShift:1

bit operators - indexed
o  bitAt: index
return the value of the index's bit (index starts at 1) as 0 or 1.
Notice: the result of bitAt: on negative receivers is not
defined in the language standard (since the implementation
is free to choose any internal representation for integers)

usage example(s): 

     1 bitAt:1                     => 1
     1 bitAt:2                     => 0
     1 bitAt:0                     index error
     2r1000100010001000100010001000100010001000100010001000 bitAt:48 => 1
     2r1000100010001000100010001000100010001000100010001000 bitAt:47 => 0

     (1 bitShift:1000) bitAt:1000  => 0
     (1 bitShift:1000) bitAt:1001  => 1
     (1 bitShift:1000) bitAt:1002  => 0

     (1 bitShift:30) bitAt:30
     (1 bitShift:30) bitAt:31
     (1 bitShift:30) bitAt:32
     (1 bitShift:31) bitAt:31
     (1 bitShift:31) bitAt:32
     (1 bitShift:31) bitAt:33
     (1 bitShift:32) bitAt:32
     (1 bitShift:32) bitAt:33
     (1 bitShift:32) bitAt:34
     (1 bitShift:64) bitAt:64
     (1 bitShift:64) bitAt:65
     (1 bitShift:64) bitAt:66

o  bitAt: anIntegerIndex put: aBit
the name is a bit misleading: this returns a NEW integer with the corresponding
bit either set or cleared.
Indexing starts with 1

usage example(s): 

     2r1100 bitAt:1 put:1
     2r1101 bitAt:1 put:0

o  bitIndicesOfOneBitsDo: aBlock
evaluate aBlock for all indices of a 1-bit, starting with the index of the lowest bit.
The index for the least significant bit is 1.

usage example(s): 

     1 bitIndicesOfOneBitsDo:[:i | Transcript showCR:i].
     2 bitIndicesOfOneBitsDo:[:i | Transcript showCR:i]
     4 bitIndicesOfOneBitsDo:[:i | Transcript showCR:i]
     12 bitIndicesOfOneBitsDo:[:i | Transcript showCR:i]
     127 bitIndicesOfOneBitsDo:[:i | Transcript showCR:i]

o  bitIndicesOfOneBitsReverseDo: aBlock
evaluate aBlock for all indices of a 1-bit, starting with the index of the highest
and ending with the lowest bit.
The index for the least significant bit is 1.

usage example(s): 

     1 bitIndicesOfOneBitsReverseDo:[:i | Transcript showCR:i].
     2 bitIndicesOfOneBitsReverseDo:[:i | Transcript showCR:i]
     4 bitIndicesOfOneBitsReverseDo:[:i | Transcript showCR:i]
     12 bitIndicesOfOneBitsReverseDo:[:i | Transcript showCR:i]
     127 bitIndicesOfOneBitsReverseDo:[:i | Transcript showCR:i]

o  changeBit: index to: aBooleanOrNumber
return a new number where the specified bit is on or off,
depending on aBooleanOrNumber.
Bits are counted from 1 starting with the least significant.
The method's name may be misleading: the receiver is not changed,
but a new number is returned. Should be named #withBit:changedTo:

usage example(s): 

     (16r3fffffff changeBit:31 to:1) hexPrintString
     (16r3fffffff asLargeInteger setBit:31) hexPrintString

o  clearBit: index
return a new integer where the specified bit is off.
Bits are counted from 1 starting with the least significant.
The method's name may be misleading: the receiver is not changed,
but a new number is returned. Should be named #withBitCleared:

usage example(s): 

     3111111111 clearBit:1

o  invertBit: index
return a new number where the specified bit is inverted.
Bits are counted from 1 starting with the least significant.
The method's name may be misleading: the receiver is not changed,
but a new number is returned. Should be named #withBitInverted:

usage example(s): 

     0 invertBit:3         => 4 (2r100)
     0 invertBit:48        => 140737488355328 (2r1000.....000)
     ((0 invertBit:99) invertBit:100) printStringRadix:2

o  isBitClear: index
return true if the index' bit is clear; false otherwise.
Bits are counted from 1 starting with the least significant.

usage example(s): 

     5 isBitClear:1       => false
     5 isBitClear:2       => true
     5 isBitClear:3       => false
     5 isBitClear:4       => true
     5 isBitClear:10000   => true
     2r0101 isBitClear:2  => true
     2r0101 isBitClear:1  => false
     2r0101 isBitClear:0  index error

o  isBitSet: index
return true if the index' bit is set; false otherwise.
Bits are counted from 1 starting with the least significant.

usage example(s): 

     5 isBitSet:3       => true
     2r0101 isBitSet:2  => false
     2r0101 isBitSet:1  => true
     2r0101 isBitSet:0  index error

o  setBit: index
return a new integer, where the specified bit is on.
Bits are counted from 1 starting with the least significant.
The method's name may be misleading: the receiver is not changed,
but a new number is returned. Should be named #withBitSet:

usage example(s): 

     0 setBit:3         => 4 (2r100)
     0 setBit:48        => 140737488355328 (2r1000.....000)
     ((0 setBit:99) setBit:100) printStringRadix:2

byte access
o  byteAt: anIndex
compatibility with ByteArrays etc.

usage example(s): 

        12345678 byteAt:2
        12345678 digitBytes at:2

        -12345678 byteAt:2
        -12345678 digitBytes at:2

o  byteSwapped32
a fallback, in case unimplemented in concrete classes.
Not actually used

usage example(s): 

     16r12345678901234567890 byteSwapped32

o  byteSwapped64
a fallback, in case unimplemented in concrete classes.
Not actually used

usage example(s): 

     16r1234567890123456789 byteSwapped64 hexPrintString

o  digitByteLength
return the number bytes required for a 2's complement
binary representation of this Integer.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  digitBytes
return a byteArray filled with the receiver's bits
(8 bits of the absolute value per element),
least significant byte is first

** This method raises an error - it must be redefined in concrete classes **

o  digitBytesMSB
return a byteArray filled with the receiver's bits
(8 bits of the absolute value per element),
most significant byte is first

** This method raises an error - it must be redefined in concrete classes **

o  digitBytesMSB: msbFlag
return a byteArray filled with the receiver's bits
(8 bits of the absolute value per element),
if msbflag = true, most significant byte is first,
otherwise least significant byte is first

usage example(s): 

      16r12 digitBytesMSB:true
      16r1234 digitBytesMSB:true
      16r1234 digitBytesMSB:false
      16r12345678 digitBytesMSB:true
      16r12345678 digitBytesMSB:false

o  signedDigitLength
return the number bytes required for a 2's complement
binary representation of this Integer.
I.e. the number of bytes from which we have to sign extent the highest bit

usage example(s): 

     0 signedDigitLength
     1 signedDigitLength
     126 signedDigitLength
     127 signedDigitLength
     128 signedDigitLength

     255 signedDigitLength
     256 signedDigitLength
     257 signedDigitLength

     32767 signedDigitLength    
     32768 signedDigitLength    

     -1 signedDigitLength
     -127 signedDigitLength
     -128 signedDigitLength
     -129 signedDigitLength

     -32767 signedDigitLength    
     -32768 signedDigitLength    
     -32769 signedDigitLength

o  swapBytes
swap bytes pair-wise in a positive integer
i.e. a.b.c.d -> b.a.d.c
Swapping of negative integers is undefined and therefore not supported.

usage example(s): 

ByteArray<<#swapBytes needs even number of bytes.
         Add 0 to the most significant position (the end)

usage example(s): 

        16rFFEE2211 swapBytes hexPrintString
        16rFFEEAA2211 swapBytes hexPrintString
        16r2211 swapBytes hexPrintString
        16rFF3FFFFF swapBytes
        self assert:(SmallInteger maxVal swapBytes swapBytes == SmallInteger maxVal)

coercing & converting
o  asFixedPoint
return the receiver as a fixedPoint number

usage example(s): 

     100 asFixedPoint
     100 asFixedPoint + 0.1 asFixedPoint

o  asFixedPoint: scale
return the receiver as fixedPoint number, with the given number
of post-decimal-point digits.

usage example(s): 

     100 asFixedPoint:2
     100 asFixedPoint + (0.1 asFixedPoint:2)

o  asFloat
return a Float with same value as myself.
Since floats have a limited precision, you usually loose bits when doing this.

usage example(s): 

     1234567890 asFloat
     1234567890 asFloat asInteger
     12345678901234567890 asFloat
     12345678901234567890 asFloat asInteger

o  asFraction
return a Fraction with same value as receiver

o  asInteger
return the receiver truncated towards zero -
for integers this is self

o  asLargeFloat
return a LargeFloat with same value as myself.
Since largeFloats have a limited precision, you usually loose bits when
doing this.
If the largeFloat class is not present, a regular float is returned

usage example(s): 

     1234567890 asLargeFloat
     1234567890 asLargeFloat asInteger
     12345678901234567890 asLargeFloat
     12345678901234567890 asLargeFloat asInteger

o  asLargeFloatPrecision: n
return a LargeFloat with same value as myself.
Since largeFloats have a limited precision, you usually loose bits when
doing this.
If the largeFloat class is not present, a regular float is returned

usage example(s): 

     1234567890 asLargeFloatPrecision:10
     12345678901234567890 asLargeFloatPrecision:10

o  asLongFloat
return a LongFloat with same value as myself.
Since longFloats have a limited precision, you usually loose bits when
doing this.

o  asModuloNumber
return a precomputed modulo number

o  asQDouble
( an extension from the stx:libbasic2 package )
return a QDouble with same value as myself.

usage example(s): 

     1234567890 asQDouble
     1234567890 asQDouble asInteger
     12345678901234567890 asQDouble
     12345678901234567890 asQDouble asInteger

o  asQuadFloat
return a QuadFloat with same value as myself.
Since quadFloats have a limited precision, you may loose bits when
doing this.

usage example(s): 

     1234567890 asQuadFloat
     1234567890 asQuadFloat asInteger
     12345678901234567890 asQuadFloat
     12345678901234567890 asQuadFloat asInteger

o  asShortFloat
return a ShortFloat with same value as receiver

o  coerce: aNumber
convert the argument aNumber into an instance of the receiver's class and return it.

o  signExtended24BitValue
return an integer from sign-extending the 24'th bit.
i.e. interprets the lowest 24 bits as a signed integer,
ignoring higher bits.
This may be useful for communication interfaces

usage example(s): 

     16r800000 signExtended24BitValue
     16r7FFFFF signExtended24BitValue
     16rFFFFFF signExtended24BitValue

o  signExtendedByteValue
return an integer from sign-extending the 8'th bit.
i.e. interprets the lowest 8 bits as a signed integer,
ignoring higher bits.
This may be useful for communication interfaces

usage example(s): 

     16r80 signExtendedByteValue
     16r7F signExtendedByteValue
     16rFF signExtendedByteValue

o  signExtendedFromBit: bitNr
return an integer from sign-extending the n'th bit.
i.e. interprets the lowest n bits as a signed integer,
ignoring higher bits.
The bit numbering is 1-based (i.e. the lowest bit has bitNr 1)
This may be useful for communication interfaces.
(kind of the reverse operation to asUnsigned:).

usage example(s): 

     2r111000111 signExtendedFromBit:3 -> 2r11111....111 -> -1 
     2r111000110 signExtendedFromBit:3 -> 2r11111....110 -> -2 
     2r111000101 signExtendedFromBit:3 -> 2r11111....101 -> -3   
     2r111000100 signExtendedFromBit:3 -> 2r11111....100 -> -4 
     2r111000000 signExtendedFromBit:3 -> 2r00000....000 -> 0   
     2r111000011 signExtendedFromBit:3 -> 2r00000....011 -> 3  

     16r800008 signExtendedFromBit:4 -> -8 
     16r7FFF07 signExtendedFromBit:4 -> 7 
     16r7FFF0F signExtendedFromBit:4 -> -1

     16rFFFFFF signExtendedFromBit:8 -> -1
     16rFFFF7F signExtendedFromBit:8 -> 127
     16rFFFF80 signExtendedFromBit:8 -> -128

o  signExtendedFromMaskBit: highBitMask
return an integer from sign-extending the bit defined by highMaskBit,
which MUST be a single bit (otherwise, you'll get garbage).
i.e. interprets the lowest n bits as a signed integer,
ignoring higher bits.
This may be useful for communication interfaces and to expand bitfields into
signed values

usage example(s): 

     2r111000111 signExtendedFromMaskBit:2r100 -> 2r11111....111 -> -1 
     2r111000110 signExtendedFromMaskBit:2r100 -> 2r11111....110 -> -2 
     2r111000101 signExtendedFromMaskBit:2r100 -> 2r11111....101 -> -3   
     2r111000100 signExtendedFromMaskBit:2r100 -> 2r11111....100 -> -4 
     2r111000000 signExtendedFromMaskBit:2r100 -> 2r00000....000 -> 0   
     2r111000011 signExtendedFromMaskBit:2r100 -> 2r00000....011 -> 3  

     16r800008 signExtendedFromMaskBit:2r1000 -> -8 
     16r7FFF07 signExtendedFromMaskBit:2r1000 -> 7 
     16r7FFF0F signExtendedFromMaskBit:2r1000 -> -1

     16rFFFFFF signExtendedFromMaskBit:2r10000000 -> -1
     16rFFFF7F signExtendedFromMaskBit:2r10000000 -> 127
     16rFFFF80 signExtendedFromMaskBit:2r10000000 -> -128

o  signExtendedLongLongValue
return an integer from sign-extending the 64'th bit.
i.e. interprets the lowest 64 bits as a signed integer,
ignoring higher bits.
This may be useful for communication interfaces

usage example(s): 

     16r1238000000000000000 signExtendedLongLongValue
     16r1237FFFFFFFFFFFFFFF signExtendedLongLongValue
     16r123FFFFFFFFFFFFFFFF signExtendedLongLongValue

o  signExtendedLongValue
return an integer from sign-extending the 32'th bit.
i.e. interprets the lowest 32 bits as a signed integer,
ignoring higher bits.
This may be useful for communication interfaces

usage example(s): 

     16r80000000 signExtendedLongValue
     16r7FFFFFFF signExtendedLongValue
     16rFFFFFFFF signExtendedLongValue

o  signExtendedShortValue
return an integer from sign-extending the 16'th bit.
i.e. interprets the lowest 16 bits as a signed integer,
ignoring higher bits.
This may be useful for communication interfaces

usage example(s): 

     16r8000 signExtendedShortValue
     16r7FFF signExtendedShortValue
     16rFFFF signExtendedShortValue

     16r1238000 signExtendedShortValue
     16r1237FFF signExtendedShortValue
     16r123FFFF signExtendedShortValue

o  zigZagDecodedValue
zigzag encoding maps values with small absolute values
into relatively small unsigned integer numbers in the same range.
i.e. [minInt .. maxInt] is mapped into [0 .. maxUINT],
where small magnitudes generate small encodings.
Zigzag is used eg. by google's protocol buffer encoding

usage example(s): 

     0 zigZagEncoded64BitValue zigZagDecodedValue -> 0
     -1 zigZagEncoded64BitValue zigZagDecodedValue -> -1
     1 zigZagEncoded64BitValue zigZagDecodedValue -> 1
     -2 zigZagEncoded64BitValue zigZagDecodedValue -> -2
     2 zigZagEncoded64BitValue zigZagDecodedValue -> 2
     -2147483647 zigZagEncoded64BitValue zigZagDecodedValue -> -2147483647
     2147483647 zigZagEncoded64BitValue zigZagDecodedValue -> 2147483647
     -2147483648 zigZagEncoded64BitValue zigZagDecodedValue -> -2147483648
     2147483648 zigZagEncoded64BitValue zigZagDecodedValue -> 2147483648

     -4611686018427387903 zigZagEncoded64BitValue zigZagDecodedValue -> -4611686018427387903
     4611686018427387903 zigZagEncoded64BitValue zigZagDecodedValue -> 4611686018427387903

     -4611686018427387904 zigZagEncoded64BitValue zigZagDecodedValue -> -4611686018427387904
     4611686018427387904 zigZagEncoded64BitValue zigZagDecodedValue -> 4611686018427387904 

     -4611686018427387905 zigZagEncoded64BitValue zigZagDecodedValue -> -4611686018427387905
     4611686018427387905 zigZagEncoded64BitValue zigZagDecodedValue -> 4611686018427387905

     -9223372036854775807 zigZagEncoded64BitValue zigZagDecodedValue -> -9223372036854775807
     9223372036854775807 zigZagEncoded64BitValue zigZagDecodedValue -> 9223372036854775807

     -9223372036854775808 zigZagEncoded64BitValue zigZagDecodedValue -> -9223372036854775808

     -- out of range
     9223372036854775808 zigZagEncoded64BitValue zigZagDecodedValue

o  zigZagEncoded32BitValue
zigzag encoding maps values with small absolute values
into relatively small unsigned integer numbers in the same range.
i.e. [minInt .. maxInt] is mapped into [0 .. maxUINT],
where small magnitudes generate small encodings.
Zigzag is used eg. by google's protocol buffer encoding

usage example(s): 

     0 zigZagEncoded32BitValue -> 0
     -1 zigZagEncoded32BitValue -> 1
     1 zigZagEncoded32BitValue -> 2
     -2 zigZagEncoded32BitValue -> 3
     2 zigZagEncoded32BitValue -> 4
     -2147483647 zigZagEncoded32BitValue -> 4294967293
     16r7FFFFFFF zigZagEncoded32BitValue -> 4294967294
     16r-80000000 zigZagEncoded32BitValue -> 4294967295

     -- out of range:
     2147483648 zigZagEncoded32BitValue -> 4294967296

o  zigZagEncoded64BitValue
zigzag encoding maps values with small absolute values
into relatively small unsigned integer numbers in the same range.
i.e. [minInt .. maxInt] is mapped into [0 .. maxUINT],
where small magnitudes generate small encodings.
Zigzag is used eg. by google's protocol buffer encoding

usage example(s): 

     0 zigZagEncoded64BitValue -> 0
     -1 zigZagEncoded64BitValue -> 1
     1 zigZagEncoded64BitValue -> 2
     -2 zigZagEncoded64BitValue -> 3
     2 zigZagEncoded64BitValue -> 4
     -2147483647 zigZagEncoded64BitValue -> 4294967293
     2147483647 zigZagEncoded64BitValue -> 4294967294
     -2147483648 zigZagEncoded64BitValue -> 4294967295
     2147483648 zigZagEncoded64BitValue -> 4294967296

     -16r3FFFFFFFFFFFFFFF zigZagEncoded64BitValue 9223372036854775805
     16r3FFFFFFFFFFFFFFF zigZagEncoded64BitValue 9223372036854775806

     -16r4000000000000000 zigZagEncoded64BitValue 9223372036854775807
     16r4000000000000000 zigZagEncoded64BitValue 9223372036854775808 

     -16r4000000000000001 zigZagEncoded64BitValue 9223372036854775809
     16r4000000000000001 zigZagEncoded64BitValue 9223372036854775810

     -16r7FFFFFFFFFFFFFFF zigZagEncoded64BitValue 18446744073709551613
     16r7FFFFFFFFFFFFFFF zigZagEncoded64BitValue 18446744073709551614

     -16r8000000000000000 zigZagEncoded64BitValue 18446744073709551615

     -- out of range
     16r8000000000000000 zigZagEncoded64BitValue

comparing
o  hash
redefined to return smallInteger hashValues

usage example(s): 

        -20000000000000 hash
         20000000000000 hash

dependents access
o  addDependent: anObject
It doesn't make sense to add dependents to a shared instance.
Silently ignore ...

o  onChangeSend: selector to: someOne
It doesn't make sense to add dependents to a shared instance.
Silently ignore ...

double dispatching
o  differenceFromFraction: aFraction
sent when a fraction does not know how to subtract the receiver, an integer

o  differenceFromTimestamp: aTimestamp
I am to be interpreted as seconds, return the timestamp this number of seconds
before aTimestamp

usage example(s): 

     Timestamp now subtractSeconds:100
     100 differenceFromTimestamp:Timestamp now

o  equalFromFraction: aFraction
that should never be invoked, as fractions are always normalized to integers
if resulting from an arithmetic operation.
However, this implementation is for subclasses (i.e. fixed point) and also
allows comparing unnormalized fractions as might appear within the fraction class

o  productFromFraction: aFraction
sent when a fraction does not know how to multiply the receiver, an integer

o  quotientFromFraction: aFraction
Return the quotient of the argument, aFraction and the receiver.
Sent when aFraction does not know how to divide by the receiver.

o  sumFromFraction: aFraction
sent when a fraction does not know how to add the receiver, an integer

o  sumFromTimestamp: aTimestamp
I am to be interpreted as seconds, return the timestamp this number of seconds
after aTimestamp

usage example(s): 

     Timestamp now addSeconds:100
     100 sumFromTimestamp:Timestamp now

helpers
o  gcd_helper: anInteger
a helper for the greatest common divisor of the receiver and anInteger.
Knuth's algorithm for large positive integers, with receiver being
larger than the arg.

inspecting
o  inspectorExtraAttributes
( an extension from the stx:libtool package )
extra (pseudo instvar) entries to be shown in an inspector.

o  inspectorValueListIconFor: anInspector
( an extension from the stx:libtool package )
returns the icon to be shown alongside the value list of an inspector

iteration
o  timesCollect: aBlock
syntactic sugar; same as (1 to:self) collect:aBlock

usage example(s): 

     10 timesCollect:[:i | i squared]

o  to: stop collect: aBlock
syntactic sugar; same as (self to:stop) collect:aBlock

usage example(s): 

     1 to:10 collect:[:i | i squared]
     10 to:20 collect:[:i | i squared]
     (10 to:20) collect:[:i | i squared]

o  to: stop collect: aBlock as: collectionClass
syntactic sugar; same as (self to:stop) collect:aBlock

usage example(s): 

     1 to:10 collect:[:i | i squared] as:Set

misc math
o  acker: n
return the value of acker(self, n).
;-) Do not try with receivers > 3

usage example(s): 

     3 acker:2
     3 acker:7

o  binco: kIn
an alternative name for the binomial coefficient for squeak compatibility

o  binomialCoefficient: k
The binomial coefficient (n over k)

/ n \ with self being n, and 0 <= k <= n.
\ k /

is the number of ways of picking k unordered outcomes from n possibilities,
also known as a combination or combinatorial number.
Sometimes also called C(n,k) (for choose k from n)

binCo is defined as:
n!
----------
k! (n-k)!

but there is a faster, recursive formula:

/ n \ = / n - 1 \ + / n - 1 \
\ k / \ k - 1 / \ k /

with:

/ n \ = / n \ = 1
\ 0 / \ n /

usage example(s): 

     (7 binomialCoefficient:3)
     (10 binomialCoefficient:5)
     (100 binomialCoefficient:5)
     (1000 binomialCoefficient:5)

     TestCase assert: (10 binomialCoefficient:5) = (10 factorial / (5 factorial * 5 factorial))
     TestCase assert: (100 binomialCoefficient:78) = (100 factorial / (78 factorial * (100-78) factorial))
     TestCase assert: (1000 binomialCoefficient:5) = (1000 factorial / (5 factorial * (1000-5) factorial))
     TestCase assert: (10000 binomialCoefficient:78) = (10000 factorial / (78 factorial * (10000-78) factorial))

     Time millisecondsToRun:[ (10000 binomialCoefficient:78) ]                            -> 0
     Time millisecondsToRun:[ (10000 factorial / (78 factorial * (10000-78) factorial)) ] -> 130

o  divMod: aNumber
return an array filled with
(self // aNumber) and (self \\ aNumber).
The returned remainder has the same sign as aNumber.
The following is always true:
(receiver // something) * something + (receiver \\ something) = receiver

Be careful with negative results: 9 // 4 -> 2, while -9 // 4 -> -3.
Especially surprising:
-1 \\ 10 -> 9 (because -(1/10) is truncated towards next smaller integer, which is -1,
and -1 multiplied by 10 gives -10, so we have to add 9 to get the original -1).
-10 \\ 3 -> 2 (because -(10/3) is truncated towards next smaller integer, which is -4,
and -4 * 4 gives -12, so we need to add 2 to get the original -10.

This may be redefined in some integer classes for
more performance (where the remainder is generated as a side effect of division)

usage example(s): 

     10 divMod:3       -> #(3 1)   because 3*3 + 1 = 10
     10 divMod:-3      -> #(-4 -2) because -4*-3 + (-2) = 10
     -10 divMod:3      -> #(-4 2) because -4*-3 + 2 = -10
     -10 divMod:-3     -> #(3 -1)  because -3*3 + (-1) = -10

     1000000000000000000000 divMod:3   -> #(333333333333333333333 1)
     1000000000000000000000 divMod:-3  -> #(-333333333333333333334 -2)
     -1000000000000000000000 divMod:3  -> #(-333333333333333333334 2)
     -1000000000000000000000 divMod:-3 -> #(333333333333333333333 -1)
     100 factorial divMod:103

o  extendedEuclid: tb
return the solution of 'ax + by = gcd(a,b)'.
An array containing x, y and gcd(a,b) is returned.

usage example(s): 

     14 extendedEuclid:5
     14 extendedEuclid:2
     25 extendedEuclid:15

o  factorial
return fac(self) (i.e. 1*2*3...*self).
This chooses a good algorithm, based on the receiver.
Some heuristics here, which has to do with the speed of largeInteger arithmetic.

usage example(s): 

requested factorial of a negative number

usage example(s): 

^ self factorialHalf

usage example(s): 

     10 factorial
     100 factorial
     1000 factorial
     10000 factorial
     100000 factorial
     200000 factorial
     300000 factorial
     1000000 factorial

     Time millisecondsToRun:[10000 factorial]40
     Time millisecondsToRun:[100000 factorial]3220
     Time millisecondsToRun:[1000000 factorial]357120

    #(factorialIter factorialHalf factorialEvenOdd factorial)
    do:[:sel |
      #( (10000 10) 
         (20000 10)
         (50000 10)
         (70000 10)
         (100000 5)
         (200000 3)
         (300000 3)
         (400000 3)) pairsDo:[:n :repeat |
         |times|
        times := (1 to:repeat) collect:[:i |
                Time millisecondsToRun:[ n perform:sel]
               ].

        Transcript printf:'%12s %6d: %5d\n' with:sel with:n with:times min 
      ]
    ].

    factorialIter  10000:    30
    factorialIter  20000:   130
    factorialIter  50000:   790
    factorialIter  70000:  1710
    factorialIter 100000:  4880
    factorialIter 200000: 24980
    factorialIter 300000: 60060
    factorialIter 400000: 112310
    factorialHalf  10000:    20
    factorialHalf  20000:   100
    factorialHalf  50000:   690
    factorialHalf  70000:  1430
    factorialHalf 100000:  3220
    factorialHalf 200000: 28340
    factorialHalf 300000: 68740
    factorialHalf 400000: 127490
    factorialEvenOdd  10000:    10
    factorialEvenOdd  20000:    60
    factorialEvenOdd  50000:   390
    factorialEvenOdd  70000:   810
    factorialEvenOdd 100000:  2020
    factorialEvenOdd 200000:  9960
    factorialEvenOdd 300000: 24480
    factorialEvenOdd 400000: 45340
    factorial  10000:    20
    factorial  20000:   100
    factorial  50000:   680
    factorial  70000:  1400
    factorial 100000:  2040
    factorial 200000: 10130
    factorial 300000: 24670

o  factorialEvenOdd
a recursive odd-even algorithm, which processes smaller largeInts in the loop.
Because multiplication is an O(n^2) algorithm, there is a threshold from which
more but smaller multiplications makes a noticable difference

usage example(s): 

     (6 to:2000) conform:[:i | i factorialIter = i factorialEvenOdd]
     
     Time millisecondsToRun:[20000 factorialIter]
     Time millisecondsToRun:[50000 factorialIter]
     Time millisecondsToRun:[70000 factorialIter]
     Time millisecondsToRun:[100000 factorialIter]
     Time millisecondsToRun:[200000 factorialIter] 16190

     Time millisecondsToRun:[20000 factorialEvenOdd]
     Time millisecondsToRun:[50000 factorialEvenOdd]
     Time millisecondsToRun:[70000 factorialEvenOdd]
     Time millisecondsToRun:[100000 factorialEvenOdd]
     Time millisecondsToRun:[200000 factorialEvenOdd] 2910

o  factorialHalf
an algorithm, which does it with half the number of multiplications.
this is faster than factorialPM to roughly 60000.

usage example(s): 

     10 factorial 3628800
     10 factorialHalf 3628800

     11 factorial 39916800
     11 factorialHalf 39916800

     12 factorial 479001600
     12 factorialHalf 479001600

     10000 factorial = 10000 factorialHalf

     (6 to:2000) conform:[:i | i factorialIter = i factorialHalf]

     Time microsecondsToRun:[30 factorialIter]
     Time microsecondsToRun:[30 factorialHalf]
     Time microsecondsToRun:[50 factorialIter]
     Time microsecondsToRun:[50 factorialHalf]
     Time microsecondsToRun:[75 factorialIter]
     Time microsecondsToRun:[75 factorialHalf]
     Time microsecondsToRun:[100 factorialIter]
     Time microsecondsToRun:[100 factorialHalf]
     Time microsecondsToRun:[500 factorialIter]
     Time microsecondsToRun:[500 factorialHalf]
     Time microsecondsToRun:[1000 factorialIter]
     Time microsecondsToRun:[1000 factorialHalf]
     Time microsecondsToRun:[2000 factorialIter]
     Time microsecondsToRun:[2000 factorialHalf]

     Time microsecondsToRun:[500 factorial]118 120 120
     Time microsecondsToRun:[1000 factorial]339 355 406
     Time microsecondsToRun:[5000 factorial]15703 13669 7715
     Time millisecondsToRun:[10000 factorial]40 30 50
     Time millisecondsToRun:[20000 factorial]140 150 150
     Time millisecondsToRun:[40000 factorial]600 570 560 570
     Time millisecondsToRun:[60000 factorial]1220 1240 1340
     Time millisecondsToRun:[80000 factorial]2600 2580 2540
     Time millisecondsToRun:[100000 factorial]4680 4810 5280
     Time millisecondsToRun:[120000 factorial]8100 8010 7920
     Time millisecondsToRun:[150000 factorial]13830 14040 13360
     Time millisecondsToRun:[200000 factorial]23880 23740

     Time microsecondsToRun:[500 factorialHalf]150 142 192
     Time microsecondsToRun:[1000 factorialHalf]383 527 684
     Time microsecondsToRun:[5000 factorialHalf]6654 9221 4629
     Time millisecondsToRun:[10000 factorialHalf]20 30 20
     Time millisecondsToRun:[20000 factorialHalf]110 110 110
     Time millisecondsToRun:[40000 factorialHalf]490 490 490
     Time millisecondsToRun:[60000 factorialHalf]1100 1090 1070
     Time millisecondsToRun:[80000 factorialHalf]1920 1920 1880
     Time millisecondsToRun:[100000 factorialHalf]3030 3010 3000
     Time millisecondsToRun:[120000 factorialHalf]4830 4770 4760
     Time millisecondsToRun:[150000 factorialHalf]14510 13940 13900
     Time millisecondsToRun:[200000 factorialHalf]28730 28160

o  factorialIter
return fac(self) (i.e. 1*2*3...*self) using an iterative algorithm.
This is slightly faster than the recursive algorithm, and does not
suffer from stack overflow problems (with big receivers)

o  factorialR
return fac(self) (i.e. 1*2*3...*self) using a recursive algorithm.

This is included to demonstration purposes - if you really need
factorial numbers, use the tuned #factorial, which is
faster and does not suffer from stack overflow problems (with big receivers).

usage example(s): 

     10 factorialR
     1000 factorialR
     Time millisecondsToRun:[10000 factorial]

o  fib
compute the fibionacci number for the receiver.
fib(0) := 0
fib(1) := 1
fib(n) := fib(n-1) + fib(n-2)

usage example(s): 

     30 fib
     60 fib
     1000 fib

o  fib_helper
compute the fibionacci number for the receiver.

Fib(n) = Fib(n-1) + Fib(n-2)

Knuth:
Fib(n+m) = Fib(m) * Fib(n+1) + Fib(m-1) * Fib(n)

This is about 3 times faster than fib_iterative.

usage example(s): 

the running time is mostly dictated by the LargeInteger multiplication performance...
     (therefore, we get O(nē) execution times, even for a linear number of multiplications)

     Time millisecondsToRun:[50000 fib_iterative]  312    (DUO 1.7Ghz CPU)
     Time millisecondsToRun:[50000 fib_helper]     109

     Time millisecondsToRun:[100000 fib_iterative] 1248
     Time millisecondsToRun:[100000 fib_helper]    374

     Time millisecondsToRun:[200000 fib_iterative] 4758
     Time millisecondsToRun:[200000 fib_helper]    1544

     Time millisecondsToRun:[400000 fib_iterative] 18892
     Time millisecondsToRun:[400000 fib_helper]    6084

     1 to:100 do:[:i | self assert:(i fib_iterative = i fib_helper) ]
     1 to:100 do:[:i | self assert:(i fib_iterative = i fib) ]

o  gcd: anInteger
return the greatest common divisor of the receiver and anInteger.
Euclids & Knuths algorithm.

usage example(s): 

     3141589999999999 gcd:1000000000000000

     Time millisecondsToRun:[
        10000 timesRepeat:[
           123456789012345678901234567890 gcd: 9876543210987654321
        ]
     ]

o  integerLog10
return the floor of log10 of the receiver.
This is the same as (self log:10) floor.
Used to find out the number of digits needed
to print a number/and for conversion to a LargeInteger.

usage example(s): 

      10 integerLog10
      1000 integerLog10

      10000000000000000.0 log:10
      10000000000000000 integerLog10
      100000000000000000 integerLog10
      1000000000000000000 integerLog10
      10000000000000000000 integerLog10
      100000000000000000000 integerLog10
      1000000000000000000000 integerLog10 -> 21
      1000000000000000000000000000000 integerLog10 -> 30
      10000000000000000000000000000000000000000 integerLog10 -> 40
      
      1 to:10000 by:10 do:[:i |
        self assert:(i factorial printString size == (i factorial integerLog10+1))
      ].
      21 factorial printString size
      21 factorial integerLog10
      51 factorial printString size
      51 factorial integerLog10

o  integerLog2
return the floor of log2 of the receiver.
This is the same as (self log:2) floor.

usage example(s): 

      2  log:2
      2  integerLog2

      3  log:2
      3  integerLog2

      4  log:2
      4  integerLog2

      64  integerLog2
      100 integerLog2
      100 log:2
      999 integerLog2
      999 log:2
      120000 integerLog2
      120000 log:2
      -1 integerLog2
      50 factorial integerLog2
      50 factorial log:2
      1000 factorial integerLog2
      1000 factorial log:2       -- float error!

o  integerReciprocal
return an integer representing 1/self * 2**n.
Where an integer is one bit longer than self.
This is a helper for modulu numbers

usage example(s): 

     333 integerReciprocal                (2 raisedTo:18) // 333
     393 integerReciprocal
     8 integerReciprocal
     15 integerReciprocal
     15112233445566 integerReciprocal
     10239552311579 integerReciprocal

o  integerSqrt
return the largest integer which is less or equal to the receiver's square root.
For large integers, this provides better results than the float sqrt method
(which actually fails for very large numbers)
This might be needed for some number theoretic problems with large numbers
(and also in cryptography).
Uses Newton's method

usage example(s): 

     333 sqrt -> 18.2482875908947
     324 sqrt -> 18.0
     323 sqrt -> 17.9722007556114

     333 integerSqrt -> 18
     325 integerSqrt -> 18
     324 integerSqrt -> 18
     323 integerSqrt -> 17
     
     10239552004900 integerSqrt
     10239552004900 sqrt
     10239552311579 integerSqrt
     10239552311579 sqrt

     5397346292805549782720214077673687804022210808238353958670041357153884304 integerSqrt squared
     5397346292805549782720214077673687804022210808238353958670041357153884304 sqrt squared

     5397346292805549782720214077673687806275517530364350655459511599582614290 integerSqrt
     5397346292805549782720214077673687806275517530364350655459511599582614290 sqrt
     1000 factorial integerSqrt

     1000 factorial - 1000 factorial integerSqrt squared
     1000 factorial - (1000 factorial integerSqrt + 1) squared
     1000 factorial between:(1000 factorial integerSqrt squared) and:((1000 factorial integerSqrt + 1) squared)

o  inverseMod: n
find the modular inverse for myself to n.
This is defined as the solution of: '1 = (self * x) mod n.
This is a helper for modulu numbers

usage example(s): 

     14 inverseMod:5      -> 4
     5 inverseMod:14      -> 3
     14 inverseMod:11     -> 4                (4 * 14) \\ 11
     11 inverseMod:14     -> 9                (9 * 11) \\ 14
     79 inverseMod:3220   -> 1019
     3220 inverseMod:79   -> 54               (54 * 3220) \\ 79
     1234567891 inverseMod:1111111111119
                          -> 148726663534     (148726663534*1234567891) \\ 1111111111119


     14 extendedEuclid:11
     5 extendedEuclid:14
     14 extendedEuclid:2
     3220 extendedEuclid:79

o  lcm: anInteger
return the least common multiple (using gcd:)

usage example(s): 

     65 lcm:15
     3 lcm:15

o  primeFactors
return a collection of prime factors of the receiver.
For prime numbers, an empty collection is returned.
Can take a long time for big numbers

usage example(s): 

     2 to:10000 do:[:n |
        self assert:((n isPrime and:[ n primeFactors isEmpty])
                    or:[ n isPrime not and:[n primeFactors product = n]])
     ]
     3 to:10000 do:[:n |
        self assert:(n factorial primeFactors product = n factorial)
     ]

     13195 primeFactors
     12 primeFactors
     2 primeFactors
     3 primeFactors
     5 primeFactors
     14 primeFactors
     13423453625634765 primeFactors
     13423453625634765 isPrime
     13423453625634765 gcd:(3 * 5 * 19 * 29)
     13423453625634765 / 8265
     1624132320101 isPrime
     1624132320101 gcd: 8265

     1000000 primeFactors
     100000000 primeFactors
     1000000000 primeFactors

     Time millisecondsToRun:[
        1000 timesRepeat:[
            10000000000000000000000000000000000000 primeFactors
        ]
     ]   421

o  primeFactorsUpTo: limitArgOrNil
return a collection of prime factors of the receiver.
For prime numbers, an empty collection is returned.
Can take a long time for big numbers
(win a nobel price, if you find something quick (*)

(*):which does not mean that the code below is optimal - far from it !

o  raisedTo: exp mod: mod
return the modulo (remainder) of
the receiver raised to exp (an Integer) and mod (another Integer)

usage example(s): 

     Time millisecondsToRun: [100000 timesRepeat: [12345678907 raisedTo: 3 modulo: 12345678917]]

     2 raisedTo:2 mod:3
      20000000000000 raisedTo:200 mod:190  ->  30
     (20000000000000 raisedTo:200) \\ 190

      Time millisecondsToRun:[10000 timesRepeat:[
                                200000000000000000000000 raisedTo:65537 mod:1900000000000000000000000
                              ]
                             ]

     Time millisecondsToRun:[1000 timesRepeat:[
                                (200000000000000000000000 raisedTo:65537) \\ 1900000000000000000000000
                             ]
                            ]

o  raisedToCrtModP: p q: q ep: ep eq: eq u: u
Application of the Chinese Remainder Theorem (CRT).

This is a faster modexp for moduli with a known factorisation into two
relatively prime factors p and q, and an input relatively prime to the
modulus, the Chinese Remainder Theorem to do the computation mod p and
mod q, and then combine the results. This relies on a number of
precomputed values, but does not actually require the modulus n or the
exponent e.

expout = expin ^ e mod (p*q).
We form this by evaluating
p2 = (expin ^ e) mod p and
q2 = (expin ^ e) mod q
and then combining the two by the CRT.

Two optimisations of this are possible. First, we can reduce expin
modulo p and q before starting.

Second, since we know the factorisation of p and q (trivially derived
from the factorisation of n = p*q), and expin is relatively prime to
both p and q, we can use Euler's theorem, expin^phi(m) = 1 (mod m),
to throw away multiples of phi(p) or phi(q) in e.
Letting ep = e mod phi(p) and
eq = e mod phi(q)
then combining these two speedups, we only need to evaluate
p2 = ((expin mod p) ^ ep) mod p and
q2 = ((expin mod q) ^ eq) mod q.

Now we need to apply the CRT. Starting with
expout = p2 (mod p) and
expout = q2 (mod q)
we can say that expout = p2 + p * k, and if we assume that 0 <= p2 < p,
then 0 <= expout < p*q for some 0 <= k < q. Since we want expout = q2
(mod q), then p*k = q2-p2 (mod q). Since p and q are relatively prime,
p has a multiplicative inverse u mod q. In other words, u = 1/p (mod q).

Multiplying by u on both sides gives k = u*(q2-p2) (mod q).
Since we want 0 <= k < q, we can thus find k as
k = (u * (q2-p2)) mod q.

Once we have k, evaluating p2 + p * k is easy, and
that gives us the result

printing & storing
o  asBCD
return an integer which represents the BCD encoded value of the receiver;
that is: each digit of its decimal representation is placed into a nibble
of the result. (aka 162 -> 0x162).
This conversion is useful for some communication protocols,
or control systems, which represent numbers this way...
This fallback code is not particularily tuned or optimized for speed.

usage example(s): 

     (100 factorial) asBCD
     999999999 asBCD
     100000000 asBCD
     123456789 asBCD
     99999999 asBCD
     12345678 asBCD
     12345678 asBCD
     12345678 asBCD hexPrintString
     12345678901234567890 asBCD

o  asBCDBytes
return a byteArray containing the receiver in BCD encoding.
The byteArray will contain the BCD encoded decimal string,
starting with the most significant digits first.
This conversion is useful for some communication protocols,
or control systems, which represent big numbers this way...
This is not particularily tuned or optimized for speed.

usage example(s): 

     12345678 asBCDBytes
     12345678 asBCDBytes hexPrintString
     12345678901234567890 asBCDBytes

o  errorPrintHex
print the receiver as a hex number on the standard error stream

o  hexPrintString
return a hex string representation of the receiver.
Notice: this is not padded in any way

usage example(s): 

     9 hexPrintString
     127 hexPrintString
     -1 hexPrintString

o  hexPrintString: size
return a hex string representation of the receiver,
padded to size characters

usage example(s): 

     12345 hexPrintString:4
     123 hexPrintString:4

o  printHex
print the receiver as a hex number on the standard output stream

o  printOn: aStream base: base showRadix: showRadix
append a string representation of the receiver in the specified numberBase to aStream
(if showRadix is true, with initial XXr)
The base argument should be between 2 and 36.
If it is negative, digits > 9 are printed as lowecase a-z.

usage example(s): 

leftPart printOn:aStream base:base.

usage example(s): 

        3000 factorial printOn:Transcript base:10
        10 printOn:Transcript base:3
        31 printOn:Transcript base:3
        10 printOn:Transcript base:2
        31 printOn:Transcript base:2
        -28  printOn:Transcript base:16
        -28  printOn:Transcript base:-16
        -20  printOn:Transcript base:10
        Time millisecondsToRun:[10000 factorial printString]
        '%012d' printf:{  (2 raisedTo:20) }

o  printOn: aStream base: baseInteger size: sz
print a string representation of the receiver in the specified
base. The string is padded on the left with fillCharacter to make
its size as specified in sz.

usage example(s): 

     1024 printOn:Transcript base:16 size:4.
     1024 printOn:Transcript base:2 size:16.
     1024 printOn:Transcript base:16 size:8.

o  printOn: aStream base: baseInteger size: sz fill: fillCharacter
print a string representation of the receiver in the specified
base. The string is padded on the left with fillCharacter to make
its size as specified in sz.

usage example(s): 

     1024 printOn:Transcript base:16 size:4 fill:$0.
     1024 printOn:Transcript base:2 size:16 fill:$.
     1024 printOn:Transcript base:16 size:8 fill:Character space.

o  printOn: aStream radix: base
append a printed description of the receiver to aStream.
The receiver is printed in radix base (instead of the default, 10).
This method is obsoleted by #printOn:base:, which is ST-80 & ANSI compatible.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  printRomanOn: aStream
print the receiver as roman number to the receiver, aStream.
This converts correct (i.e. prefix notation for 4,9,40,90, etc.).

usage example(s): 

     1 to:10 do:[:i | i printRomanOn:Transcript. Transcript cr.].
     1999 printRomanOn:Transcript. Transcript cr.
     Date today year printRomanOn:Transcript. Transcript cr.

usage example(s): 

test all between 1 and 9999:
      1 to:9999 do:[:n |
        |romanString|

        romanString := String streamContents:[:stream | n printRomanOn:stream].
        (Integer readFromRomanString:romanString onError:nil) ~= n ifTrue:[self halt].
     ]

o  printRomanOn: aStream naive: naive
print the receiver as roman number to the receiver, aStream.
The naive argument controls if the conversion is
correct (i.e. subtracting prefix notation for 4,9,40,90, etc.),
or naive (i.e. print 4 as IIII and 9 as VIIII); also called simple.
The naive version is often used for page numbers in documents.

usage example(s): 

     1 to:10 do:[:i | i printRomanOn:Transcript naive:false. Transcript cr.].
     1 to:10 do:[:i | i printRomanOn:Transcript naive:true. Transcript cr.].

     1999 printRomanOn:Transcript. Transcript cr.
     Date today year printRomanOn:Transcript. Transcript cr.

usage example(s): 

test all between 1 and 9999:
      1 to:9999 do:[:n |
        |romanString|

        romanString := String streamContents:[:stream | n printRomanOn:stream naive:false].
        (Integer readFromRomanString:romanString onError:nil) ~= n ifTrue:[self halt].
     ]

usage example(s): 

test naive all between 1 and 9999:
      1 to:9999 do:[:n |
        |romanString|

        romanString := String streamContents:[:stream | n printRomanOn:stream naive:true].
        (Integer readFromRomanString:romanString onError:nil) ~= n ifTrue:[self halt].
     ]

o  printStringRadix: aRadix size: sz fill: fillCharacter
return a string representation of the receiver in the specified
radix. The string is padded on the left with fillCharacter to make
its size as specified in sz.

usage example(s): 

     1024 printStringRadix:16 size:4 fill:$0.
     1024 printStringRadix:2 size:16 fill:$.
     1024 printStringRadix:16 size:8 fill:(Character space)

o  romanPrintString
return a roman number representation of the receiver as a string

usage example(s): 

     1999 romanPrintString.
     Date today year romanPrintString.

private
o  numberOfDigits: n8BitDigits
initialize the instance to store n8BitDigits

** This method raises an error - it must be redefined in concrete classes **

o  numberOfDigits: n8BitDigits sign: newSign
initialize the instance to store n8BitDigits and sign

** This method raises an error - it must be redefined in concrete classes **

o  setSign: aNumber
private: for protocol completeness with LargeIntegers.
Returns a smallInteger with my absValue and the sign of the argument.
The method's name may be misleading: the receiver is not changed,
but a new number is returned.

o  sign: aNumber
destructively change the sign of the receiver

** This is an obsolete interface - do not use it (it may vanish in future versions) **

queries
o  digitAt: n
return the n-th byte of the binary representation.

** This method raises an error - it must be redefined in concrete classes **

o  digitByteAt: n
return 8 bits of my signed value, starting at byte index.
For positive receivers, this is the same as #digitAt:;
for negative ones, the actual bit representation is returned.

** This method raises an error - it must be redefined in concrete classes **

o  digitLength
return the number of bytes needed for the unsigned binary representation of the receiver.
For negative receivers, the result is not defined by the language standard.
This method is redefined in concrete classes
- the fallback here is actually never used.

o  exponent
return what would be the normalized float's exponent if I were a float.
This is not for general use - it has been added for dolphin (soap) compatibility.
This assumes that the mantissa is normalized to
0.5 .. 1.0 and the number's value is: mantissa * 2^exp

usage example(s): 

     self assert:( 1.0 exponent = 1 exponent ).
     self assert:( 2.0 exponent = 2 exponent ).
     self assert:( 3.0 exponent = 3 exponent ).
     self assert:( 4.0 exponent = 4 exponent ).
     self assert:( 12345.0 exponent = 12345 exponent ).
     self assert:( 0.0 exponent = 0 exponent ).

     self assert:( -1.0 exponent = -1 exponent ).
     self assert:( -2.0 exponent = -2 exponent ).
     self assert:( -3.0 exponent = -3 exponent ).
     self assert:( -4.0 exponent = -4 exponent ).
     self assert:( -12345.0 exponent = -12345 exponent ).

o  isInteger
return true, if the receiver is some kind of integer number

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

o  isPerfectSquare
return true if I am a perfect square.
That is a number for which the square root is an integer.

usage example(s): 

     0 isPerfectSquare
     3 isPerfectSquare
     4 isPerfectSquare
     9 isPerfectSquare
     (1 to:1000000) count:[:n | n isPerfectSquare] 1000
     12345678987654321234567 isPerfectSquare
     123123123432 squared isPerfectSquare
     (123123123432 raisedTo:7) isPerfectSquare
     ((123456789123456789 raisedTo:7)) isPerfectSquare
     ((123456789123456789 raisedTo:7)-1) isPerfectSquare
     Time microsecondsToRun:[12345678987654321234567 isPerfectSquare]

o  isPowerOf: p
return true, if the receiver is a power of p

usage example(s): 

     0 isPowerOf:2
     1 isPowerOf:2

     16r0000000000000000 isPowerOf:2
     16r0000004000000000 isPowerOf:2
     16r0000004000000001 isPowerOf:2

     16r0000000000000001 isPowerOf:2
     16r0000000000000002 isPowerOf:2
     16r0000000000000004 isPowerOf:2
     16r0000000000000008 isPowerOf:2

     16r0000000000000001 isPowerOf:4
     16r0000000000000002 isPowerOf:4
     16r0000000000000004 isPowerOf:4
     16r0000000000000008 isPowerOf:4
     16r0000000000000010 isPowerOf:4
     16r0000000000000020 isPowerOf:4

     3r0000000000000001 isPowerOf:3
     3r0000000000000010 isPowerOf:3
     3r0000000000000100 isPowerOf:3
     3r0000000000001000 isPowerOf:3
     3r0000000000001001 isPowerOf:3
     3r0000000000002000 isPowerOf:3

     10 isPowerOf:10
     20 isPowerOf:10
     100 isPowerOf:10
     110 isPowerOf:10
     200 isPowerOf:10
     1000 isPowerOf:10
     10000 isPowerOf:10
     100000 isPowerOf:10
     100001 isPowerOf:10

o  isPowerOfTwo
return true, if the receiver is a power of 2

usage example(s): 

     10000 factorial isPowerOfTwo
     |n| n := 10000 factorial. Time millisecondsToRun:[10000 timesRepeat:[ n isPowerOfTwo]]

usage example(s): 

     (2 raisedTo:10000) isPowerOfTwo
     |n| n := (2 raisedTo:10000). Time millisecondsToRun:[10000 timesRepeat:[ n isPowerOfTwo]]

o  isPrime
return true if I am a prime Number.
Pre-condition: I am positive.
This is a q&d hack, which may need optimization if heavily used.

usage example(s): 

     Integer primesUpTo:1000
     (1 to:1000000) count:[:n | n isPrime] 78498
     Time millisecondsToRun:[ (1 to:1000000) count:[:n | n isPrime]] 1295   w.o firstFewPrimes
     Time millisecondsToRun:[ (1 to:1000000) count:[:n | n isPrime]] 936    with firstFewPrimes (less tests)
     Time millisecondsToRun:[ (1 to:1000000) count:[:n | n isPrime]] 343    with primeCache

o  nextMultipleOf: n
return the multiple of n at or above the receiver.
(?? The name of this method may be a bit misleading,
as it returns the receiver iff it is already a multiple)
Useful for padding, aligning or rounding,
especially when reading aligned binary data.

usage example(s): 

     0 nextMultipleOf: 4 -> 0
     1 nextMultipleOf: 4 -> 4
     2 nextMultipleOf: 4 -> 4 
     3 nextMultipleOf: 4 -> 4
     4 nextMultipleOf: 4 -> 4
     5 nextMultipleOf: 4 -> 8

     22 nextMultipleOf: 4
     100 factorial nextMultipleOf: 4

o  nextPowerOf2
return the power of 2 at or above the receiver.
Useful for padding.
Notice, that for a powerOf2, the receiver is returned.
Also notice, that (because it is used for padding),
0 is returned for zero.

usage example(s): 

     0 nextPowerOf2
     1 nextPowerOf2
     2 nextPowerOf2
     3 nextPowerOf2
     4 nextPowerOf2
     5 nextPowerOf2
     6 nextPowerOf2
     7 nextPowerOf2
     8 nextPowerOf2

     22 nextPowerOf2
     12 factorial nextPowerOf2  isPowerOf:2
     100 factorial nextPowerOf2  isPowerOf:2
     1000 factorial nextPowerOf2  isPowerOf:2
     Time millisecondsToRun:[
         |v|
         v := 1000 factorial.
         1000 timesRepeat:[
            v nextPowerOf2
         ]
     ]

o  nextPrime
return the next prime after the receiver

usage example(s): 

     0 nextPrime
     1 nextPrime
     2 nextPrime
     22 nextPrime
     37 nextPrime
     36 nextPrime
     3456737 nextPrime
     1000 factorial nextPrime

o  parityOdd
return true, if an odd number of bits are set in the receiver, false otherwise.
(i.e. true for odd parity)
Undefined for negative values (smalltalk does not require the machine to use 2's complement)

usage example(s): 

     0 parityOdd
     1 parityOdd
     2 parityOdd
     4 parityOdd
     5 parityOdd
     7 parityOdd
     33 parityOdd
     6 parityOdd

     1 to:1000000 do:[:n |
        self assert:(n parityOdd = ((n printStringRadix:2) occurrencesOf:$1) odd).
     ]

     0 to:255 do:[:n |
        |p|

        p :=
            (((((((((n rightShift: 7)
            bitXor: (n rightShift: 6))
                bitXor: (n rightShift: 5))
                    bitXor: (n rightShift: 4))
                        bitXor: (n rightShift: 3))
                            bitXor: (n rightShift: 2))
                                bitXor: (n rightShift: 1))
                                    bitXor: n) bitAnd:1) == 1.
        self assert:(n parityOdd = p).
     ]

special modulo arithmetic
o  add_32: anInteger
return a C-semantic 32bit sum of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns a signed 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics.

o  add_32u: anInteger
return a C-semantic 32bit unsigned sum of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns an unsigned 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics.

o  mul_32: anInteger
return a C-semantic 32bit product of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns a signed 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics.

o  mul_32u: anInteger
return a C-semantic 32bit unsigned product of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns an unsigned 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics.

o  sub_32: anInteger
return a C-semantic 32bit difference of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns a signed 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics.

o  sub_32u: anInteger
return a C-semantic 32bit unsigned difference of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns an unsigned 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics.

special modulo bit operators
o  asSigned32
return a 32-bit integer with my bit-pattern.
For protocol completeness.

o  asUnsigned128
return a 128-bit integer with my bit-pattern, but positive.
May be required for bit operations on the sign-bit and/or to
convert C numbers.
Does not check if the value is out of range, so callers
may have to do a bitwise-and on the result

usage example(s): 

     (-1 asUnsigned128) hexPrintString
     1 asUnsigned128
     (SmallInteger minVal asUnsigned128) hexPrintString
     (SmallInteger maxVal asUnsigned128) hexPrintString

o  asUnsigned16
return a 16-bit integer with my bit-pattern, but positive.
May be required for bit operations on the sign-bit and/or to
convert C/Java numbers.
Does not check if the value is out of range, so callers
may have to do a bitwise-and on the result

usage example(s): 

     (-1 asUnsigned16) hexPrintString
     1 asUnsigned16
     (SmallInteger minVal asUnsigned16) hexPrintString
     (SmallInteger maxVal asUnsigned16) hexPrintString

o  asUnsigned32
return a 32-bit integer with my bit-pattern, but positive.
May be required for bit operations on the sign-bit and/or to
convert C/Java numbers.
Does not check if the value is out of range, so callers
may have to do a bitwise-and on the result

usage example(s): 

     (-1 asUnsigned32) hexPrintString
     1 asUnsigned32
     (SmallInteger minVal asUnsigned32) hexPrintString
     (SmallInteger maxVal asUnsigned32) hexPrintString

o  asUnsigned64
return a 64-bit integer with my bit-pattern, but positive.
May be required for bit operations on the sign-bit and/or to
convert C/Java numbers.
Does not check if the value is out of range, so callers
may have to do a bitwise-and on the result

usage example(s): 

     (-1 asUnsigned64) hexPrintString
     1 asUnsigned64
     (SmallInteger minVal asUnsigned64) hexPrintString
     (SmallInteger maxVal asUnsigned64) hexPrintString

     
     (16r-8000000000000000 asUnsigned64) hexPrintString

     out of range: wrong results
     (16r8000000000000000 asUnsigned64) hexPrintString
     (16rFFFFFFFFFFFFFFFF asUnsigned64) hexPrintString
     (16r-FFFFFFFFFFFFFFFF asUnsigned64) hexPrintString

o  asUnsigned: numBits
return a numBits integer with my bit-pattern, but positive.
May be required for bit operations on the sign-bit and/or to
convert C/Java numbers, or to generate bitfields from signed numbers
(kind of the reverse operation to signExtenedFromBit:).
Does not check if the value is out of range, so callers
may have to do a bitwise-and on the result

usage example(s): 

     (-1 asUnsigned:64) hexPrintString
     1 asUnsigned:64
     (SmallInteger minVal asUnsigned:64) hexPrintString
     (SmallInteger maxVal asUnsigned:64) hexPrintString

     (-1 asUnsigned:4) hexPrintString
     (-7 asUnsigned:4) hexPrintString
     (-8 asUnsigned:4) hexPrintString
     1 asUnsigned:4

o  bitAnd_32: anInteger
return a C-semantic 32bit locical-and of the receiver and
the argument. Both must be either Small- or LargeIntegers.
Returns a signed 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
bit operations with C semantics.

o  bitAnd_32u: anInteger
return a C-semantic 32bit locical-and of the receiver and
the argument. Both must be either Small- or LargeIntegers.
Returns an unsigned 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
bit operations with C semantics.

o  bitInvert_32
return a C-semantic 32bit complement of the receiver,
which must be either Small- or LargeIntegers.
Returns a signed 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
bit operations with C semantics.

o  bitInvert_32u
return a C-semantic 32bit complement of the receiver,
which must be either Small- or LargeIntegers.
Returns an unsigned 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
bit operations with C semantics.

o  bitOr_32: anInteger
return a C-semantic 32bit locical-or of the receiver and
the argument. Both must be either Small- or LargeIntegers.
Returns a signed 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
bit operations with C semantics.

o  bitOr_32u: anInteger
return a C-semantic 32bit locical-or of the receiver and
the argument. Both must be either Small- or LargeIntegers.
Returns an unsigned 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
bit operations with C semantics.

o  bitXor_32: anInteger
return a C-semantic 32bit locical-xor of the receiver and
the argument. Both must be either Small- or LargeIntegers.
Returns a signed 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
bit operations with C semantics.

o  bitXor_32u: anInteger
return a C-semantic 32bit locical-xor of the receiver and
the argument. Both must be either Small- or LargeIntegers.
Returns an unsigned 32bit number.
This (nonstandard) specialized method is provided to allow simulation of
bit operations with C semantics.

tracing
o  traceInto: aRequestor level: level from: referrer
double dispatch into tracer, passing my type implicitely in the selector

truncation & rounding
o  ceiling
return the smallest integer which is larger or equal to the receiver.
For integers, this is the receiver itself.

o  compressed
if the receiver can be represented as a SmallInteger, return
a SmallInteger with my value; otherwise return self with leading
zeros removed. This method is redefined in LargeInteger.

o  floor
return the largest integer which is smaller or equal to the receiver.
For integers, this is the receiver itself.

o  fractionPart
return a number with value from digits after the decimal point.
(i.e. the receiver minus its truncated value)
Since integers have no fraction, return 0 here.

usage example(s): 

     1234.56789 fractionPart
     1.2345e6 fractionPart
     1000 fractionPart
     10000000000000000 fractionPart

o  integerPart
return a number with value from digits before the decimal point.
(i.e. the receiver's truncated value)
Since integers have no fraction, return the receiver here.

usage example(s): 

     1234.56789 integerPart
     1.2345e6 integerPart
     1000 integerPart
     10000000000000000 integerPart

o  normalize
if the receiver can be represented as a SmallInteger, return
a SmallInteger with my value; otherwise return self with leading
zeros removed.
This method is left for backward compatibility - it has been
renamed to #compressed for ST-80 compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  rounded
return the receiver rounded toward the next Integer -
for integers this is the receiver itself.

o  truncated
return the receiver truncated towards zero as Integer
for integers this is the receiver itself.

visiting
o  acceptVisitor: aVisitor with: aParameter
dispatch for visitor pattern; send #visitInteger:with: to aVisitor

Private classes:

    ModuloNumber

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Mon, 04 Dec 2023 10:41:07 GMT