Class: SmallInteger

• Inheritance
• Description
• Related information
• Class protocol
  • bit mask constants
  • constants
  • instance creation
  • queries
• Instance protocol
  • arithmetic
  • binary storage
  • bit operators
  • bit operators-32bit
  • byte access
  • catching messages
  • coercing & converting
  • comparing
  • copying
  • iteration
  • misc math
  • modulo arithmetic
  • printing & storing
  • private
  • testing

Inheritance:

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

Package:

stx:libbasic

Category:

Magnitude-Numbers

Version:

rev: 1.185 date: 2010/04/13 18:58:23

user: cg

file: SmallInteger.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

SmallIntegers are Integers in the range of at least +/- 2^30
(i.e. 31 bits, which is not a guaranteed: on an alpha, 63 bits are used,
 if the system was configured for 64bit mode).

These are no real objects - they have no instances (not even storage !)
and cannot be subclassed.
The reason is to save both storage and runtime by not collecting
SmallIntegers in the system. SmallInts are marked by having the TAG_INT
bit set, in contrast to all other objects which do not.
Since this knowledge is hardwired into the system (and there is no
class-field stored with SmallIntegers) there can be no subclass of
SmallInteger (sorry).

If you really need this kind of thing, create a subclass of Integer,
with an instance variable holding the value.

Related information:

    Number
    Float
    Fraction
    FixedPoint
    LargeInteger

Class protocol:

 bitMaskFor: index

return a bitmask for the index's bit (index starts at 1)

 maxBits

return the number of bits in instances of me.
For very special uses only - not constant across implementations

 maxBytes

return the number of bytes in instances of me.
For very special uses only - not constant across implementations

 maxVal

return the largest Integer representable as SmallInteger.
For very special uses only - not constant across implementations

 minVal

return the smallest Integer representable as SmallInteger.
For very special uses only - not constant across implementations

 basicNew

catch instance creation
- SmallIntegers cannot be created with new

 basicNew: size

catch instance creation
- SmallIntegers cannot be created with new

 canBeSubclassed

return true, if its allowed to create subclasses of the receiver.
Return false here - since it is NOT possible for SmallInteger
(due to the tagged representation of SmallIntegers)

 hasImmediateInstances

return true if this class has immediate instances
i.e. if the instances are represented in the pointer itself and
no real object header/storage is used for the object.
Redefined from Behavior

 isBuiltInClass

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

Instance protocol:

 * aNumber

return the product of the receiver and the argument

 + aNumber

return the sum of the receivers value and the arguments value

 - aNumber

return the difference of the receivers value and the arguments value

 / aNumber

return the quotient of the receivers value and the arguments value

 // aNumber

