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.
+ (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.
+str:(STR)aStringCreates an object given a string description. No default implementation.
+int:(int)intValueCreates an object given an int value. No default.
-copyCreates a copy of the object by sending copy to super. Sets the reference count of the new object to one.
Subclasses must implement their own versions of copy to copy additional memory consumed by the copied object.
- copy
{
self = [super copy];
pointer = malloc(nBytes);
return self;
}
See also: deepCopy
-deepCopyCreates a deep copy of the object by sending copy to super. Sets the reference count of the new object to one.
Subclasses must implement their own versions of deepCopy to make a full independent copy of the object.
- deepCopy
{
self = [super deepCopy];
companionObject = [companionObject deepCopy];
return self;
}
- (BOOL)sameClass:aWhether 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];
- (BOOL)differentClass:aWhether sameClass: returns NO. Don't override this method. Implement your own version of sameClass: instead (incorporating a call to super's implementation of sameClass:).
- (BOOL)isKindOfSequenceEquivalent to :
[self isKindOf:(id)[CASequence class]]
- (STR)strReturns 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.
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 :
fprintf(stderr,"Value of this %s is %s\n",[anObject name],[anObject str]);
-str:(STR)aStringReturns 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.
- (int)intValueReturns, if it makes sense, the value of the object as C integer. There is no default implementation for this method.
-intValue:(int)iReturns a new object of the same class with intValue equal to i or returns nil.
-asModp:(unsigned short)pReturns 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.
- (BOOL)isFloatingPointReturns 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.
-asNumericalReturns 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.
- (float)floatValueReturns, if it makes sense, the value of the object as C floating-point number. There is no default implementation for this method.
-floatValue:(float)fReturns a new object of the same class with floatValue equal to f or returns nil.
-asTotalFractionReturns 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.
-asScalarReturns 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.
-asSymbolReturns 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.
Note: Symbol itself does not implement this method.
- (BOOL)isEqual:aShould test whether the objects are equal. Returns, by default, YES if the two objects are the same (ie. pointer equal)
- (BOOL)notEqual:aWhether isEqual: returns NO.
- (BOOL)inOrderedSetWhether 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.
- (int)compare:bThis 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.
- (int)signReturns 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.
- (BOOL)isLess:aTests whether the object is less than (but not equal to) a. Defined, by default, in terms of compare:.
- (BOOL)isGreater:aTests whether the object is greater than (but not equal to) a. Defined, by default, in terms of compare:.
- (BOOL)isLessEqual:aTests whether the object is less than or equal to a. Defined, by default, in terms of compare:.
- (BOOL)isGreaterEqual:aTests whether the object is greater than or equal to a. Defined, by default, in terms of compare:.
-absValueReturns the absolute value of the object (a new object). If the object is negative, invokes negate. Otherwise returns self.
- (BOOL)inAdditiveSemiGroupShould 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.
- (BOOL)inAdditiveMonoidShould 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.
- (BOOL)inAdditiveGroupShould 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.
- (BOOL)isZeroReturns YES if the object is equal to zero. There is no default implementation for 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.
- (BOOL)notZeroWhether isZero returns NO.
- (BOOL)isOpposite:bShould 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.
- (BOOL)notOpposite:bWhether isOpposite returns NO.
-zeroReturns a new reference to the zero element.
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.
-negateReturns the opposite of the object (a new object). There is no default implementation.
-add:bReturns 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:bReturns a new object, equal to self - b. If the object is pointer equal to the argument, this method is equivalent to zero.
-incrementAdds one to the object. Returns a new object.
-decrementSubtracts one from the object. Returns a new object.
-multiplyIntValue:(int)bReturns a new object equal to the product self b. The default implementation creates an object through -intValue: and then invokes multiply:.
See also: zero, double, quadruple
-doubleMultiplies the object by two. Returns a new object. There is no default implementation for this method.
-quadrupleMultiplies the object by four. Returns a new object.
There is no default implementation for this method.
-divideIntValue:(int)bReturns 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.
-halfDivides the object by two. Returns a new object, or nil if the object is not a multiple of two.
-quarterDivides the object by four. Returns a new object, or nil if the object is not a multiple of four.
- (BOOL)commutesShould 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.
- (BOOL)commutesWith:bShould return YES if multiplication is commutative for the two objects. There is no default implemenation for this method.
- (BOOL)inSemiGroupShould 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.
- (BOOL)inMonoidShould 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.
- (BOOL)inGroupShould 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.
-oneReturns a new reference to the multiplicative unity.
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.
-minusOneReturns a new reference to the opposite of the multiplicative unity. Negates by default the object returned by one.
- (BOOL)isOneShould return YES if the object is equal to one. 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.
- (BOOL)notOneWhether isOne returns NO.
- (BOOL)isMinusOneShould 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.
- (BOOL)notMinusOneWhether isMinusOne returns NO.
-squareReturns the square of the object ie., a new object equal to the object multiplied by itself.
-multiply:bReturns a new object equal to the product self b.
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.
-power:(int)nReturns the object raised to the n-th power ie., a new object obtained by multiplying the object n times by itself.
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.).
-inverseReturns the multiplicative inverse (a new object). If there is no inverse, the method returns nil.
- (BOOL)isUnitTests whether the object has a multiplicative inverse. The default implementation tests whether inverse returns nil or not.
- (BOOL)notUnitWhether isUnit returns NO.
-divide:bReturns 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.
Note: Use quotient: to determine the quotient of a division with remainder.
-remainder:bquotient:(id *)qDivides 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.
See also: divide, quotient, remainder
-remainder:bReturns a new object, the remainder on division of self by b. The default implementation invokes remainder:quotient: with a NULL quotient argument.
Note: For ordered domains (such as the integers), this method should return a signed remainder, while modulo: returns an unsigned remainder.
See also: modulo
-quotient:bReturns 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.
See also: divide
- (BOOL)inEuclideanDomainReturns YES if self is an element of a euclidean domain. There is no default implementation.
- (BOOL)isCoprime:bTests whether the greatest common divisor of self and b is a unit. Computes the gcd (by invoking -gcd:) and then invokes isUnit.
- (BOOL)notCoprime:bWhether isCoprime returns NO.
- (BOOL)isGcd:a:bWhether self is the greatest common divisor of a and b. The default implementation computes the gcd by sending -gcd: and compares to self.
- (BOOL)isLcm:a:bWhether self is the least common multiple of a and b. The default implementation computes the gcd by sending -lcm: and compares to self.
-gcd:bReturns 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:bgcd:(id *)gcdReturns 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.
There is no default implementation for this method.
-lcm:bReturns 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:mReturns 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:.
The default implementation invokes remainder:. Adds back m, if self is ordered and the remainder is negative.
-multiply:bmodulo:mReturns a new object, the product self b modulo m. The default implementation first calls multiply: and then modulo:.
-squareModulo:mReturns a new object, the square of self modulo m. The default implementation first calls square and then modulo:.
-power:(int)nmodulo:mReturns a new object, equal to self raised to the n-th power modulo m. The default implementation uses the modular binary exponentation algorithm.
If self and n are equal to zero, returns nil.
See also: genpower:modulo:
-genpower:nmodulo:mReturns a new object, equal to self raised to the n-th power modulo m (where n is an instance of the BigInt class). The default implementation uses the modular binary exponentation algorithm.
If self and n are equal to zero, returns nil.
-inverseModulo:mReturns a new object, the inverse of self modulo m. Generates an error message by default.
-randomReturns 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).
There is no default implementation.
- (int)characteristicReturns 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.
- (BOOL)isCharacteristicZeroWhether characteristic returns zero.
- (BOOL)notCharacteristicZeroWhether characteristic returns not zero.
- (BOOL)isCharacteristicTwoWhether characteristic returns two.
- (BOOL)notCharacteristicTwoWhether characteristic returns not two.
-frobeniusReturns a new object, the image of self under the frobenius map, ie. exponentation by the characteristic of self. There is no default implementation.
-frobeniusInverseReturns 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.
- (int)dimensionOverPrimeFieldThis 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.
- (BOOL)inRingThe object is in a ring if it's in an additive group and a multiplicative monoid.
- (BOOL)inIntegralDomainShould 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.
- (BOOL)inFieldWhether 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.
- (BOOL)inFieldOfFractionsWhether 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.
-scalarZeroReturns a reference to the zero scalar object.
See also: zero
-scalarContentReturns a new scalar object, the (scalar) content of the objects, ie. the gcd of its scalars.
There is no default implementation of this method.
-divideScalarContentIf the scalar content is zero, this method simply returns a copy of self. Otherwise, it divides by the content (sending divideScalar:), ie. it computes the primitive part of self.
-multiplyScalar:sReturns a new object, equal to self multiplied (to the right) by the scalar s.
-divideScalar:sReturns a new object, equal to self divided by the scalar s. The division is exact; if it isn't, the method returns nil.
-addScalar:sAdds the scalar s to the object. Should return a new object.
-subtractScalar:sSubtracts the scalar s from the object. Should return a new object.
- (BOOL)printsLeadingSignShould 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.
- (BOOL)printsSumShould 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.
- (BOOL)printsProductShould 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:(IOD)aFileShould print a textual representation of the object to aFile. Methods such as str, printForDebugger:, printOn: etc. work by invoking this method.