Computer Algebra Kit (c) 1992,00 by Comp.Alg.Objects.  All Rights Reserved.

BigInt

Inherits from: CAObject

Maturity Index: Relatively mature

Class Description

An integer (alias BigInt) is an array of digits, each digit is a value of type DIGIT declared as unsigned short int.  So, abstractly, the integer is expressed base USHRT_MAX + 1, which is a power of two. (USHRT_MAX is defined in the ANSI header file limits.h)  The most significant (or leading) digit is never zero; the last digit is the least significant digit of the integer.  There are methods to count, access, insert or remove digits.  Besides the normal elementary arithmetical operations, Integer also supports multiplication, division etc. by digits.  For input and output, integers are in decimal representation.

Method types

Creation	- new
	- str:
	- int:
	- factorial:
	- fibonacci:
	- copy
	- deepCopy
	- release

Identity	- hash
	- isEqual:
	- numDigits
	- isDigit

Inserting and Removing Digits	- insertDigit:
	- removeDigit

Accessing Digits	- digitAt:
	- lastDigit
	- leadingDigit

String Value	- str
	- str:

Coercion	- asNumerical
	- asModp:
	- digitValue
	- digitValue:
	- ulongValue
	- ulongValue:
	- intValue
	- intValue:
	- doubleValue
	- floatValue

Comparing	- sign
	- compare:

Addition	- zero
	- isZero
	- isOpposite:
	- negate
	- double
	- add:
	- subtract:
	- addDigit:
	- subtractDigit:

Multiplication	- one
	- minusOne
	- isOne
	- isMinusOne
	- square
	- multiply:
	- multiplyDigit:
	- inverse

Division	- divide:
	- divideDigit:
	- quotientDigit:
	- remainder:quotient:
	- quotientDigit:remainder:
	- remainderDigit:

Parity	- isEven
	- isOdd

Greatest Common Divisor	- gcd:

Printing	- printsLeadingSign
	- printOn:

Methods

new
+new

Returns a new integer equal to zero.  The instance method zero returns a shared, zero integer object. 

See also: - zero

str:
+str:(STR)aString

Returns a new integer from the decimal representation aString, or returns nil if aString doesn't contain decimal characters (with optional unary minus sign).

int:
+int:(int)intValue

Returns a new integer with value equal to intValue.

factorial:
+factorial:(int)n

Returns a new integer object that is the n-th factorial.

fibonacci:
+fibonacci:(int)n

Returns a new object that is the n-th Fibonacci number. (Not implemented).

copy
-copy

Makes a copy of the digits.

deepCopy
-deepCopy

For integer objects, deepCopy is equivalent to copy.

release
-release

Frees the array of digits of the integer object.

hash
- (unsigned)hash

Returns a small integer that is the same for objects that are equal (in the sense of isEqual:).

isEqual:
- (BOOL)isEqual:b

numDigits
- (int)numDigits

Returns the number of DIGIT's in the integer.  Returns zero if the integer is zero.  The leading digit of an integer is at position numDigits minus one.

isDigit
- (BOOL)isDigit

Whether the integer consists of a single digit.  If the integer is zero, this method returns NO.  The method ignores the sign of the integer.

See also: digitValue

insertDigit:
-insertDigit:(DIGIT)d

Inserts d as last digit, shifting the other digits one position up.  The method doesn't insert anything if both the integer and d are equal to zero. 

removeDigit
- (DIGIT)removeDigit

Removes and returns the last digit, shifting the other digits one position down.  The method returns zero if the integer is equal to zero. 

digitAt:
- (DIGIT)digitAt:(int)i

Returns the digit at position i.  The leading digit is position numDigits minus one.  The last digit is at position zero.  Returns 0 if the index is less than zero or equal to or greater than numDigits.

lastDigit
- (DIGIT)lastDigit

Returns the least significant digit of the integer, the digit at position 0.  Returns 0 if the integer is zero.

leadingDigit
- (DIGIT)leadingDigit

Returns the most significant digit of the integer, the digit at position numDigits minus one.  The leading digit of a nonzero integer is never zero.  The method returns 0 if the integer is zero.

str
- (STR)str

Returns the decimal representation of the integer as a NULL-terminated string of characters.  The string is automatically disposed off when freeing the integer, or when modifying the integer with methods that work destructively on the integer such as removeDigit or insertDigit:.

str:
-str:(STR)aString

Returns a new integer from the decimal representation aString, or returns nil if aString doesn't contain decimal characters (with optional unary minus sign).

asNumerical
-asNumerical

Returns a new instance of the Float class whose float value is equal to that of the integer.

See also: floatValue

asModp:
-asModp:(unsigned short)p

Returns a new instance of the IntegerModp class whose value is equal to that of the integer modulo p (with p a small prime number).  Negative integers are mapped to the opposite (mod p) of their absolute value.

See also: IntegerModp

