Smalltalk/X Webserver

Documentation of class 'Integer':

Class: Integer

Inheritance
Description
Class protocol
Instance protocol
Private classes

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--ArithmeticValue
         |
         +--Number
            |
            +--Integer
               |
               +--LargeInteger
               |
               +--SmallInteger

Package:: stx:libbasic

Category:: Magnitude-Numbers

Version:: rev: 1.574 date: 2024/04/24 09:04:38; user: stefan; file: Integer.st directory: libbasic; module: stx stc-classLibrary: libbasic

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

copyrightCOPYRIGHT (c) 1988 by Claus Gittinger
             All Rights Reserved

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

Class protocol:

Signal constants

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

class initialization

initialize: (comment from inherited method)
setup the signals

coercing & converting

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

constants

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

instance creation

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

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).
Otherwise, you'll get a wrong result.
However, for portability, only use it for 32bit numbers (int32s).
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.
Use only if you are sure, that the passed in string contains valid strings.
This is roughly 3 times faster than the full-blown inherited fromString:

Usage example(s):

     Integer fastFromString:'0' at:1    
     Integer fastFromString:'0000' at:1 
     Integer fastFromString:'0001' at:1 
     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:'-2147483647' at:1
     Integer fastFromString:'-2147483648' at:1
     Integer fastFromString:'-2147483649' at:1 -- wrong on 32 bit machines
     Integer fastFromString:'-12345' at:1

     Integer fastFromString:'4294967295' at:1  -- wrong on 32bit machines
     Integer fromString:'4294967295'           -- correct on all machines

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

     Integer fastFromString:'0.001' at:1
     Float fastFromString:'1234' at:1 
     Number fastFromString:'1234' at:1 
     Number fastFromString:'1234.0' at:1 

     (Time toRun:[
        100000 timesRepeat:[
            Integer readFrom:'12345'
        ]
     ]) / 100000  => 509ns

Usage example(s):

     (Time toRun:[
        100000 timesRepeat:[
            Integer fastFromString:'12345' at:1
        ]
     ]) / 100000  => 107ns

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]

fromBytes: aByteArray

given a byteArray with bytes in the machine's natural byteorder,
return an appropriate integer.
This conversion is useful when arbitrary large integers are received
from a byte stream