return the integer part of the quotient of the receivers value
and the arguments value. The result is truncated toward negative infinity
and negative, if the operands signs differ.
Be careful with negative results: 9 // 4 = 2,
while -9 // 4 = -3.
The following is always true:
(receiver // aNumber) * aNumber + (receiver \\ aNUmber) = receiver
See #quo: which returns -2 in the latter.

 \\ aNumber

Answer the integer remainder m defined by division with truncation toward
negative infinity. The remainder has the same sign as aNumber.
m < |aNumber| AND there is an integer k with (k * aNumber + m) = self
The following is always true:
(receiver // aNumber) * aNumber + (receiver \\ aNumber) = receiver
Compare with #rem:

Redefined for speed.

 abs

return the absolute value of the receiver
reimplemented here for speed

 negated

return the negative value of the receiver
reimplemented here for speed

 quo: aNumber

return the integer part of the quotient of the receivers value
and the arguments value. The result is truncated towards zero
and negative, if the operands signs differ..
The following is always true:
(receiver quo: aNumber) * aNumber + (receiver rem: aNumber) = receiver
For positive results, this is the same as #//,
for negative results, the remainder is ignored.
I.e.: '9 // 4 = 2' and '-9 // 4 = -3'
in contrast: '9 quo: 4 = 2' and '-9 quo: 4 = -2'

 identityHashForBinaryStore

 bitAnd: anInteger

return the bitwise-and of the receiver and the argument, anInteger

 bitAt: anIntegerIndex

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)

 bitClear: anInteger

return the bitwise-and of the receiver and the complement of the argument, anInteger,
returning the receiver with bits of the argument cleared.

 bitCount

return the number of 1-bits in the receiver

 bitInvert

return the value of the receiver with all bits inverted

 bitOr: anInteger

return the bitwise-or of the receiver and the argument, anInteger

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

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.

 bitXor: anInteger

return the bitwise-exclusive-or of the receiver and the argument, anInteger

 clearBit: anInteger

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

 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.

 invertBit: anInteger

return a new number where the specified bit is inverted.
Bits are counted from 1 starting with the least significant.
The methods name may be missleading: the receiver is not changed,
but a new number is returned. Should be named #withBitInverted:

 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.

 rightShift: shiftCount

return the value of the receiver shifted by shiftCount bits;
right shift if shiftCount > 0; left shift 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.

 setBit: anInteger

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

 asSigned32

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

 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.

 bitInvert32

return the value of the receiver with all bits inverted in 32bit signed int space
(changes the sign)

 bitRotate32: shiftCount

return the value of the receiver rotated by shiftCount bits,
but only within 32 bits, rotating left for positive, right for negative counts.
Rotates through the sign bit.
Useful for crypt algorithms, or to emulate C/Java semantics.

 bitShift32: shiftCount

return the value of the receiver shifted by shiftCount bits,
but only within 32 bits, shifting into/out-of the sign bit.
May be useful for communication interfaces, to create ST-numbers
from a signed 32bit int value given as individual bytes,
or to emulate C/Java semantics.

 bitXor32: aNumber

return the xor of the receiver and the argument.
The argument must be another SmallInteger or a 4-byte LargeInteger.
If the result overflows the 32 bit range, the value modulo 16rFFFFFFFF is returned.
This is of course not always correct, but allows for C/Java behavior to be emulated.

 unsignedBitShift32: shiftCount

return the value of the receiver shifted by shiftCount bits,
but only within 32 unsigned bits.
May be useful for communication interfaces, to create ST-numbers
from an unsigned 32bit int value given as individual byte,
or to emulate C/Java semantics.

 digitAt: index

return 8 bits of value, starting at byte index

 digitByteAt: index

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

 digitBytes

return a byteArray filled with the receivers bits
(8 bits of the absolute value per element),
least significant byte is first

 digitBytesMSB: msbFlag

return a byteArray filled with the receivers bits
(8 bits of the absolute value per element),
if msbflag = true, most significant byte is first,
otherwise least significant byte is first

 digitLength

return the number bytes required to represent this Integer.
For negative receivers, the digitLength of its absolute value
is returned.

 basicAt: index

catch indexed access - report an error
defined here since basicAt: in Object ommits the SmallInteger check.

 basicAt: index put: anObject

catch indexed access - report an error
defined here since basicAt:put: in Object ommits the SmallInteger check.

 basicSize

return the number of indexed instvars - SmallIntegers have none.
Defined here since basicSize in Object ommits the SmallInteger check.

 size

return the number of indexed instvars - SmallIntegers have none.

 asCharacter

Return a character with the receiver as ascii value

 asFloat

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

 asLargeInteger

return a LargeInteger with same value as receiver

 asShortFloat

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

 codePoint

for compatibility with Characters.
(Allows for integers to be stored into U16/U32 strings)

 coerce: aNumber

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

 generality

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

 signExtended24BitValue

return a smallInteger from sign-extending the 24'th bit.
May be useful for communication interfaces

 signExtendedByteValue

return a smallInteger from sign-extending the 8'th bit.
May be useful for communication interfaces

 signExtendedShortValue

return a smallInteger from sign-extending the 16'th bit.
May be useful for communication interfaces

 < aNumber

return true, if the argument is greater than the receiver

 <= aNumber

return true, if the argument is greater or equal

 = aNumber

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

 > aNumber

return true, if the argument is less than the receiver

 >= aNumber

return true, if the argument is less or equal

 hash

return an integer useful for hashing on value

 identityHash

return an integer useful for hashing on identity

 max: aNumber

return the receiver or the argument, whichever is greater

 min: aNumber

return the receiver or the argument, whichever is smaller

 ~= aNumber

return true, if the arguments value is not equal to mine

 deepCopy

return a deep copy of myself
- reimplemented here since smallintegers are unique

 deepCopyUsing: aDictionary postCopySelector: postCopySelector

return a deep copy of myself
- reimplemented here since smallintegers are unique

 shallowCopy

return a shallow copy of myself
- reimplemented here since smallintegers are unique

 simpleDeepCopy

return a deep copy of myself
- reimplemented here since smallintegers are unique

 timesRepeat: aBlock

evaluate the argument, aBlock self times.
Reimplemented as primitive for speed

 to: stop by: incr do: aBlock

reimplemented as primitive for speed

 to: stop do: aBlock

evaluate aBlock for every integer between (and including) the receiver
and the argument, stop.
Reimplemented as primitive for speed

 bernoulli

returns the nth Bernoulli number.
The series runs this:
1/6, 1/30, 1/42, 1/30, 5/66, 691/2730, etc
Uses a table of the first 20 bernoulli numbers.
So bernoulli(42) will fail for now.
Used with taylor series for tan

 divMod: aNumber

return an array filled with self // aNumber and
self \\ aNumber.
The result is only defined for positive receiver and
argument.

 gcd: anInteger

return the greatest common divisor (Euclid's algorithm).
This has been redefined here for more speed since due to the
use of gcd in Fraction code, it has become time-critical for
some code. (thanx to MessageTally)

 gcd_helper: anInteger

same as gcd - see knuth & Integer>>gcd:

 intlog10

return the truncation of log10 of the receiver -
stupid implementation; used to find out the number of digits needed
to print a number/and for conversion to a LargeInteger.
Implemented that way, to allow for tiny systems (PDAs) without a Float class
(i.e. without log).

 plus32: aNumber

return the sum of the receiver and the argument, as SmallInteger.
The argument must be another SmallInteger.
If the result overflows the 32 bit range, the value modulo 16rFFFFFFFF is returned.
This is of course not always correct, but allows for C/Java behavior to be emulated.

 plus: aNumber

return the sum of the receiver and the argument, as SmallInteger.
The argument must be another SmallInteger.
If the result overflows the smallInteger range, the value modulo the
smallInteger range is returned (i.e. the low bits of the sum).
This is of course not always correct, but some code does a modulo anyway
and can therefore speed things up by not going through LargeIntegers.

 subtract: aNumber

return the difference of the receiver and the argument, as SmallInteger.
The argument must be another SmallInteger.
If the result overflows the smallInteger range, the value modulo the
smallInteger range is returned (i.e. the low bits of the sum).
This is of course not always correct, but some code does a modulo anyway
and can therefore speed things up by not going through LargeIntegers.

 times: aNumber

return the product of the receiver and the argument, as SmallInteger.
The argument must be another SmallInteger.
If the result overflows the smallInteger range, the value modulo the
smallInteger range is returned (i.e. the low bits of the product).
This is of course not always correct, but some code does a modulo anyway
and can therefore speed things up by not going through LargeIntegers.

 printOn: aStream

append my printstring (base 10) to aStream.

 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.

 printString

return my printstring (base 10)

 printStringRadix: base

return my printstring (optimized for bases 16, 10 and 8)

 printfPrintString: formatString

non-standard, but sometimes useful.
return a printed representation of the receiver
as specified by formatString, which is defined by the C-
function 'printf'.
No checking for string overrun - the resulting string
must be shorter than 256 chars or else ...
This method is NONSTANDARD and may be removed without notice;
it is provided to allow special conversions in very special
situaltions.
Notice that a conversion may not be portable; for example,
to correctly convert an int on a 64-bit alpha, a %ld is required,
while other systems may be happy with a %d ...
Use at your own risk (if at all).
WARNNG: this goes directly to the C-printf function and may therefore me inherently unsafe.
Please use the printf: method, which is safe as it is completely implemented in Smalltalk.

 sign: aNumber

private: for protocol completeness with LargeIntegers

 between: min and: max

return true if the receiver is less than or equal to the argument max
and greater than or equal to the argument min.
- reimplemented here for speed

 even

return true, if the receiver is even

 negative

return true, if the receiver is less than zero
reimplemented here for speed

 odd

return true, if the receiver is odd

 positive

return true, if the receiver is not negative
reimplemented here for speed

 sign

return the sign of the receiver (-1, 0 or 1).
reimplemented here for speed

 strictlyPositive

return true, if the receiver is greater than zero
reimplemented here for speed