digitValue
- (DIGIT)digitValue

Equivalent to lastDigit.  This method ignores the sign of the integer i.e., for a negative integer that consists of just one digit, it returns the absolute value of the integer.

digitValue:
-digitValue:(DIGIT)aValue

Returns a new (positive) integer object, with value equal to aValue.

ulongValue
- (unsigned long)ulongValue

Returns the two last digits of the integer as an unsigned long value.

ulongValue:
-ulongValue:(unsigned long)aValue

Returns a (positive) integer with value as unsigned long equal to aValue.

intValue
- (int)intValue

Returns the value of the integer as int value, if possible.  If the integer is too large to represented as int, the method returns INT_MIN or INT_MAX depending on the sign of the integer.

intValue:
-intValue:(int)aValue

Returns a new integer with value equal to aValue.

doubleValue
- (double)doubleValue

Returns the integer as a floating-point double value, if possible.  If the integer is too big to be represented as double, the method returns DBL_MIN or DBL_MAX depending on the sign of the integer.

floatValue
- (float)floatValue

Returns the integer as a floating-point float value, if possible.  If the integer is too big to be represented as float, the method returns FLT_MIN or FLT_MAX depending on the sign of the integer.

sign
- (int)sign

Returns plus one if the object is positive (greater than zero), zero if zero and minus one if negative (less than zero).

compare:
- (int)compare:b

Returns -1, 0, or +1 if the object is respectively less than, equal to, or greater than b.  Returns 0 for pointer equal objects.

zero
-zero

Returns a copy of a shared integer instance with value equal to zero.

isZero
- (BOOL)isZero

Whether the object is equal to zero.

isOpposite:
- (BOOL)isOpposite:b

Whether the object is the opposite of b.

negate
-negate

Returns the opposite of the object.

double
-double

Returns a new object, equal to the object multiplied by two i.e., added to itself.

add:
-add:b

Adds b to the object.  Returns a new object.

subtract:
-subtract:b

Subtracts b from the object.  Returns a new object.

addDigit:
-addDigit:(DIGIT)d

Returns a new integer that is the sum of the integer self and the digit d.

subtractDigit:
-subtractDigit:(DIGIT)d

Returns a new integer that is the equal to the integer self minus the digit d.

one
-one

Returns a copy of a shared integer instance with value equal to one.

minusOne
-minusOne

Returns a copy of the integer minus one.

isOne
- (BOOL)isOne

Whether the object is equal to one.

isMinusOne
- (BOOL)isMinusOne

Whether the object is equal to minus one.

square
-square

Returns the square of the object i.e., a new object equal to the original object multiplied by itself.

multiply:
-multiply:b

Returns a new object, the product of the object multiplied (to the right) by b.  If the objects are pointer equal, this method is equivalent to square.

multiplyDigit:
-multiplyDigit:(DIGIT)d

Returns the product of the integer and the digit d (the product is a new object).

inverse
-inverse

Returns nil, except if the integer is one or minus one, in which case the method returns a copy of the object itself.

divide:
-divide:b

Returns the exact quotient on division by b.  Returns nil if the divisor b is zero or if the division is not exact (when the remainder is not zero).

See also: quotient:

divideDigit:
-divideDigit:(DIGIT)b

Returns the exact quotient on division by the digit b.  Returns nil if the divisor b is zero or if the division is not exact (when the remainder is not zero).

quotientDigit:
-quotientDigit:(DIGIT)b

Returns the quotient on division by the digit b; the division need not necessarily be exact.  Returns nil if b is equal to zero.

remainder:quotient:
-remainder:bquotient:(id *)q

Returns the remainder and, if a non-NULL pointer is passed for q, the quotient on division of the dividend self by a divisor b.  Both remainder and quotient are new integer objects.  The remainder is signed i.e., its sign is the same as the sign of the dividend; the relation dividend == quotient divisor + remainder holds for all integers.

quotientDigit:remainder:
-quotientDigit:(DIGIT)dremainder:(DIGIT *)r

Returns the quotient and, if a non-NULL pointer is passed along for r, the unsigned remainder on division by a digit d; the relation dividend == quotient divisor + remainder does not hold if the dividend is negative.

remainderDigit:
- (DIGIT)remainderDigit:(DIGIT)d

Returns the unsigned remainder on division by a digit d i.e., the sign of the object is ignored.  The divisor d shouldn't be equal to zero.

isEven
- (BOOL)isEven

Whether the integer is even i.e., zero or divisible by two.

isOdd
- (BOOL)isOdd

Whether the integer is odd i.e., not divisible by two.

gcd:
-gcd:b

Returns a new (non-negative) integer, the greatest common divisor of the two integers, computed by the Euclidean algorithm. 

printsLeadingSign
- (BOOL)printsLeadingSign

Returns YES if the integer is negative.

printOn:
-printOn:(IOD)aFile

Prints the integer in decimal representation to aFile.