Usage example(s):

     (Integer fromBytes:#[16r12 16r34 16r56])               hexPrintString -> '563412'
     (Integer fromBytes:#[16r12 16r34 16r56 16r78])         hexPrintString -> '78563412'
     (Integer fromBytes:#[16r12 16r34 16r56 16r78 16r90])   hexPrintString -> '9078563412'
     (Integer fromBytes:#[16r12 16r34 16r56 16r78 16r90 16r12 16r34 16r56 16r78 16r90]
                ) hexPrintString ->  '90785634129078563412'

fromBytes: aByteArray MSB: msb

given a byteArray with bytes, return an appropriate integer.
This conversion is useful when arbitrary large integers are received
from a byte stream

Usage example(s):

     (Integer fromBytes:#[16r12 16r34 16r56] MSB:false)     hexPrintString -> '563412'
     (Integer fromBytes:#[16r12 16r34 16r56] MSB:true)      hexPrintString -> '123456'

     (Integer fromBytes:#[16r12 16r34 16r56 16r78])         hexPrintString -> '78563412'
     (Integer fromBytes:#[16r12 16r34 16r56 16r78 16r90])   hexPrintString -> '9078563412'
     (Integer fromBytes:#[16r12 16r34 16r56 16r78 16r90 16r12 16r34 16r56 16r78 16r90]
              MSB:false ) hexPrintString ->  '90785634129078563412'
     (Integer fromBytes:#[16r12 16r34 16r56 16r78 16r90 16r12 16r34 16r56 16r78 16r90]
              MSB:true ) hexPrintString ->  '12345678901234567890'

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]

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:

readFrom: aStringOrStream

return the next Integer from the (character-)stream aStream
as decimal number.

NOTICE (QUESTIONABLE BEHAVIOR):
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.

Better call readFrom:onError:, so you know what you get in case of an error

Usage example(s):

     Integer readFrom:(ReadStream on:'foobar')  
     Integer readFrom:(ReadStream on:'0xAFF')  
     Integer readFrom:(ReadStream on:'0xAFF' allowRadix:true)  
     Integer readFrom:(ReadStream on:'123foobar')
     Integer readFrom:(ReadStream on:'foobar') onError:nil

readFrom: aStringOrStream allowRadix: aBoolean

return the next Integer from the (character-)stream aStream
as decimal number or optionally as radix number.

NOTICE (QUESTIONABLE BEHAVIOR):
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.

Better call readFrom:onError:, so you know what you get in case of an error

Usage example(s):

     Integer readFrom:(ReadStream on:'foobar')  
     Integer readFrom:(ReadStream on:'0xAFF')  
     Integer readFrom:(ReadStream on:'0xAFF') allowRadix:true
     Integer readFrom:(ReadStream on:'123foobar')
     Integer readFrom:(ReadStream on:'foobar') onError:nil

readFrom: aStringOrStream allowRadix: allowRadix allowPlusSign: allowPlusSign groupCharacters: groupCharacters 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 allowPlusSign is true, a prefix '+' is allowed and ignored.
If groupCharacters is non-nil, these are skipped and ignored.
If the string does not represent a valid integer number,
return the value of exceptionBlock.

Usage example(s):

     Integer readFrom:'12345'      onError:['wrong'] => 12345
     Integer readFrom:'-12345'     onError:['wrong'] => -12345
     Integer readFrom:'+12345'     onError:['wrong'] => 'wrong'
     Integer readFrom:'16rFFFF'    onError:['wrong'] => 65535 
     Integer readFrom:'12345.1234' onError:['wrong'] => 12345
     Integer readFrom:'foo'        onError:['wrong'] => 'wrong'
     Integer readFrom:'foo'
     Integer readFrom:'0x123'                        => 0
     Integer readFrom:'0x123' allowRadix:true        => 291

readFrom: aStringOrStream allowRadix: allowRadix onError: exceptionBlock

Usage example(s):

     Integer readFrom:'12345'      onError:['wrong'] => 12345
     Integer readFrom:'-12345'     onError:['wrong'] => -12345
     Integer readFrom:'+12345'     onError:['wrong'] => 'wrong'
     Integer readFrom:'16rFFFF'    onError:['wrong'] => 65535 
     Integer readFrom:'12345.1234' onError:['wrong'] => 12345
     Integer readFrom:'foo'        onError:['wrong'] => 'wrong'
     Integer readFrom:'foo'
     Integer readFrom:'0x123'                        => 0
     Integer readFrom:'0x123' allowRadix:true        => 291

readFrom: aStringOrStream base: aBase

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

NOTICE (QUESTIONABLE BEHAVIOR):
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.

Better call readFrom:radix:onError:, so you know what you get in case of an error

readFrom: aStringOrStream base: baseInteger groupCharacters: groupCharacters onError: exceptionBlock

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
        ]
     ]

readFrom: aStringOrStream base: baseInteger onError: exceptionBlock

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'
     Integer readFrom:'gg' radix:16 onError:0           => 0
     Integer readFrom:'-10' radix:16 onError:0          => -16
     Integer readFrom:'10' radix:16 onError:0           => 16

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

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']   => 12345
     Integer readFrom:'-12345'     onError:['wrong']   => -12345
     Integer readFrom:'+12345'     onError:['wrong']   
     Integer readFrom:'16rFFFF'    onError:['wrong']   => 65535
     Integer readFrom:'12345.1234' onError:['wrong']   => 12345
     Integer readFrom:'foo'        onError:['wrong']   => 'wrong'
     Integer readFrom:'foo'                            => 0
     Integer readFrom:'0xFFFF'     onError:['wrong']   => 65535

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

readFrom: aStringOrStream radix: radix

marked as obsolete by Stefan Vogel at 22-Apr-2024

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

readFrom: aStringOrStream radix: baseInteger groupCharacters: groupCharacters onError: exceptionBlock

marked as obsolete by Stefan Vogel at 22-Apr-2024

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

readFrom: aStringOrStream radix: baseInteger onError: exceptionBlock

marked as obsolete by Stefan Vogel at 22-Apr-2024

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

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

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

readFromString: aString base: 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' base:10 onError:[nil]
     Integer readFromString:'-1234' base:10 onError:[nil]  - I only read unsigned numbers
     Integer readFromString:' 1234' base:10 onError:[nil]  - I do not skip whitespace
     Integer readFromString:'1234 ' base:10 onError:[nil]  - I do not accept anything after the number

readFromString: aString radix: base onError: exceptionBlock

marked as obsolete by Stefan Vogel at 22-Apr-2024

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

readUnsignedFrom: aStringOrStream radix: radix

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

NOTICE (QUESTIONABLE BEHAVIOR):
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.

Better call readUnsignedFrom:radix:onError:, so you know what you get

readUnsignedFrom: aStringOrStream radix: radix onError: exceptionBlock

Usage example(s):

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

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

readUnsignedFrom: aStringOrStream radix: radix sign: sign

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

NOTICE (QUESTIONABLE BEHAVIOR):
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.

Better call readUnsignedFrom:radix:sign:onError:, so you know what you get

readUnsignedFrom: aStringOrStream radix: radix sign: sign groupCharacters: groupCharacters onError: exceptionBlock

return the next UNSIGNED Integer from the (character-)stream aStream in radix;
(assumes that any initial XXr or sign has already been read).
No whitespace-skipping is done.
However, groupCharacters if not nil, may define a set of characters
which are to be skipped if encountered inside the digits.
This can be used to skip over thousands group separators.
Returns the value of exceptionBlock, if no number is available.

Usage example(s):

     Integer readFrom:(ReadStream on:'12345') radix:10
     Integer readFrom:(ReadStream on:'123_45') 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'

     Integer 
        readUnsignedFrom:'1_234_567_890' 
        radix:10 
        sign:0 
        groupCharacters:'_' 
        onError:[self error]

     -- swiss thousands groups
     Integer 
        readUnsignedFrom:'1''234''567''890' 
        radix:10 
        sign:0 
        groupCharacters:'''' 
        onError:[self error]

     -- US thousands groups
     Integer 
        readUnsignedFrom:'1,234,567,890' 
        radix:10 
        sign:0 
        groupCharacters:',' 
        onError:[self error] 

     -- German thousands groups
     Integer 
        readUnsignedFrom:'1.234.567.890' 
        radix:10 
        sign:0 
        groupCharacters:'.' 
        onError:[self error] 

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

readUnsignedFrom: aStringOrStream radix: radix sign: sign onError: exceptionBlock

prime numbers

flushPrimeCache

cleanup after using a primeCache.
See comment in initializePrimeCacheUpTo:limit

Usage example(s):

     Integer initializePrimeCacheUpTo:1000000
     Integer flushPrimeCache.

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.

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

primeCacheSize

see comment in initializePrimeCacheUpTo:limit

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.

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]

Usage example(s):

     |p N a b|

     N := 1000.
     p := 1.
     a := (1 to:1000)
	 collect:[:i | p := p nextPrime. p ]
	 thenSelect:[:p | p <= N].
     b := Integer primesUpTo:N.
     self assert:(a = b)

Usage example(s):

     |p N a b|

     N := 1000 nextPrime.
     p := 1.
     a := (1 to:1000)
	 collect:[:i | p := p nextPrime. p ]
	 thenSelect:[:p | p <= N].
     b := Integer primesUpTo:N.
     self assert:(a = b)

Usage example(s):

     |p N a b|

     N := 1000 nextPrime-1.
     p := 1.
     a := (1 to:1000)
	 collect:[:i | p := p nextPrime. p ]
	 thenSelect:[:p | p <= N].
     b := Integer primesUpTo:N.
     self assert:(a = b)

Usage example(s):

     |p N a b|

     N := 100000.
     p := 1.
     a := (1 to:N)
	 collect:[:i | p := p nextPrime. p ]
	 thenSelect:[:p | p <= N].
     b := Integer primesUpTo:N.
     self assert:(a = b)

Usage example(s):

     |p N a b|

     N := 100000 nextPrime.
     p := 1.
     a := (1 to:N)
	 collect:[:i | p := p nextPrime. p ]
	 thenSelect:[:p | p <= N].
     b := Integer primesUpTo:N.
     self assert:(a = b)

Usage example(s):

     |p N a b|

     N := 100000 nextPrime-1.
     p := 1.
     a := (1 to:N)
	 collect:[:i | p := p nextPrime. p ]
	 thenSelect:[:p | p <= N].
     b := Integer primesUpTo:N.
     self assert:(a = b)

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

hasSharedInstances: return true if this class can share instances when stored binary,
that is, instances with the same value can be stored by reference.
Although not always shared (LargeIntegers), these should be treated
so, to be independent of the number of bits in a SmallInt
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

& 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

highWord

return the high 16 bits of a 32 bit value

Usage example(s):

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

lowWord

return the low 16 bits of a 32 bit value

Usage example(s):

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

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

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

maskSet: aMaskInteger

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

printStringBase: aBaseInteger 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:

printStringRadix: aRadix padTo: sz

Usage example(s):

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

| 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

anyBitOfMagnitudeFrom: startBitIndex to: stopBitIndexArg

Tests for any magnitude bits in the interval from start to stopArg.

asByteArray

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

asByteArrayOfSize: size

return my hexBytes in MSB, optionally padded at the left with zeros.
Caveat: should be named asByteArrayMSBOfSize:;
please use asByteArrayOfSize:MSB: to make the byte order explicit

Usage example(s):

     123 asByteArrayOfSize:1 -> #[123]
     123 asByteArrayOfSize:2 -> #[0 123]
     123 asByteArrayOfSize:3 -> #[0 0 123]
     123 asByteArrayOfSize:4 -> #[0 0 0 123]

     255 asByteArrayOfSize:1 -> #[255]

     256 asByteArrayOfSize:1 -> erorr
     256 asByteArrayOfSize:2 -> #[1 0]
     256 asByteArrayOfSize:4 -> #[0 0 1 0]
     256 asByteArrayOfSize:8 -> #[0 0 0 0 0 0 1 0]

     16r87654321 asByteArrayOfSize:4 -> #[135 101 67 33]
     16r87654321 asByteArrayOfSize:8 -> #[0 0 0 0 135 101 67 33]
     16rfedcba9876543210 asByteArrayOfSize:8 -> #[254 220 186 152 118 84 50 16]
     16r0123456789abcdef asByteArrayOfSize:8 -> #[1 35 69 103 137 171 205 239]

asByteArrayOfSize: size MSB: msb

return my hexBytes in MSB ir LSB,
optionally padded at the left with zeros.

Usage example(s):

     123 asByteArrayOfSize:1 -> #[123]
     123 asByteArrayOfSize:2 -> #[0 123]
     123 asByteArrayOfSize:3 -> #[0 0 123]
     123 asByteArrayOfSize:4 -> #[0 0 0 123]

     123 asByteArrayOfSize:1 MSB:false -> #[123]
     123 asByteArrayOfSize:2 MSB:false -> #[123 0]
     123 asByteArrayOfSize:3 MSB:false -> #[123 0 0]
     123 asByteArrayOfSize:4 MSB:false -> #[123 0 0 0]
     123 asByteArrayOfSize:8 MSB:false -> #[123 0 0 0 0 0 0 0]
     123 asByteArrayOfSize:8 MSB:true  -> #[0 0 0 0 0 0 0 123]

     255 asByteArrayOfSize:1 -> #[255]

     256 asByteArrayOfSize:1 -> erorr
     256 asByteArrayOfSize:2 -> #[1 0]
     256 asByteArrayOfSize:4 -> #[0 0 1 0]
     256 asByteArrayOfSize:8 -> #[0 0 0 0 0 0 1 0]

     16r87654321 asByteArrayOfSize:4 -> #[135 101 67 33]
     16r87654321 asByteArrayOfSize:8 -> #[0 0 0 0 135 101 67 33]
     16rfedcba9876543210 asByteArrayOfSize:8 -> #[254 220 186 152 118 84 50 16]
     16r0123456789abcdef asByteArrayOfSize:8 -> #[1 35 69 103 137 171 205 239]

     16rfedcba9876543210 asByteArrayOfSize:9 -> #[0 254 220 186 152 118 84 50 16]
     16r0123456789abcdef asByteArrayOfSize:9 -> #[0 1 35 69 103 137 171 205 239]

     16rfedcba9876543210 asByteArrayOfSize:9 MSB:true  -> #[0 254 220 186 152 118 84 50 16]
     16rfedcba9876543210 asByteArrayOfSize:9 MSB:false -> #[16 50 84 118 152 186 220 254 0]

asEnglishWords
( an extension from the stx:libcompat package )

english name of an integer.
Caveat: not british, but US american;
uses the short scale (i.e. million, billion, trillion, etc.)

Usage example(s):

     1035 asEnglishWords        -> 'one thousand, thirty-five'
     123456 asEnglishWords      -> 'one hundred twenty-three thousand, four hundred fifty-six'
     1234567 asEnglishWords     -> 'one million, two hundred thirty-four thousand, five hundred sixty-seven'
     1234567000 asEnglishWords  -> 'one billion, two hundred thirty-four million, five hundred sixty-seven thousand'
     SmallInteger maxVal asEnglishWords -> 'four quintillion, six hundred eleven quadrillion, six hundred eighty-six trillion, eighteen billion, four hundred twenty-seven million, three hundred eighty-seven thousand, nine hundred three'
     (10 raisedTo:100) asEnglishWords

asLargerPowerOfTwo
( an extension from the stx:libcompat package )

same as nextPowerOf2 for Squeak compatibility

Usage example(s):

     40 asLargerPowerOfTwo  64
     40 asSmallerPowerOfTwo

asSmallerPowerOfTwo
( an extension from the stx:libcompat package )

same as nextPowerOf2 for Squeak compatibility

Usage example(s):

     32 asLargerPowerOfTwo   
     32 asSmallerPowerOfTwo  

     33 asLargerPowerOfTwo   
     33 asSmallerPowerOfTwo

atRandom
( an extension from the stx:libbasic2 package )

return a random number between 1 and myself

Usage example(s):

     100 atRandom
     1000 atRandom

atRandom: aRandomGenerator

return a random number between 1 and myself

Usage example(s):

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

bitShiftMagnitude: shift

-1 bitShiftMagnitude:1
-2 bitShift:-1
-2 bitShift:-1

isPowerOfTwo

return true, if the receiver is a power of 2

primeFactorsOn: aStream
( an extension from the stx:libcompat package )

Recursively calculate the primefactors of myself and put the factors into the given stream

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

printPaddedWith: padChar to: size base: base

attention: prints right-padded; see printLeftPadded.

Usage example(s):

     1234 printPaddedWith:$0 to:4 base:16

printStringHex

return my printString in base 16;
same as printStringBase:

Usage example(s):

     4096 printStringHex

printStringRoman

return my roman printString;
almost the same as romanPrintString:

raisedTo: exp modulo: mod

sqrtFloor
( an extension from the stx:libcompat package )

Return the integer part of the square root of self

Usage example(s):

     9 sqrtFloor  => 3
     10 sqrtFloor => 3
     16 sqrtFloor => 4
     1234567890 squared sqrtFloor => 1234567890

     1234567890 squared integerSqrt => 1234567890

Compatibility-V'Age

<< aNumber

V'Age compatibility: left shift

Usage example(s):

     1 << 5
     64 << -5

>> aNumber

V'Age compatibility: right shift

Usage example(s):

     1 >> -5
     64 >> 5

Javascript support

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

approximation series

integerCbrtWithGuess: initialGuess: return the largest integer which is less or equal to the receiver's cubic root.
For large integers, this provides better results than the float cbrt 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.
integerSqrtWithGuess: initialGuess: 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.

bcd conversion

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          => 55
     16r127 decodeFromBCD
     16r800000 decodeFromBCD
     16r8000000 decodeFromBCD
     16r80000000 decodeFromBCD
     16r800000000 decodeFromBCD
     16r127567890 decodeFromBCD
     16r1234567890 decodeFromBCD

     16r5A decodeFromBCD          => error
     16rFF decodeFromBCD          => error

encodeAsBCD

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

Usage example(s):

     55 encodeAsBCD                     => 85
     55 encodeAsBCD hexPrintString      => '55'
     127 encodeAsBCD hexPrintString     => '127'
     8912345 encodeAsBCD hexPrintString => '8912345'
     89123456 encodeAsBCD hexPrintString  => '89123456'
     891234567 encodeAsBCD hexPrintString => '891234567'
     900000000 encodeAsBCD hexPrintString => '900000000'
     1073741823 encodeAsBCD hexPrintString  => '1073741823'
     1073741824 encodeAsBCD hexPrintString  => '1073741824'
     1073741825 encodeAsBCD hexPrintString  => '1073741825'
     1891234567 encodeAsBCD hexPrintString  => '1891234567'
     8912345678 encodeAsBCD hexPrintString  => '8912345678'
     1234567890 encodeAsBCD hexPrintString  => '1234567890'
     5 encodeAsBCD                          => 5

bit operators

allMask: aMaskInteger

return true if all 1-bits in aMaskInteger are also 1 in the receiver

Usage example(s):

     2r00001111 allMask:2r00000001   => true
     2r00001111 allMask:2r00011110   => false
     2r00001111 allMask:2r00011111   => false
     2r00001111 allMask:2r00001111   => true
     2r00001111 allMask:2r00000000   => true

anyMask: aMaskInteger

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

Usage example(s):

     2r00001111 anyMask:2r00000001   => true
     2r00001111 anyMask:2r11110000   => false

asLowBitMask

return a bit mask for the n lowest bits.

Usage example(s):

     4 asLowBitMask    -> 2r1111
     2 asLowBitMask    -> 2r0011
     16 asLowBitMask   -> 2r1111111111111111

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

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.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

bitXored: anInteger

subclasses may redefine this to possibly change the receiver
and return an possibly unnormalized Integer.
Use to speed up cryptographic computations.

bitsFrom: lowBitIndex to: highBitIndex

return the n middle bits from low to high index (both 1-based).

Usage example(s):

     2r110011111001 bitsFrom:1 to:4    -> 2r1001
     2r110011111001 bitsFrom:2 to:4    -> 2r100
     2r110011111001 bitsFrom:3 to:8    -> 2r111110
     2r110011111001 bitsFrom:8 to:12   -> 2r11001

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     -> '3FFFFF7F'
     (16r3fff0000 changeMask:16r80 to:1) hexPrintString     -> '3FFF0080'
     (16r3fffffFF changeMask:16rFF to:0) hexPrintString     -> '3FFFFF00'
     (16r3fff0000 changeMask:16rFF to:1) hexPrintString     -> '3FFF00FF'
     (16r3fffffFF changeMask:16rFF to:false) hexPrintString -> '3FFFFF00'
     (16r3fff0000 changeMask:16rFF to:true) hexPrintString  -> '3FFF00FF'

even

return true if the receiver is even

Usage example(s):

     16r112233445566778899 even
     16r112233445566778800 even
     1 even
     2 even

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

highBitOfMagnitude

return the high bit index of my magnitude bits
(i.e. of my absolute value)

Usage example(s):

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

highBits: nBits

return the n highest bits.
If n is > than the number of bits, the result is undefined.
Useful for approximation (reducing the number of bits of colors).

Usage example(s):

     2r110011111111 highBits:4    -> 2r1100
     2r110011111111 highBits:2    -> 3
     2r110011111111 highBits:1    -> 1
     2r110011111111 highBits:5    -> 2r11001
     2r110011111111 highBits:8    -> 2r11001111
     2r110011111111 highBits:9    -> 2r110011111
     2r110011111111 highBits:12   -> 2r110011111111

     error cases:
     2r110 highBits:6             -> 2r110000
     2r110 highBits:4             -> 2r1100
     2r110011111111 highBits:13   -> 2r1100111111110

     100 factorial highBits:8

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

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

lowBits: nBits

return the n lowest bits.
For protool completeness.

Usage example(s):

     2r110011111001 lowBits:4    -> 2r1001
     2r110011111101 lowBits:2    -> 1
     100 factorial lowBits:16    -> 0
     16r12345 lowBits:16         -> 16r2345

noMask: aMaskInteger

return true if no 1-bit in anInteger is 1 in the receiver

Usage example(s):

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

odd

return true if the receiver is odd

Usage example(s):

     16r112233445566778899 odd
     16r112233445566778800 odd
     1 odd
     2 odd

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

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
     2r1000000000000000000000000000000000000000000000000000 bitAt:1  => 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

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

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]

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]

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

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  
     0xFFFFFFFF clearBit:1  
     0x1FFFFFFFF clearBit:1  
     0x3FFFFFFFF clearBit:1  
     0x400000000 clearBit:1  
     0x1FFFFFFFFFFFFFFF clearBit:1  
     0x3FFFFFFFFFFFFFFF clearBit:1  
     0x4000000000000001 clearBit:1  
     0xFFFFFFFFFFFFFFFF clearBit:1  
     0x1FFFFFFFFFFFFFFFF clearBit:1

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

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

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

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

byteAt: anIndex

compatibility with ByteArrays etc.

Usage example(s):

	12345678 byteAt:2
	12345678 digitBytes at:2

	-12345678 byteAt:2
	-12345678 digitBytes at:2

byteSwapped16

byte swap a 16bit value; lsb -> msb;
i.e. a.b-> b.a
Any higher bits are ignored.
Useful for communication protocols

Usage example(s):

     16r12345678901234567890 byteSwapped16 hexPrintString:16 -> '0000000000009078'

byteSwapped32

byte swap a 32bit value; lsb -> msb;
i.e. a.b.c.d -> d.c.b.a
Any higher bits are ignored.
Useful for communication protocols

Usage example(s):

     16r12345678901234567890 byteSwapped32 hexPrintString:16 => '0000000090785634'

byteSwapped64

byte swap a 64bit value; lsb -> msb;
i.e. a.b.c.d.e.f.g.h -> h.g.f.e.d.c.b.a
Any higher bits are ignored.
Useful for communication protocols

Usage example(s):

     16r1234567890123456789 byteSwapped64 hexPrintString  => '8967452301896745'
     16r0102030405060708 byteSwapped64 hexPrintString:16  => '0807060504030201'
     16rfffefdfcfbfaf9f8 byteSwapped64 hexPrintString:16  => 'F8F9FAFBFCFDFEFF'

digitByteLength

return the number bytes required for a 2's complement
binary representation of this Integer.
The name 'digit' is a bit misleading: 'digit' here means byte (not decimal digit).

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

digitBytes

return a byteArray filled with the receiver's bits
(8 bits of the absolute value per element),
least significant byte is first.
The name 'digit' is a bit misleading: 'digit' here means byte (not decimal digit).

** This method must be redefined in concrete classes (subclassResponsibility) **

digitBytesMSB

return a byteArray filled with the receiver's bits
(8 bits of the absolute value per element),
most significant byte is first.
The name 'digit' is a bit misleading: 'digit' here means byte (not decimal digit).

** This method must be redefined in concrete classes (subclassResponsibility) **

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.
The name 'digit' is a bit misleading: 'digit' here means byte (not decimal digit).

Usage example(s):

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

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):

     0x8000 digitLength        -> 2
     -0x8000 digitLength       -> 2

     0x8000 signedDigitLength  -> 3
     -0x8000 signedDigitLength -> 2

     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

swapBytes

swap bytes pair-wise (i.e. of int16s) 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       => 'EEFF1122'
        16rFFEEAA2211 swapBytes hexPrintString     => 'FF00AAEE1122'
        16r2211 swapBytes hexPrintString           => '1122'
        16rFF3FFFFF swapBytes hexPrintString       => '3FFFFFFF'
        16r01020304 swapBytes hexPrintString       => '2010403'
        self assert:(SmallInteger maxVal swapBytes swapBytes == SmallInteger maxVal)

coercing & converting

asFloat

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

Usage example(s):

     1234567890 asFloat
     1234567890 asFloat asInteger
     12345678901234567890 asFloat
     12345678901234567890 asFloat asInteger

asFraction

return a Fraction with same value as receiver

asIEEEFloat
( an extension from the stx:libbasic2 package )

return an IEEE soft float with same value as the receiver

Usage example(s):

     1234567890 asIEEEFloat
     1234567890 asIEEEFloat asInteger
     12345678901234567890 asIEEEFloat
     12345678901234567890 asIEEEFloat asInteger

asIEEEFloat: numBits

return an IEEE soft float with same value as receiver and numBits overAll
numBits should be a multiple of 8,
i.e. 32 for IEEE single, 64 for double, 128 for quadFloat, etc.)

Usage example(s):

     (10 asIEEEFloat:8)
     (10 asIEEEFloat:8) asInteger
     (1234567890 asIEEEFloat:8)
     (1234567890 asIEEEFloat:8) asInteger

     (10 asIEEEFloat:16)
     (10 asIEEEFloat:32)
     (10 asIEEEFloat:64)
     (10 asIEEEFloat:128)
     (10 asIEEEFloat:256)
     (10 asIEEEFloat:1024)

asIEEEFloat: numBits numBitsInExponent: numBitsInExponent

return an IEEE soft float with same value as receiver and numBits overAll
numBits should be a multiple of 8,
i.e. 32 for IEEE single, 64 for double, 128 for quadFloat, etc.)

Usage example(s):

     (10 asIEEEFloat:8 numBitsInExponent:3)
     (10 asIEEEFloat:8 numBitsInExponent:3) asInteger
     (1234567890 asIEEEFloat:16 numBitsInExponent:5)
     (1234567890 asIEEEFloat:16 numBitsInExponent:5) asInteger

asInteger

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

asIntegerChecked

return an integer with same value - might truncate.
Raises an error for non-finite numbers (NaN or INF)

asLargeFloat
( an extension from the stx:libbasic2 package )

return a LargeFloat with same value as myself.
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 
     100 factorial asLargeFloat    
     100 factorial asLargeFloat asInteger = 100 factorial

asLargeFloatPrecision: n
( an extension from the stx:libbasic2 package )

return a LargeFloat with same value as myself.
If the largeFloat class is not present, a regular float is returned

Usage example(s):

     1234567890 asLargeFloatPrecision:10
     12345678901234567890 asLargeFloatPrecision:10

asLongFloat

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

asModuloNumber

return a precomputed modulo number

asOctaFloat
( an extension from the stx:libbasic2 package )

return a OctaFloat with same value as myself.
Since octaFloats have a limited precision,
you may loose bits when doing this for a large integer.

Usage example(s):

     1234567890 asOctaFloat
     1234567890 asOctaFloat asInteger
     12345678901234567890 asOctaFloat
     12345678901234567890 asOctaFloat asInteger

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

asQuadFloat
( an extension from the stx:libbasic2 package )

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

asRaisedNumber
( an extension from the stx:libbasic2 package )

100 asRaisedNumber
0.1 asRaisedNumber
(1 / 100) asRaisedNumber

asScaledDecimal

return the receiver as a scaledDecimal number

Usage example(s):

     100 asScaledDecimal    
     100 asScaledDecimal + 0.1 asScaledDecimal 
     100 asScaledDecimal + (0.1 asScaledDecimal:1)

asScaledDecimal: scale

return the receiver as scaledDecimal number, with the given number
of post-decimal-point digits.

Usage example(s):

     100 asScaledDecimal:2
     100 asScaledDecimal + (0.1 asScaledDecimal:2)

asShortFloat

return a ShortFloat with same value as receiver

asTrueFraction

Answer a fraction or integer that EXACTLY represents the receiver

asUnsignedInt

return an integer representing my unsigned INT value.
Notice, that the returned integer's size
depends heavily on the receiver' number of bits;
You will get 16rFFFFFFFF on 32bit machines,
but 16rFFFFFFFFFFFFFFFF on 64 bit machines.
So use this only for printing or certain bit operations (emulating C semantics).

Usage example(s):

     -1 asUnsignedInt hexPrintString          -> 'FFFFFFFF' / 'FFFFFFFFFFFFFFFF'
     16r-8000 asUnsignedInt hexPrintString    -> 'FFFF8000' / 'FFFFFFFFFFFF8000'
     16r80000000 asUnsignedInt hexPrintString -> '80000000' 
     16r-7FFFFFFF asUnsignedInt hexPrintString -> '80000001' 
     16r-80000000 asUnsignedInt hexPrintString -> '80000000'

coerce: aNumber

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

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

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

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

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

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

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

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

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 => 0

     -- not out of range
     9223372036854775808 zigZagEncoded zigZagDecodedValue =>  9223372036854775808


     (-50 abs = 50 abs) => (50 zigZagEncoded dist:50 zigZagEncoded) == 1  -- but not vice versa

     -5 dist:5                                  => 10
     -50 dist:50                                => 100
     -5 zigZagEncoded dist:5 zigZagEncoded      => 1
     -50 zigZagEncoded dist:50 zigZagEncoded    => 1

zigZagEncoded32BitValue

Usage example(s):

     -5 to:5 collect:[:each | each zigZagEncoded32BitValue]  

     0 zigZagEncoded32BitValue -> 0
     -1 zigZagEncoded32BitValue -> 1
     1 zigZagEncoded32BitValue -> 2
     -2 zigZagEncoded32BitValue -> 3
     2 zigZagEncoded32BitValue -> 4

     16r-7FFFFFFF zigZagEncoded32BitValue -> 4294967293
     16r7FFFFFFF zigZagEncoded32BitValue -> 4294967294
     16r-80000000 zigZagEncoded32BitValue -> 4294967295

     -- out of range:
     2147483648 zigZagEncoded32BitValue  -> 0 (should be 4294967296)
     -2147483649 zigZagEncoded32BitValue -> 1 (should be 4294967297)

zigZagEncoded64BitValue

Usage example(s):

     -5 to:5 collect:[:each | each zigZagEncoded64BitValue]  

     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 => 0  (instead of 18446744073709551615)
     -16r8000000000000001 zigZagEncoded64BitValue => 1  (instead of 18446744073709551616)

zigZagEncodedValue

Usage example(s):

        2147483648 zigZagEncodedValue -> 4294967296
        -2147483649 zigZagEncodedValue -> 4294967297

     out of 32bit range:
        2147483648 zigZagEncoded32BitValue  -> 0 (should be 4294967296)
        -2147483649 zigZagEncoded32BitValue -> 1 (should be 4294967297)

comparing

hash

redefined to return smallInteger hashValues

Usage example(s):

	-20000000000000 hash
	 20000000000000 hash

dependents access

addDependent: anObject: It doesn't make sense to add dependents to a shared instance.
Silently ignore ...
onChangeSend: selector to: someOne: It doesn't make sense to add dependents to a constant; will never change.
Silently ignore ...

double dispatching

differenceFromFraction: aFraction

sent when a fraction does not know how to subtract the receiver, an integer

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

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

productFromFraction: aFraction

sent when a fraction does not know how to multiply the receiver, an integer

quotientFromFraction: aFraction

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

sumFromFraction: aFraction

sent when a fraction does not know how to add the receiver, an integer

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

inspecting

inspectorExtraAttributes
( an extension from the stx:libtool package ): extra (pseudo instvar) entries to be shown in an inspector.
inspectorValueListIconFor: anInspector
( an extension from the stx:libtool package ): returns the icon to be shown alongside the value list of an inspector

iteration

timesCollect: aBlock

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

Usage example(s):

     10 timesCollect:[:i | i squared]

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]

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

mathematical functions

acker: n

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

Usage example(s):

1 acker:n

Usage example(s):

1 acker:0

Usage example(s):

     3 acker:2
     3 acker:7
     0 acker:10
     1 acker:4  6 5 4 3
     2 acker:6 15  13  11  9  7  5
     3 acker:3 61 29 13 5
     3 acker:7 1021
     3 acker:8 2045
     3 acker:10 8189
     Time millisecondsToRun:[3 acker:10] 801
     Time millisecondsToRun:[3 acker:11] 3982
     Time millisecondsToRun:[3 acker:12] 18008
     3 acker:100 
     4 acker:0     
     4 acker:1     
     4 acker:2

binco: kIn

an alternative name for the binomial coefficient for squeak compatibility

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)    
     (100000 binomialCoefficient:100000)     
     (0 binomialCoefficient:0)

     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

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

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    #(-1 3 1)
     14 extendedEuclid:2    #(0 1 2)
     25 extendedEuclid:15   #(-1 2 5)

factorial

return fac(self) (i.e. 1*2*3...*self)

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

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]

     [20000 factorialIter] benchmark:'20000 factorialIter'    149ms (2012 2.5Ghz mac)
     [50000 factorialIter] benchmark:'50000 factorialIter'    470ms
     [100000 factorialIter] benchmark:'100000 factorialIter'   2.2s
     [200000 factorialIter] benchmark:'200000 factorialIter'  11.2s

     [20000 factorialEvenOdd] benchmark:'20000 factorialEvenOdd'    28ms
     [50000 factorialEvenOdd] benchmark:'50000 factorialEvenOdd'   177ms
     [100000 factorialEvenOdd] benchmark:'100000 factorialEvenOdd' 646ms
     [200000 factorialEvenOdd] benchmark:'200000 factorialEvenOdd'   2.4s

factorialHalf

an algorithm, which does it with half the number of multiplications.
this is faster than factorialIter to roughly 60000.
ATTENTION:
Bad Algorithm
This is included to demonstration purposes - if you really need
factorial numbers, use the tuned #factorial, which is faster.
This is slightly faster than the recursive algorithm, and does not
suffer from stack overflow problems (with big receivers)

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

factorialIter

return fac(self) (i.e. 1*2*3...*self) using an iterative algorithm.
ATTENTION:
Bad Algorithm
This is included to demonstration purposes - if you really need
factorial numbers, use the tuned #factorial, which is faster.
This is slightly faster than the recursive algorithm, and does not
suffer from stack overflow problems (with big receivers)

Usage example(s):

     10 factorial
     1000 factorial
     10000 factorial
     10000 factorialR

     [100 factorial] benchmark:'100 factorial'
     [100 factorialIter] benchmark:'100 factorialIter'

     [1000 factorial] benchmark:'1000 factorial'
     [1000 factorialIter] benchmark:'1000 factorialIter'
     [1000 factorialR] benchmark:'1000 factorialR'

     [2000 factorial] benchmark:'2000 factorial'
     [2000 factorialIter] benchmark:'2000 factorialIter'

     [10000 factorial] benchmark:'10000 factorial'
     [10000 factorialIter] benchmark:'10000 factorialIter'

     -1 factorial

factorialR

return fac(self) (i.e. 1*2*3...*self) using a recursive algorithm.
ATTENTION:
Bad 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
     100 factorialR
     1000 factorialR
     [1000 factorial] benchmark:'1000 factorialR'

fib

compute the fibonacci 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
     10000 fib
     100000 fib
     1000000 fib        => a number with around 209000 digits
     1000000 fib log10  => 208987.290764977

fib_binet

compute an approximation to the n'th fibonacci number using Binet
(mhm: Euler / d Moivre).
Caveat: because it uses limited double prec. arithmetic,
it will suffer from rounding errors
and also from overflow for large receivers

Usage example(s):

     30 fib       -> 832040
     60 fib       -> 1548008755920
     1000 fib     -> 43466557686937456435688527675040625802564660517371780402481729089536555417949051890403879840079255169295922593080322634775209689623239873322471161642996440906533187938298969649928516003704476137795166849228875
     5000 fib     -> 387896845438832563370191630832590531208212771464624.....74382863125
     50000 fib    -> 1077773489307297478027903885511948082962510676941...5364252373553125

     30 fib_binet   -> 832040.0
     60 fib_binet   -> 1.54800875592e+12
     1000 fib_binet -> 4.34665576869389E+208
     5000 fib_binet -> 3.878968454388326074E+1044
     50000 fib_binet -> 1.07777348930729745e+10449

fib_helper

compute the fibonacci 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) ]

gcd: anInteger

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

Usage example(s):

     3141589999999999 gcd:1000000000000000

     4500000000000000 gcd:3000000000000000   1500000000000000
     -4500000000000000 gcd:3000000000000000  1500000000000000
     4500000000000000 gcd:-3000000000000000  1500000000000000
     -4500000000000000 gcd:-3000000000000000 -1500000000000000

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

gfMul2_128: factorIn

Galoise multiplication inf GF(2^128).
This is defined by 1 + a + a^2 + a^7 + a^128.
Candidate for faster implementation - especially for Intel processors:
https://www.intel.cn/content/dam/www/public/us/en/documents/white-papers/carry-less-multiplication-instruction-in-gcm-mode-paper.pdf
Warning: this may destruct the passed in factorIn arg (sigh)
make sure its a throw -away LargeInt

integerCbrt

return the largest integer which is less or equal to the receiver's cubic root.
For large integers, this provides better results than the float cbrt 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.

Notice the special tuning for small numbers;
this was done to support some of the algebra functions in the Physics package,
which deal with small powers in the formula handling code

Usage example(s):

Transcript showCR: e'guess: {initialGuess} result: {meAbs integerCbrtWithGuess:initialGuess}'.

Usage example(s):

     |n cbrt|
     n := 1000 factorial.
     cbrt := n integerCbrt.
     self assert:(cbrt cubed <= n).
     self assert:((cbrt+1) cubed >= n).
     [ n integerCbrt] benchmark:'integerCbrt'

     333 cbrt -> 6.93130076842881
     342 cbrt -> 6.99319065718087
     343 cbrt -> 7.0
     344 cbrt -> 7.00679612077345

     333 integerCbrt -> 6
     342 integerCbrt -> 6
     343 integerCbrt -> 7
     344 integerCbrt -> 7

     10239552004900 integerCbrt
     10239552004900 cbrt
     10239552311579 integerCbrt
     10239552311579 cbrt
     1023955231157912341234 cbrt 10079221.5084596
     1023955231157912341234 integerCbrt 10079221
     10239552311579123412341023955231157912341234 integerCbrt

     100000 cubed integerCbrt
     100000 squared cubed integerCbrt integerSqrt

     1000 factorial integerCbrt
     1000 factorial asFloat cbrt
     1000 factorial asLargeFloat cbrt

     500 factorial cubed - 500 factorial cubed integerCbrt cubed  -> 0
     1000 factorial - (1000 factorial integerCbrt + 1) cubed
     1000 factorial between:(1000 factorial integerCbrt cubed) and:((1000 factorial integerCbrt + 1) cubed)

     |n|
     n := 1000 factorial cubed.
     self assert:n isPerfectCube.
     [n isPerfectCube] benchmark:'cube check bigNr hit'

     |n|
     n := 1000 factorial cubed - 1.
     self assert:n isPerfectCube not.
     [n isPerfectCube] benchmark:'cube check bigNr miss'.

     1 to:1000000 do:[:n |
        self assert:(n integerCbrt cubed = n) == n isPerfectCube
     ]

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 log2           8529.39800420477
      1000 factorial integerLog2    8529
      1000 factorial log:2          8529.39800420477
      1000 factorial asFloat log2   INF      overflow

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

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.

Notice the special tuning for small numbers;
this was done to support some of the algebra functions in the Physics package,
which deal with small powers in the formula handling code

Usage example(s):

      [1000 factorial integerSqrt] benchmark:'intSqrt'.

Usage example(s):

Transcript showCR: e'guess: {initialGuess} result: {meAbs integerSqrtWithGuess:(1 bitShift:self highBit//2)}'.

Usage example(s):

     90 integerSqrt -> 9

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

     333 integerSqrt -> 18
     324 integerSqrt -> 18
     325 integerSqrt -> 18
     323 integerSqrt -> 17

     0 integerSqrt -> 0
     1 integerSqrt -> 1
     2 integerSqrt -> 1

     5 sqrt -> 2.23606797749979
     5 integerSqrt -> 2

     10239552004900 integerSqrt -> 3199930
     10239552004900 sqrt        -> 3199930.0

     10239552311579 integerSqrt -> 3199930
     10239552311579 sqrt        -> 3199930.04791964

     10239552311580 integerSqrt  -> 3199930

     10239562322990 integerSqrt  -> 3199931
     10239562322990 sqrt         -> 3199931.61223642

     |n|
     n := 5397346292805549782720214077673687804022210808238353958670041357153884304.
     n integerSqrt squared.
     self assert:(n integerSqrt squared = n).

     5397346292805549782720214077673687804022210808238353958670041357153884304 sqrt squared
     = 5397346292805549782720214077673687806275517530364350655459511599582614290 integerSqrt squared

     self assert:(1000 factorial - 1000 factorial integerSqrt squared) >= 0
     self assert:(1000 factorial - (1000 factorial integerSqrt + 1) squared < 0)
     1000 factorial between:(1000 factorial integerSqrt squared) and:((1000 factorial integerSqrt + 1) squared)

     [
         1 to:1000000 do:[:n |
            self assert:(n integerSqrt squared = n) == n isPerfectSquare
         ]
     ] benchmark:'many many'

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

lcm: anInteger

return the least common multiple (using gcd:)

Usage example(s):

     65 lcm:15
     3 lcm:15

ln

return the natural logarithm of the receiver.
this computes a float value,
which is correct up to the float precision (esp. for huge integers)

Usage example(s):

      10 ln
      1000 ln
      1000 ln
      10000 ln
      1e5 ln
      1e21 ln

      10000000000000000000000.0 ln       50.656872045869
      10000000000000000000000   ln       50.656872045869
      20000000000000000000000.0 ln       51.3500192264289
      20000000000000000000000   ln       51.3500192264289
      30000000000000000000000.0 ln       51.7554843345371
      30000000000000000000000   ln       51.7554843345371
      40000000000000000000000.0 ln       52.0431664069889
      40000000000000000000000   ln       52.0431664069889
      50000000000000000000000.0 ln       52.2663099583031
      50000000000000000000000   ln       52.2663099583031
      80000000000000000000000.0 ln       52.7363135875488
      80000000000000000000000   ln       52.7363135875488
      90000000000000000000000.0 ln       52.8540966232052
      90000000000000000000000   ln       52.8540966232052

      100 factorial asFloat ln           363.739375555563
      100 factorial ln                   363.739375555564

      1000 factorial asFloat ln          INF
      1000 factorial ln                  5912.12817848816

      10000 factorial ln                 82108.9278368144
      100000 factorial ln                1051299.22189912

log10

return the base-10 logarithm of the receiver.
Raises an exception, if the receiver is less or equal to zero.
This computes a float value,
which is correct up to the float precision (esp. for huge integers)

Usage example(s):

^ self asFloat log10 floor

Usage example(s):

      10 log10        => 1.0
      15 log10        => 1.17609125905568
      1000 log10      => 3.0
      10000 log10     => 4.0
      1e5 log10       => 5.0
      1e21 log10      => 21.0
      16rFFFFFFFFFFFFFFFF log10 => 19.2659197224948
      16r7FFFFFFFFFFFFFFF log10 => 18.9648897268308
      16r3FFFFFFFFFFFFFFF log10 => 18.6638597311668
      16r1FFFFFFFFFFFFFFF log10 => 18.3628297355029
      16r0FFFFFFFFFFFFFFF log10 => 18.0617997398389      60 bits
      16r00FFFFFFFFFFFFFF log10 => 16.8576797571829      56 bits
      16r003FFFFFFFFFFFFF log10 => 16.255619765855       54 bits
      16r001FFFFFFFFFFFFF log10 => 15.954589770191       53 bits
      16r000FFFFFFFFFFFFF log10 => 15.653559774527       52 bits

      16r000FFFFFFFFFFFFF               =  4503599627370495
      10 ** (16r000FFFFFFFFFFFFF log10) => 4.50359962737049e+15

      10000000000000000000000.0 log10       => 22.0
      10000000000000000000000   log10       => 22.0
      20000000000000000000000.0 log10       => 22.301029995664
      20000000000000000000000   log10       => 22.301029995664
      30000000000000000000000.0 log10       => 22.4771212547197
      30000000000000000000000   log10       => 22.4771212547197
      40000000000000000000000.0 log10       => 22.602059991328
      40000000000000000000000   log10       => 22.602059991328
      50000000000000000000000.0 log10       => 22.698970004336
      50000000000000000000000   log10       => 22.698970004336
      80000000000000000000000.0 log10       => 22.9030899869919
      80000000000000000000000   log10       => 22.9030899869919
      90000000000000000000000.0 log10       => 22.9542425094393
      90000000000000000000000   log10       => 22.9542425094393

      100 factorial asFloat log10           => 157.970003654716
      100 factorial log10                   => 157.970003654716

      1000 factorial asFloat log10          => INF
      1000 factorial log10                  => 2567.60464422213

      10000 factorial log10                 => 35659.4542745208
      100000 factorial log10                => 456573.450899971

log2

return the log2 of the receiver.
this computes a float value,
which is correct up to the float precision (esp. for huge integers)

Usage example(s):

^ self asFloat log2

Usage example(s):

      8.0 log2  => 3.0
      8 log2    => 3

      10.0 log2  => 3.32192809488736
      10 log2    => 3.32192809488736

      100000.0 log2  => 16.6096404744368
      100000 log2    => 16.6096404744368 

      10000000000000000.0 log2   => 53.1508495181978
      10000000000000000   log2   => 53.1508495181978

      1000000000000000000.0 log2  59.7947057079725
      1000000000000000000   log2  59.7947057079725

      10000000000000000000000.0 log2    73.082418087522
      10000000000000000000000 log2      73.082418087522
      20000000000000000000000.0 log2    74.082418087522
      20000000000000000000000 log2      74.082418087522
      20000000000000000000000.0 log2    74.082418087522
      20000000000000000000000 log2      74.082418087522
      40000000000000000000000.0 log2    75.082418087522
      40000000000000000000000 log2      75.082418087522
      80000000000000000000000.0 log2    76.082418087522
      80000000000000000000000 log2      76.082418087522
      90000000000000000000000.0 log2    76.2523430889643
      90000000000000000000000 log2      76.2523430889643
      99999999999999999999999.0 log2    76.4043461824093
      99999999999999999999999 log2      76.4043461824093

      51 factorial log2               219.880563405562
      51 factorial asFloat log2       219.880563405562

      1000 factorial log2             8529.39800420477
      1000 factorial asFloat log2     INF

      10000 factorial log2            118458.143002882
      10000 factorial asFloat log2    INF

      100000 factorial log2           1516704.17392429

      (1<<61) log2                => 61
      (1<<62) log2                => 62
      (1<<63) log2                => 63
      (1<<64) log2                => 64
      ((1<<64) + 1) log2          => 64.0
      ((1<<64) + 1000000) log2    => 64.0000000000001

      1<<100000) log2                100000

log: n

return the log base n of the receiver.
this computes a float value,
which is correct up to the float precision (esp. for huge integers)

Usage example(s):

      100 factorial asFloat log10           157.970003654716
      100 factorial log10                   157.970003654716
      100 factorial log:10                  157.970003654716

      1000 factorial asFloat log10          INF
      1000 factorial log10                  2567.60464422213
      1000 factorial log:10                 2567.60464422213

      (10 raisedTo:100) log10           
      (10 raisedTo:100) log:10          
      (10 raisedTo:100) log:3               209.590327428938

      nBytes req'd to store:
      (10 raisedTo:100) log:256             41.524101186092

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

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 (*)
If limitArgOrNil is nil, all prime factors are returned,
otherwise, only prime factors upto that limit (and slightly above) are returned.

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

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)
     ]
     (2*2*2*3*3*3*3*4*4*4*4*4*5*5*6*11*11*11) primeFactors product

     13195 primeFactors             Bag('7(*1)' '5(*1)' '29(*1)' '13(*1)')
     13195 primeFactorsUpTo:20      Bag('7(*1)' '5(*1)' '29(*1)' '13(*1)')
     13195 primeFactorsUpTo:10      Bag('7(*1)' '5(*1)')
     12 primeFactors                Bag('3(*1)' '2(*2)')
     2 primeFactors                 #()
     3 primeFactors                 Bag()
     5 primeFactors                 Bag()
     14 primeFactors                Bag('7(*1)' '2(*1)')
     13423453625634765 primeFactors Bag('5(*1)' '3(*1)' '19(*1)' '29(*1)' '1624132320101(*1)')
     13423453625634765 isPrime      false
     13423453625634765 integerSqrt  115859628

     13423453625634765 gcd:(3 * 5 * 19 * 29) 8265
     13423453625634765 / 8265                1624132320101
     13423453625634765 primeFactors
     1624132320101 isPrime                   true
     1624132320101 gcd: 8265                 1
     1624132320101 primeFactors              Bag('1624132320101(*1)')

     1000000 primeFactors                    Bag('5(*6)' '2(*6)')
     100000000 primeFactors                  Bag('5(*8)' '2(*8)')
     1000000000 primeFactors                 Bag('5(*9)' '2(*9)')

     [ 1000 timesRepeat:[ 10000000000000000000000000000000000000 primeFactors ]] benchmark:'bigFactors'
     [ 1000 timesRepeat:[ 10000000000000000000000000000000000001 primeFactors ]] benchmark:'bigFactors'
     10000000000000000000000000000000000001 isPrime
     10000000000000000000000000000000000001 primeFactors
     2147483647 primeFactors
     2147483645 primeFactors
     [2147483742 primeFactors] benchmark:'2147483742 primeFactors'
     [2147483645 primeFactors] benchmark:'2147483645 primeFactors'
     [7777777777777777777777777772 primeFactors] benchmark:'7777777777777777777777777772 primeFactors'
     7777777777777777777777777772 primeFactors

     1485931918335559259347 * 1485931918335559259503 * 2687 * 487 * 2 * 2
     11557248253721016462801111102525726694061213167316 primeFactors

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
			     ]
			    ]

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

raisedToInteger: exp

return the receiver raised to exp.
The caller must ensure that the arg is actually an integer.
Warning: if the receiver is a float/double,
currently INF may be returned on overflow.
This may be changed silently to raise an error in future versions.

Usage example(s):

     0x10000000000000000 raisedToInteger:6

     (2 raisedToInteger:216)                ->  105312291668557186697918027683670432318895095400549111254310977536
     (2.0 raisedToInteger:216)              -> 1.05312291668557E+65
     (2.0 asLongFloat) raisedToInteger:216  -> 1.053122916685571867E+65
     (2.0 asShortFloat) raisedToInteger:216 -> inf
     (2.0 asQDouble) raisedToInteger:216

     (2 raisedTo:216)
            -> 105312291668557186697918027683670432318895095400549111254310977536
     (2.0 raisedToInteger:216) asInteger - (2 raisedToInteger:216)
     (2.0 raisedToInteger:400) asInteger - (2 raisedToInteger:400)
     (2.0 raisedToInteger:500) asInteger - (2 raisedToInteger:500)
     (2.0 raisedToInteger:1000) asInteger - (2 raisedToInteger:1000)

     (2 raisedToInteger:216) asFloat
     (2 raisedTo:216) asFloat
            -> 1.05312E+65

     (2 raisedToInteger:500)
     (2 raisedTo:500)
            -> 3273390607896141870013189696827599152216642046043064789483291368096133796404674554883270092325904157150886684127560071009217256545885393053328527589376
     (2 raisedTo:-500)
            -> (1/3273390607896141870013189696827599152216642046043064789483291368096133796404674554883270092325904157150886684127560071009217256545885393053328527589376)
     2 raisedToInteger:10
            -> 1024
    -2 raisedToInteger:10
            -> 1024
     -2 raisedToInteger:9
            -> -512
     10 raisedToInteger:-10
            -> (1/10000000000)
     2 raisedToInteger:0
            -> 1
     2 raisedToInteger:-1
            -> (1/2)

     Time millisecondsToRun:[
        10000 timesRepeat:[
            (2 raisedToInteger:500)
        ]
     ]

     Time millisecondsToRun:[
        |bigNum|
        bigNum := 2 raisedToInteger:500.
        10 timesRepeat:[
            (bigNum raisedToInteger:500)
        ]
     ]

timesTwoPower: anInteger

Return the receiver multiplied by 2 raised to the power of the argument.
I.e. self * (2**n)
Warning: may return infinity, if the result is too big;
or zero if too small.
For protocol completeness wrt. Squeak and ST80.

Usage example(s):

     0 timesTwoPower:0  = 0*1 -> 0
     0 timesTwoPower:1  = 0*1 -> 0
     0 timesTwoPower:2  = 0*4 -> 0
     0 timesTwoPower:-2 = 0/4 -> 0

     2 timesTwoPower:0  = 2*1 -> 2
     2 timesTwoPower:1  = 2*2 -> 4
     2 timesTwoPower:2  = 2*4 -> 8
     2 timesTwoPower:-2 = 2/4 -> (1/2)

     4 timesTwoPower:0  = 4*1 -> 4      = 4 * (2**0) 
     4 timesTwoPower:1  = 4*2 -> 8      = 4 * (2**1) 
     4 timesTwoPower:2  = 4*4 -> 16     = 4 * (2**2) 
     4 timesTwoPower:3  = 4*8 -> 32     = 4 * (2**3) 

     16 timesTwoPower:0  = 16*1 -> 16     = 16 * (2**0) 
     16 timesTwoPower:1  = 16*2 -> 32     = 16 * (2**1) 
     16 timesTwoPower:2  = 16*4 -> 64     = 16 * (2**2)  
     16 timesTwoPower:5  = 16*32 -> 512   = 16 * (2**5)  

     16 timesTwoPower:-1 = 16/2 -> 8      = 16 * (2**-1) 
     16 timesTwoPower:-2 = 16/4 -> 4      = 16 * (2**-2)  
     16 timesTwoPower:-3 = 16/8 -> 2      = 16 * (2**-3)  
     16 timesTwoPower:-4 = 16/16 -> 1     = 16 * (2**-4)  
     16 timesTwoPower:-5 = 16/32 -> 1/2   = 16 * (2**-5)  

     123 timesTwoPower:0  = 123*1 -> 123
     123 timesTwoPower:1  = 123*2 -> 246
     123 timesTwoPower:2  = 123*4 -> 492
     123 timesTwoPower:3  = 123*8 -> 984
     124 timesTwoPower:-1 = 124/2 -> 62
     124 timesTwoPower:-2 = 124/4 -> 31
     124 timesTwoPower:-3 = 124/8 -> 31/2
     124 timesTwoPower:-4 = 124/16 -> (31/4)

     (2 timesTwoPower: -150) timesTwoPower: 150  -> 2
     (2 timesTwoPower: 150) timesTwoPower: -150  -> 2
     (2 timesTwoPower: 150) timesTwoPower: -149  -> 4
     (2 timesTwoPower: 150) timesTwoPower: -151  -> 1
     (2 timesTwoPower: 150) timesTwoPower: -152  -> (1/2)

     (7 timesTwoPower: -150) timesTwoPower: 150  -> 7
     (-7 timesTwoPower: -150) timesTwoPower: 150 -> -7

     Time millisecondsToRun:[
        100000 timesRepeat:[
            (2 timesTwoPower: -150) timesTwoPower: 150      
        ]
     ]

printing & storing

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
     55 asBCD hexPrintString        => '55'  
     999999999 asBCD hexPrintString => '999999999'
     100000000 asBCD
     123456789 asBCD
     99999999 asBCD
     12345678 asBCD
     12345678 asBCD
     12345678 asBCD hexPrintString
     12345678901234567890 asBCD
     5 asBCD hexPrintString         => '5'

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

errorPrintHex

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

hexPrintString

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

Usage example(s):

     9 hexPrintString       '9'
     127 hexPrintString     '7F'
     -1 hexPrintString      '-1'
     -127 hexPrintString    '-7F'

hexPrintString: size

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

Usage example(s):

     12345 hexPrintString:4 => '3039'
     123 hexPrintString:4   => '007B'

printHex

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

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 showRadix:true
        10 printOn:Transcript base:3 showRadix:true
        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) }

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.

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.

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) **

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

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

printStringBase: aBaseInteger size: sz fill: fillCharacter

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

printStringRadix: aBaseInteger size: sz fill: fillCharacter

marked as obsolete by Stefan Vogel at 22-Apr-2024

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

romanPrintString

return a roman number representation of the receiver as a string

Usage example(s):

     1999 romanPrintString.
     Date today year romanPrintString.

private

destructiveAbs

only for protocol completeness with LargeInteger; see there

destructiveNegated

only for protocol completeness with LargeInteger; see there

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.

mightBeACube

a quick (and cheap) reject check if the receiver is possibly a perfect cube.
This only rules out many, but is not a full check for perfect cubeness.
Use only to prefilter large non-cubic integers, where the full check is expensive;
if this methoid returns true, you still have to perform a real check.

Usage example(s):

     2r1010101101010110101010101010101010101010101010101010 mightBeACube => false
     123456789012345678901234567890 mightBeACube                         => false
     123456789012345678901234567890 squared mightBeACube                 => false
     123456789012345678901234567890 cubed mightBeACube                   => true

Usage example(s):

     1 to:1000000 do:[:n |
        |isCube|
        isCube := n cbrt asInteger cubed == n.
        (n mightBeACube) ifFalse:[ self assert:isCube not].
     ]

mightBeASquare

a quick (and cheap) check if the receiver is possibly a perfect square.
Must be called for strictly positive integers only
This only rules out many, but is not a full check for perfect squareness.
Use only to prefilter large non-square integers, where the full check is expensive;
if this methoid returns true, you still have to perform a real check.

Usage example(s):

     2r1010101101010110101010101010101010101010101010101010 mightBeASquare
     123456789012345678901234567890 mightBeASquare
     123456789012345678901234567890 squared mightBeASquare

Usage example(s):

     1 to:1000000 do:[:n |
        |isSquare|
        isSquare := n sqrt asInteger squared == n.
        (n mightBeASquare) ifFalse:[ self assert:isSquare not].
     ]

numberOfDigits: n8BitDigits

initialize the instance to store n8BitDigits

** This method must be redefined in concrete classes (subclassResponsibility) **

numberOfDigits: n8BitDigits sign: newSign

initialize the instance to store n8BitDigits and sign

** This method must be redefined in concrete classes (subclassResponsibility) **

pollardRho

algorithm to find a factor of the receiver.
A helper for prime factors.
see https://en.wikipedia.org/wiki/Pollard%27s_rho_algorithm

Usage example(s):

     13423453625634765 pollardRho   -> 3
        13423453625634765 / 3       -> 4474484541878255
        4474484541878255 * 3        -> 13423453625634765

     13423453625634765 nextPrime    -> 13423453625634799
     13423453625634799 pollardRho   -> endless
     8051 pollardRho                -> 97
        8051 / 97                   -> 83
        97 * 83                     -> 8051

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.

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

digitAt: n

return the n-th byte of the binary representation of the absolute value.
The name 'digit' is a bit misleading: 'digit' here means byte (not decimal digit).

** This method must be redefined in concrete classes (subclassResponsibility) **

digitByteAt: n

return 8 bits of my signed value, starting at byte index.
The name 'digit' is a bit misleading: 'digit' here means byte (not decimal digit).
For positive receivers, this is the same as #digitAt:;
for negative ones, the actual bit representation is returned.

** This method must be redefined in concrete classes (subclassResponsibility) **

digitLength

return the number of bytes needed for the unsigned binary representation of the receiver.
The name 'digit' is a bit misleading: 'digit' here means byte (not decimal digit).
For negative receivers, the result is not defined by the language standard.
ST/X returns the digitLength of its absolute value.
Therefore, do not use this to find out how many bytes are needed
for a negative integer; use #signedDigitLength.
This method is redefined in concrete classes
- the fallback here is actually never used.

exponent

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

Usage example(s):

     16 mantissa * (2 raisedTo:16 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 ).
     self assert:( 1e7 exponent = 10000000 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 ).

isCoprimeWith: anInteger

return true if I am coprime to anInteger.
Coprime means that I have no common divisor with it.

Usage example(s):

     10 isCoprimeWith:11  ->  true
     10 isCoprimeWith:12  ->  false
     123456789012345678901234567890 isCoprimeWith:123456789012345678901234567891 -> true

isInteger

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

isLiteral

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

isPerfectCube

return true if I am a perfect cube.
That is a number for which the cubic root is an integer.

Usage example(s):

     0 isPerfectCube
     1 isPerfectCube
     8 isPerfectCube
     27 isPerfectCube
     -27 isPerfectCube  
     (1 to:1000000) count:[:n | n isPerfectCube]
     12345678987654321234567 isPerfectCube
     123123123432 cubed isPerfectCube
     (123123123432 raisedTo:7) isPerfectCube
     (123123123432 raisedTo:6) isPerfectCube 
     (123123123432 raisedTo:6) negated isPerfectCube 
     (123456789123456789 * 123456789123456789 * 123456789123456789) isPerfectCube
     ((123456789123456789 raisedTo:3)) isPerfectCube 
     ((123456789123456789 raisedTo:7)-1) isPerfectCube
     Time microsecondsToRun:[12345678987654321234567 isPerfectCube]
     12345678987654321234567 cubed isPerfectCube

     Time microsecondsToRun:[12345678987654321234567 cubed isPerfectCube] 
     Time microsecondsToRun:[12345678987654321234567 cubed ]

isPerfectSquare

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

Usage example(s):

     (1 to:100) count:#isPerfectSquare
     (1 to:1000) count:#isPerfectSquare
     (1 to:1024) count:#isPerfectSquare  

     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  
     (123123123432 raisedTo:6) isPerfectSquare  
     ((123456789123456789 raisedTo:7)) isPerfectSquare 
     ((123456789123456789 raisedTo:7)-1) isPerfectSquare  
     Time microsecondsToRun:[12345678987654321234567 isPerfectSquare]
     12345678987654321234567 squared isPerfectSquare    
     Time microsecondsToRun:[12345678987654321234567 squared isPerfectSquare] 
     Time microsecondsToRun:[12345678987654321234567 squared ]                

     2r1010101101010110101010101010101010101010101010101010 isPerfectSquare  
     123456789012345678901234567890 isPerfectSquare            
     123456789012345678901234567890 squared isPerfectSquare    
     100 factorial isPerfectSquare                            
     100 factorial squared isPerfectSquare            
     1000 factorial isPerfectSquare                    
     1000 factorial squared isPerfectSquare           

     [
        |n|
        n := 100 factorial squared.
        1000 timesRepeat:[
            n isPerfectSquare
        ]
     ] benchmark:'perfectSquare'

isPowerOf10

return true, if the receiver is a power of 10.
The receiver must be positive.

isPowerOf2

return true, if the receiver is a power of 2

Usage example(s):

     10000 factorial isPowerOf2       
     ((2 raisedTo:1000)+1) isPowerOf2       
     |n| n := 10000 factorial. Time millisecondsToRun:[10000 timesRepeat:[ n isPowerOf2]]

Usage example(s):

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

isPowerOf: p

return true, if the receiver is a power of p.
The receiver must be positive.
Time complexity is O(self log:p)

Usage example(s):

     0 isPowerOf:2   
     1 isPowerOf:2   

     16r0000000000000000 isPowerOf:2   false
     16r0000004000000000 isPowerOf:2   true
     16r0000004000000001 isPowerOf:2   false

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

     16r0000000000000001 isPowerOf:4  true
     16r0000000000000002 isPowerOf:4  false
     16r0000000000000004 isPowerOf:4  true
     16r0000000000000008 isPowerOf:4  false
     16r0000000000000010 isPowerOf:4  true
     16r0000000000000020 isPowerOf:4  false
     16r0000000000000040 isPowerOf:4  true

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

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

     (3 raisedTo:1000) isPowerOf:3    true
     (3 raisedTo:100000) isPowerOf:3  true

     (1000 factorial) isPowerOf:3      false
     (10000 factorial) isPowerOf:3     false

     [ (100000 factorial) isPowerOf:3 ] benchmark:'isPowerOf:3'    836ms
     [ (100000 factorial) isPowerOf:10 ] benchmark:'isPowerOf:10'    743ms

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):

     13 isPrime
     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

    [ (1 to:1000000) count:[:n | n isPrime]] benchmark:'isPrime' 2200 interpreted     with PrimeNumberGenerator
    [ (1 to:1000000) count:[:n | n isPrime]] benchmark:'isPrime'  396 stc compiled    with PrimeNumberGenerator
    [ (1 to:1000000) count:[:n | n isPrime]] benchmark:'isPrime'  278 r-mul stc compiled

    [ (1 to:1000000) count:[:n | n isPrime]] benchmark:'isPrime' 2250 interpreted     without PrimeNumberGenerator
    [ (1 to:1000000) count:[:n | n isPrime]] benchmark:'isPrime'  398 stc compiled    without PrimeNumberGenerator

    |nr|
    nr := 1000 factorial + 1.
    [ 400 timesRepeat:[ nr isPrime ] ] benchmark:'isPrime' 7350 interpreted     with PrimeNumberGenerator
    [ 400 timesRepeat:[ nr isPrime ] ] benchmark:'isPrime' 7280 stc compiled    with PrimeNumberGenerator

    [ 400 timesRepeat:[ nr isPrime ] ] benchmark:'isPrime'20000 interpreted     without PrimeNumberGenerator
    [ 400 timesRepeat:[ nr isPrime ] ] benchmark:'isPrime'19900 stc compiled    with PrimeNumberGenerator

isSophieGermainPrime

return true if I am a prime Number and 2p+1 is also prime.
This is also called a 'safe prime'.

Usage example(s):

     2 isSophieGermainPrime  -> true
     (1 to:1000000) count:[:n | n isSophieGermainPrime] -> 7746
     (1 to:1000000) count:[:n | n isPrime] -> 78498

mantissa

return what would be the normalized float's mantissa if I was a float.
This is not for general use - it has been added for dolphin (soap) compatibility.
This assumes that a float's mantissa is normalized to
0.5 .. 1.0 and the number's value is: mantissa * 2^exp;
so this mantissa is constructed here synthetically
(will return a fraction, as any other limitedPrecisionReal might not be able to represent it)

Usage example(s):

     16.0 mantissa   -> 0.5
     16 mantissa     -> (1/2)

     20.0 mantissa   0.625
     20 mantissa     (5/8)

     16.0 exponent   -> 5
     16 exponent     -> 5

     16 mantissa * (2 raisedTo:16 exponent)
     16.0 mantissa * (2 raisedTo:16.0 exponent)

     -16 mantissa * (2 raisedTo:-16 exponent)
     -16.0 mantissa * (2 raisedTo:-16.0 exponent)

     0.0 mantissa
     0 mantissa
     0.0 exponent
     0 exponent
     0 mantissa * (2 raisedTo:0 exponent)
     0.0 mantissa * (2 raisedTo:0.0 exponent)

     #( 1.0 1
        2.0 2
        3.0 3
        4.0 4
        12345.0 12345
        0.0 0
        -1.0 -1
        -2.0 -2
        -3.0 -3
        -4.0 -4
        -12345.0 -12345
     ) pairWiseDo:[:f :i |
        self assert:( f exponent = i exponent ).
        self assert:( f mantissa = i mantissa ).
        self assert:( f mantissa * (2 raisedTo:f exponent))= f.
        self assert:( i mantissa * (2 raisedTo:i exponent)) = i.
     ].

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)
Should probably be renamed to roundUpToMultipleOf:n
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

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.
Should propably be renamed to roundUpToPowerOf2

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
         ]
     ]

nextPrime

return the next prime after the receiver

Usage example(s):

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

Usage example(s):

        TimeDuration toRun:[
            1000000 timesRepeat:[
                5000 nextPrime.
            ]
        ].

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).
     ]

ulp

answer the distance between me and the next representable number;
I am not sure if this makes a good fallback default

special modulo arithmetic

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.
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.
add_64: anInteger: return a C-semantic 64bit signed sum of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns an signed 64bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics on 64 bit machines.
add_64u: anInteger: return a C-semantic 64bit unsigned sum of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns a unsigned 64bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics on 64 bit machines.
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.
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.
mul_64: anInteger: return a C-semantic 64bit product of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns a signed 64bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics.
mul_64u: anInteger: return a C-semantic 64bit unsigned product of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns an unsigned 64bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics.
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.
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.
sub_64: anInteger: return a C-semantic 64bit signed difference of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns an signed 64bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics on 64 bit machines.
sub_64u: anInteger: return a C-semantic 64bit signed difference of the receiver and the argument.
Both must be either Small- or LargeIntegers.
Returns a signed 64bit number.
This (nonstandard) specialized method is provided to allow simulation of
modulu operations with C semantics on 64 bit machines.

special modulo bit operators

asSigned32

return a 32-bit integer with my bit-pattern.
For protocol completeness.

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

testing

isExact: Answer whether the receiver performs exact arithmetic.

tracing

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

truncation & rounding

ceiling

return the smallest integer which is larger or equal to the receiver.
For integers, this is the receiver itself.

ceilingAsFloat

for protocol compatibility with floats

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.

floor

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

floorAsFloat

for protocol compatibility with floats

fractionPart

return a number with value from digits after the decimal point.
such that:
(self truncated + self fractionPart) = self
Since integers have no fraction, return 0 here.

Usage example(s):

     1234.56789 fractionPart
     1.2345e6 fractionPart
     1000 fractionPart
     10000000000000000 fractionPart

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

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) **

rounded

for protocol compatibility with floats;
return the receiver rounded toward the next Integer -
for integers this is the receiver itself.

roundedAsFloat

for protocol compatibility with floats;
returns the receiver as a float

truncated

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

truncatedAsFloat

for protocol compatibility with floats

visiting

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

Private classes:

    ModuloNumber

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 02:32:37 GMT