Maturity Index:Relatively mature
Arithmetical operations such as multiply: or add: are defined only on instances of the same class, or more precisely on objects for which sameClass: returns YES. The algebraic properties of a set (class) of objects is tested by sending messages to an element of the set (for example inOrderedSet), and control the algorithms being used. Nullary operators, like obtaining the unity element of a set, are made unary : the unity element of a set is obtained by sending one to an arbitrary element of the set.
For example, for two Integer objects, sameClass: simply returns YES, but for two IntegerModp objects, sameClass: returns YES if and only if the moduli are equal. This means that you can sum, using add:, any pair of Integer instances, but that you cannot add an object mod p to an object mod q. Also, you cannot add a Integer instance to a IntegerModp instance using the add: method.
In many cases, a loop needs to repeatedly update some value. And because the Computer Algebra Kit enforces explicit deallocation of objects, you should use a temporary variable to this purpose :
while (n--) {
id tmp;
tmp = [power square];
power = [power free];
power = tmp;
}
The following example shows how to destructively invert anObject : when anObject is successfully inverted, anObject is replaced by the return value of the method. Otherwise, when an exception occurs, the method returns nil and anObject is guaranteed not to be modified. The object can be inspected by the 'exception handler' - and needs to be freed if the handler wants to recover from the exception.
inverse = [anObject inverse];
if (inverse) {
anObject = [anObject free];anObject = inverse;
} else {
fprintf(stderr,"%s has no inverse\n",[anObject str]);
anObject = [anObject free];
}
Note: In the future, the Computer Algebra Kit will support an exception handling scheme in the spirit of the Cox's TaskMaster document, using Objective-C Blocks.
+ (STR) cakitRevisionThis method returns the value of the revision string __cakit_revision__ (declared in the header file cakit/cakit.h), as it was when the Computer Algebra Kit was built. The string in the header file that you're using should match the string returned by this method.
Subclasses must implement their own versions of copy to copy additional memory consumed by the copied object.
See also: cheapCopy, deepCopy
Subclasses must implement their own versions of deepCopy to make a full independent copy of the object.
The reference count controls the behavior of the free method : by default, an object is created with a reference count equal to one. When a free message is sent to such an object, it will effectively free the memory consumed by the object, and make it available to other objects. However, after increasing the reference count by sending cheapCopy to the object, the next invocation of free will not yet really-free, but rather decrement the reference count. Freeing is delayed until the reference count is equal to one.
Note: This method was originally called addReference, because that's how it is implemented. addReference is retained for backward compatibility.
See also: copy, deepCopy
Subclasses must implement their own versions of clear, rather than free.
Returns nil if the object was successfully destroyed or if the reference count was successfully decremented.
Note: Subclasses should never need to override free. Override clear instead.
You don't have to free the string (it is deallocated when you free or change the object), which makes it easy to use the method as follows :
Note: Symbol itself does not implement this method.
If the object is an element of an additive monoid, the method should test whether the object is the unique zero element. Otherwise, isZero should return YES if the object is the zero element for itself. Matrices of variable dimension, for example, have zero elements of different dimension.
If the object is an element of an additive monoid, the zero element is unique. Otherwise, zero should return an element c such that self + c = 0. Matrices of variable dimension, for example, have zero elements of different dimension.
There is no default implementation for this method.
See also: zero, double, quadruple
There is no default implementation for this method.
If the object is an element of a multiplicative monoid the unity element is unique. Otherwise, one returns the (right) multiplicative unity element for the object itself, ie. an element c such that self c = 1. Matrices of variable dimension, for example, have unity elements of different dimension.
There is no default implementation for this method.
If the object is an element of an multiplicative monoid, the method should test whether the object is the unique unity element. Otherwise, isOne should return YES if the object is the (right) multiplicative unity element for itself. Matrices of variable dimension, for example, have unity elements of different dimension.
Note that when multiplication is not commutative, [a multiply:b] is not the same thing as [b multiply:a]. Non-commutative multiplication is currently hardly supported. In general, we have used throughout the Computer Algebra Kit right multiplication. Left multiplication will be explicitely indicated.
If n is zero, the method invokes one, except if the object itself is zero. In that case the method returns nil. If n is negative, the method raises the inverse of the object to the -n-th power, or if the object is not invertible, it returns nil.
The default implementation of this method consists of the binary exponentation algorithm (invoking square). The method may be overridden in those cases where the binary exponentation algorithm performs worse than, for example, a repeated multiplication strategy (for sufficiently sparse polynomials e.g.).
Note: Use quotient: to determine the quotient of a division with remainder.
See also: divide, quotient, remainder
Note: For ordered domains (such as the integers), this method should return a signed remainder, while modulo: returns an unsigned remainder.
See also: modulo
See also: divide
There is no default implementation for this method.
The default implementation invokes remainder:. Adds back m, if self is ordered and the remainder is negative.
If self and n are equal to zero, returns nil.
There is no default implementation.
See also: zero
There is no default implementation of this method.
new
+ new
Creates an object and sets the reference count of the new object to one.
str:
+ str :(STR) aString
Creates an object given a string description. No default implementation.
int:
+ int :(int) intValue
Creates an object given an int value. No default.
copy
- copy
Creates a copy of the object by sending copy to super. Sets the reference count of the new object to one.
Note that the message to super precedes the code added in the method. This ensures that copying proceeds in the order of inheritance.
- copy
{
self = [super copy];
companionObject = [companionObject cheapCopy];
return self;
}
deepCopy
- deepCopy
Creates a deep copy of the object by sending copy to super. Sets the reference count of the new object to one.
See also: copy, cheapCopy
- deepCopy
{
self = [super deepCopy];
companionObject = [companionObject deepCopy];
return self;
}
cheapCopy
- cheapCopy
Increments the reference count of the object and returns self.
clear
- clear
Invoked by free to clear supporting memory of the object - without destroying the object itself. The default implementation simply returns self.
An implementation of clear frees instance variables. It does not send clear messages other than the one to super.
- clear
{
companionObject = [companionObject free];
return [super clear];
}
free
- free
If the reference count of the object is equal to one, free first sends a clear message and then destroys the memory occupied by the object itself. If the reference count is not equal to one, free doesn't free anything, but subtracts instead a reference from the count.
sameClass:
- (BOOL) sameClass : a
Whether the objects belong to the same class; the default implementation checks whether the isa pointers of the objects are the same. Some classes override sameClass: to impose extra requirements; for example, for integers mod p :
return [super sameClass:a] && [self modulus] == [a modulus];
differentClass:
- (BOOL) differentClass : a
Whether sameClass: returns NO. Don't override this method. Implement your own version of sameClass: instead (incorporating a call to super's implementation of sameClass:).
isKindOfSequence
- (BOOL) isKindOfSequence
Equivalent to :
[self isKindOf:(id)[CASequence class]]
str
- (STR) str
Returns a string containing a symbolic representation for the object. Suited for small expressions only since output is unbuffered. Works by allocating a small buffer and then invoking printOn: on that buffer to do the actual printing.
fprintf(stderr,"Value of this %s is %s\n",[anObject name],[anObject str]);
str:
- str :(STR) aString
Returns a new object, instance of the same class, created from aString or returns nil if it's not possible to evaluate aString in the set. Note that it's not necessarily true that the string value of the new object is literally equal to aString. There is no default implementation for this method.
intValue
- (int) intValue
Returns, if it makes sense, the value of the object as C integer. There is no default implementation for this method.
intValue:
- intValue :(int) i
Returns a new object of the same class with intValue equal to i or returns nil.
asModp:
- asModp :(unsigned short) p
Returns an object that is the value modulo the small prime number p for the object that receives the message. For example, an integer object returns a IntegerModp object in response to this method; a matrix returns a matrix with modular values and so on.
isFloatingPoint
- (BOOL) isFloatingPoint
Returns YES if the object is some kind of floating-point arithmetic. The default implementation returns NO. No attempt has been made to integrate floating-point arithmetic into the Computer Algebra Kit's framework of algebraic structures; floating-point numbers are always treated as a special case.
asNumerical
- asNumerical
Returns an object that is the numerical value for the object that receives the message. For example, an integer object returns a floating-point object as numerical value; a matrix returns a matrix with numerical values and so on.
floatValue
- (float) floatValue
Returns, if it makes sense, the value of the object as C floating-point number. There is no default implementation for this method.
floatValue:
- floatValue :(float) f
Returns a new object of the same class with floatValue equal to f or returns nil.
asTotalFraction
- asTotalFraction
Returns a new fraction with the numerator set to a new reference to the original object, and with the denominator set to one. For example, an integer object returns a rational number.
asScalar
- asScalar
Returns a new scalar object or nil if the object cannot be coerced into a scalar object; there is no default implementation of the method. Polynomial overrides this method to return a scalar object if the polynomial contains just a single scalar and no symbols, or nil otherwise.
asSymbol
- asSymbol
Returns a new symbol object or nil if the object cannot be coerced into a symbol object; there is no default implementation provided. Polynomial overrides this method to return a symbol object if the polynomial consists of a single symbol raised to the exponent one, or nil otherwise.
isEqual:
- (BOOL) isEqual : a
Should test whether the objects are equal. Returns, by default, YES if the two objects are the same (ie. pointer equal)
notEqual:
- (BOOL) notEqual : a
Whether isEqual: returns NO.
inOrderedSet
- (BOOL) inOrderedSet
Whether the object is an element of a (totally) ordered set. Elements can be compared with compare: if this method returns YES. There is no default implementation for this method.
compare:
- (int) compare : b
This method should return -1, 0, or +1 if self is less than, equal to, or greater than b. There is no default implementation for this method.
sign
- (int) sign
Returns the sign of the object : plus one if positive (greater than zero), zero if zero and minus one if negative (less than zero). There is no default implementation for this method.
isLess:
- (BOOL) isLess : a
Tests whether the object is less than (but not equal to) a. Defined, by default, in terms of compare:.
isGreater:
- (BOOL) isGreater : a
Tests whether the object is greater than (but not equal to) a. Defined, by default, in terms of compare:.
isLessEqual:
- (BOOL) isLessEqual : a
Tests whether the object is less than or equal to a. Defined, by default, in terms of compare:.
isGreaterEqual:
- (BOOL) isGreaterEqual : a
Tests whether the object is greater than or equal to a. Defined, by default, in terms of compare:.
absValue
- absValue
Returns the absolute value of the object (a new object). If the object is negative, invokes negate. Otherwise returns a cheap copy of self.
inAdditiveSemiGroup
- (BOOL) inAdditiveSemiGroup
Should return YES if the object is an element of an additive semigroup ie., a set equiped with a (commutative) additive operation, but not necessarily with a unique zero element. Objects that return YES should be prepared to receive negate, add:, subtract:, zero and isZero messages, but a zero element for some object a is not necessarily the zero object for another object b of the same class. For example, the vectors (of variable dimension) have zero elements of different dimension. There is no default implementation for this method.
inAdditiveMonoid
- (BOOL) inAdditiveMonoid
Should return YES if the object is an element of an additive monoid ie., an additive semigroup with a unique zero element : if an object returns YES to this method, and if isZero returns YES, then it is the zero object for all objects of the same class. However, not every element in the set necessarily has an additive inverse : for example, the set of positive integers contains elements with no additive inverse. There is no default implementation for this method.
inAdditiveGroup
- (BOOL) inAdditiveGroup
Should return YES if the object is an element of an additive group ie., an additive monoid with an additive inverse for each element. There is no default implementation for this method.
isZero
- (BOOL) isZero
Returns YES if the object is equal to zero. There is no default implementation for this method.
notZero
- (BOOL) notZero
Whether isZero returns NO.
isOpposite:
- (BOOL) isOpposite : b
Should return YES if the objects are additive inverses. Zero is the only object that is its own additive inverse, unless the characteristic is equal to two.
notOpposite:
- (BOOL) notOpposite : b
Whether isOpposite returns NO.
zero
- zero
Returns a new reference to the zero element.
negate
- negate
Returns the opposite of the object (a new object). There is no default implementation.
add:
- add : b
Returns the sum self + b. If the object is pointer equal to the argument, this method should be equivalent to double. Adding zero returns a new object that is equal to the non-zero object.
subtract:
- subtract : b
Returns a new object, equal to self - b. If the object is pointer equal to the argument, this method is equivalent to zero.
increment
- increment
Adds one to the object. Returns a new object.
decrement
- decrement
Subtracts one from the object. Returns a new object.
multiplyIntValue:
- multiplyIntValue :(int) b
Returns a new object equal to the product self b. The default implementation creates an object through -intValue: and then invokes multiply:.
double
- double
Multiplies the object by two. Returns a new object. There is no default implementation for this method.
quadruple
- quadruple
Multiplies the object by four. Returns a new object.
divideIntValue:
- divideIntValue :(int) b
Returns a new object, the exact quotient of the object on division by b. Returns nil if the division is not exact or if b is equal to zero.
half
- half
Divides the object by two. Returns a new object, or nil if the object is not a multiple of two.
quarter
- quarter
Divides the object by four. Returns a new object, or nil if the object is not a multiple of four.
commutes
- (BOOL) commutes
Should return YES if multiplication is commutative for all elements of the set that the object belongs to. There is no default implemenation for this method.
commutesWith:
- (BOOL) commutesWith : b
Should return YES if multiplication is commutative for the two objects. There is no default implemenation for this method.
inSemiGroup
- (BOOL) inSemiGroup
Should return YES if the object is an element of a (multiplicative) semigroup, ie. a set equiped with a (possibly non-commutative) multiplicative operation. However, the set doesn't necessarily have a unique unity element. For example, matrices of free dimension don't. There is no default implemenation for this method.
inMonoid
- (BOOL) inMonoid
Should return YES if self is an element of a (multiplicative, possibly non-commutative) monoid, ie. a semigroup with a unique unity element. However, not every element in the set necessarily has a multiplicative inverse. There is no default implemenation for this method.
inGroup
- (BOOL) inGroup
Should return YES if self is an element of a (multiplicative, possibly non-commutative) group, ie. a monoid with a multiplicative inverse for each element. There is no default implemenation for this method.
one
- one
Returns a new reference to the multiplicative unity.
minusOne
- minusOne
Returns a new reference to the opposite of the multiplicative unity. Negates by default the object returned by one.
isOne
- (BOOL) isOne
Should return YES if the object is equal to one. There is no default implementation for this method.
notOne
- (BOOL) notOne
Whether isOne returns NO.
isMinusOne
- (BOOL) isMinusOne
Should return YES if the object is equal to minus one i.e., the additive inverse of the multiplicative unity. There is no default implementation for this method.
notMinusOne
- (BOOL) notMinusOne
Whether isMinusOne returns NO.
square
- square
Returns the square of the object ie., a new object equal to the object multiplied by itself.
multiply:
- multiply : b
Returns a new object equal to the product self b.
power:
- power :(int) n
Returns the object raised to the n-th power ie., a new object obtained by multiplying the object n times by itself.
inverse
- inverse
Returns the multiplicative inverse (a new object). If there is no inverse, the method returns nil.
isUnit
- (BOOL) isUnit
Tests whether the object has a multiplicative inverse. The default implementation tests whether inverse returns nil or not.
notUnit
- (BOOL) notUnit
Whether isUnit returns NO.
divide:
- divide : b
Returns the exact quotient on division ie., returns a new object equal to the object multiplied (to the right) by the inverse of b. If the division fails or if the division is not exact (when there is a remainder), this method returns nil.
remainder:quotient:
- remainder : b quotient :(id *) q
Divides self by b; returns the remainder R, and by reference, the quotient Q, such that a = Q b + R. The quotient should not be computed when a NULL pointer is passed for q. There is no default implementation for this method.
remainder:
- remainder : b
Returns a new object, the remainder on division of self by b. The default implementation invokes remainder:quotient: with a NULL quotient argument.
quotient:
- quotient : b
Returns a new object, the quotient on division of by b. There may be a remainder on division, which can be obtained through remainder:. The default implementation invokes remainder:quotient:, and throws away the remainder.
inEuclideanDomain
- (BOOL) inEuclideanDomain
Returns YES if self is an element of a euclidean domain. There is no default implementation.
isCoprime:
- (BOOL) isCoprime : b
Tests whether the greatest common divisor of self and b is a unit. Computes the gcd (by invoking -gcd:) and then invokes isUnit.
notCoprime:
- (BOOL) notCoprime : b
Whether isCoprime returns NO.
isGcd::
- (BOOL) isGcd : a : b
Whether self is the greatest common divisor of a and b. The default implementation computes the gcd by sending -gcd: and compares to self.
isLcm::
- (BOOL) isLcm : a : b
Whether self is the least common multiple of a and b. The default implementation computes the gcd by sending -lcm: and compares to self.
gcd:
- gcd : b
Returns a new object, the greatest common divisor of self and b. In the case of an additive semigroup, the following should hold : gcd(0,b) = b and gcd(a,0) = a. There is no default implementation for this method.
bezout:gcd:
- bezout : b gcd :(id *) gcd
Returns a new object, the bezout coefficient of the object, and if a non NULL pointer is passed for gcd, by reference, the gcd of object and b. The bezout coefficient is the element u such that u self + v b == gcd.
lcm:
- lcm : b
Returns the least common multiple of the objects. The default implementation multiplies the the objects and divides by their gcd. In the case of an additive semi-group, lcm(a,0) = a and lcm(0,b) = b and lcm(0,0) = 0.
modulo:
- modulo : m
Returns a new object, the representant of the object modulo m. For ordered domains (such as the integers), the representant is kept positive (in the range [0,m[). For domains such as polynomials over a finite field, modulo: is equivalent to remainder:.
multiply:modulo:
- multiply : b modulo : m
Returns a new object, the product self b modulo m. The default implementation first calls multiply: and then modulo:.
squareModulo:
- squareModulo : m
Returns a new object, the square of self modulo m. The default implementation first calls square and then modulo:.
power:modulo:
- power :(int) n modulo : m
Returns a new object, equal to self raised to the n-th power modulo m. The default implementation uses the modular binary exponentation algorithm.
inverseModulo:
- inverseModulo : m
Returns a new object, the inverse of self modulo m. Generates an error message by default.
random
- random
Returns a new random object. For example, for the integers, random returns 0 or 1. For the integers mod p, random returns an integer mod p (possibly zero).
characteristic
- (int) characteristic
Returns the characteristic of (the set of) the object, ie. the number n such that n a is zero for each element a. Domains of characteristic larger than INT_MAX are currently not supported. There is no default implementation of the method.
isCharacteristicZero
- (BOOL) isCharacteristicZero
Whether characteristic returns zero.
notCharacteristicZero
- (BOOL) notCharacteristicZero
Whether characteristic returns not zero.
isCharacteristicTwo
- (BOOL) isCharacteristicTwo
Whether characteristic returns two.
notCharacteristicTwo
- (BOOL) notCharacteristicTwo
Whether characteristic returns not two.
frobenius
- frobenius
Returns a new object, the image of self under the frobenius map, ie. exponentation by the characteristic of self. There is no default implementation.
frobeniusInverse
- frobeniusInverse
Returns a new object, the inverse image of self under the frobenius map, ie. the n-th root of self where n is the characteristic of self. There is no default implementation.
dimensionOverPrimeField
- (int) dimensionOverPrimeField
This method should return the dimension of a finite field over its prime field. For example, the dimension of GaloisField(9) over GaloisField(3) is 2.
inRing
- (BOOL) inRing
The object is in a ring if it's in an additive group and a multiplicative monoid.
inIntegralDomain
- (BOOL) inIntegralDomain
Should return YES if the object is an element of a ring without zero divisors. There is no default implementation of this method. Examples of integral domains in the Computer Algebra Kit include, the integers, the Gaussian (complex) integers and polynomial rings.
inField
- (BOOL) inField
Whether the object is element of an additive group and a multiplicative group. Examples of fields in the Computer Algebra Kit include, the integers mod p, Galois fields, and various fields of fractions such as the rational numbers or rational functions.
inFieldOfFractions
- (BOOL) inFieldOfFractions
Whether the object is element of a field of fractions. Returns NO by default; overridden by Fraction and used by some linear algebra algorithms to reduce computations over a field of fractions to computations over an integral domain.
scalarZero
- scalarZero
Returns a reference to the zero scalar object; you may not free the object returned by this method
scalarContent
- scalarContent
Returns a new scalar object, the (scalar) content of the objects, ie. the gcd of its scalars.
divideScalarContent
- divideScalarContent
If the scalar content is zero, this method simply returns a cheap copy of self. Otherwise, it divides by the content (sending divideScalar:), ie. it computes the primitive part of self.
multiplyScalar:
- multiplyScalar : s
Returns a new object, equal to self multiplied (to the right) by the scalar s.
divideScalar:
- divideScalar : s
Returns a new object, equal to self divided by the scalar s. The division is exact; if it isn't, the method returns nil.
addScalar:
- addScalar : s
Adds the scalar s to the object. Should return a new object.
subtractScalar:
- subtractScalar : s
Subtracts the scalar s from the object. Should return a new object.
printsLeadingSign
- (BOOL) printsLeadingSign
Should return YES if the printing methods for this object print a leading minus sign. This can be used in other implementations to avoid printing a plus sign followed by a minus sign. The default implementation returns NO.
printsSum
- (BOOL) printsSum
Should return YES if the printing methods for this object print multiple terms separated by a plus or minus sign. This can be used in other implementations to place the expression between parentheses if necessary. The default implementation returns NO.
printsProduct
- (BOOL) printsProduct
Should return YES if the printing methods for this object print multiple factors separated by a space or multiplication sign. This can be used in other implementations to place the expression between parentheses if necessary. The default implementation returns NO.
printOn:
- printOn :(IOD) aFile
Should print a textual representation of the object to aFile. Methods such as str, printForDebugger:, printOn: etc. work by invoking this method.