X-Git-Url: https://mattmccutchen.net/bigint/bigint.git/blobdiff_plain/a305e8a577403b7c952e3900f64bbacf464edd98..8cad5ca94a8df88e0f48a5f8d4b9a7d056a59ef6:/BigUnsignedInABase.hh diff --git a/BigUnsignedInABase.hh b/BigUnsignedInABase.hh index 6925151..8f9bdce 100644 --- a/BigUnsignedInABase.hh +++ b/BigUnsignedInABase.hh @@ -6,70 +6,68 @@ #include /* - * A BigUnsignedInABase object represents a nonnegative - * integer of size limited only by available memory, - * represented in a user-specified base that can fit in - * an `unsigned short' (most can, and this saves memory). + * A BigUnsignedInABase object represents a nonnegative integer of size limited + * only by available memory, represented in a user-specified base that can fit + * in an `unsigned short' (most can, and this saves memory). * - * BigUnsignedInABase is intended as an intermediary class - * with little functionality of its own. BigUnsignedInABase - * objects can be constructed from, and converted to, - * BigUnsigneds (requiring multiplication, mods, etc.) and - * `std::string's (by switching digit values for appropriate - * characters). + * BigUnsignedInABase is intended as an intermediary class with little + * functionality of its own. BigUnsignedInABase objects can be constructed + * from, and converted to, BigUnsigneds (requiring multiplication, mods, etc.) + * and `std::string's (by switching digit values for appropriate characters). * * BigUnsignedInABase is similar to BigUnsigned. Note the following: * - * (1) They represent the number in exactly the same way, except - * that BigUnsignedInABase uses ``digits'' (or Digit) where BigUnsigned uses + * (1) They represent the number in exactly the same way, except that + * BigUnsignedInABase uses ``digits'' (or Digit) where BigUnsigned uses * ``blocks'' (or Blk). * - * (2) Both use the management features of NumberlikeArray. (In fact, - * my desire to add a BigUnsignedInABase class without duplicating a - * lot of code led me to introduce NumberlikeArray.) + * (2) Both use the management features of NumberlikeArray. (In fact, my desire + * to add a BigUnsignedInABase class without duplicating a lot of code led me to + * introduce NumberlikeArray.) * - * (3) The only arithmetic operation supported by BigUnsignedInABase - * is an equality test. Use BigUnsigned for arithmetic. + * (3) The only arithmetic operation supported by BigUnsignedInABase is an + * equality test. Use BigUnsigned for arithmetic. */ class BigUnsignedInABase : protected NumberlikeArray { - // TYPES public: - typedef unsigned short Digit; // The digit type that BigUnsignedInABases are built from + // The digits of a BigUnsignedInABase are unsigned shorts. + typedef unsigned short Digit; + // That's also the type of a base. typedef Digit Base; - // FIELDS protected: - Base base; // The base of this BigUnsignedInABase + // The base in which this BigUnsignedInABase is expressed + Base base; - // MANAGEMENT -protected: - // These members generally defer to those in NumberlikeArray, possibly with slight changes. - // It might be nice if one could request that constructors be inherited in C++. - - BigUnsignedInABase(int, Index c) : NumberlikeArray(0, c) {} // Creates a BigUnsignedInABase with a capacity + // Creates a BigUnsignedInABase with a capacity; for internal use. + BigUnsignedInABase(int, Index c) : NumberlikeArray(0, c) {} - void zapLeadingZeros() { // Decreases len to eliminate leading zeros + // Decreases len to eliminate any leading zero digits. + void zapLeadingZeros() { while (len > 0 && blk[len - 1] == 0) len--; } - //void allocate(Index c); // (NlA) Ensures the number array has at least the indicated capacity, maybe discarding contents - //void allocateAndCopy(Index c); // (NlA) Ensures the number array has at least the indicated capacity, preserving its contents - public: - BigUnsignedInABase() : NumberlikeArray(), base(2) {} // Default constructor (value is 0 in base 2) - BigUnsignedInABase(const BigUnsignedInABase &x) : NumberlikeArray(x), base(x.base) {} // Copy constructor + // Constructs zero in base 2. + BigUnsignedInABase() : NumberlikeArray(), base(2) {} - void operator =(const BigUnsignedInABase &x) { // Assignment operator + // Copy constructor + BigUnsignedInABase(const BigUnsignedInABase &x) : NumberlikeArray(x), base(x.base) {} + + // Assignment operator + void operator =(const BigUnsignedInABase &x) { NumberlikeArray::operator =(x); base = x.base; } - BigUnsignedInABase(const Digit *d, Index l) : NumberlikeArray(d, l) { // Constructor from an array of digits - zapLeadingZeros(); - } + // Constructor that copies from a given array of digits. + BigUnsignedInABase(const Digit *d, Index l, Base base); + + // Destructor. NumberlikeArray does the delete for us. + ~BigUnsignedInABase() {} // LINKS TO BIGUNSIGNED BigUnsignedInABase(const BigUnsigned &x, Base base); @@ -77,38 +75,43 @@ public: /* LINKS TO STRINGS * - * These use the symbols ``0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'' to represent - * digits of 0 through 35. When parsing strings, lowercase is also accepted. + * These use the symbols ``0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'' to + * represent digits of 0 through 35. When parsing strings, lowercase is + * also accepted. * - * All string representations are big-endian (big-place-value digits first). - * (Computer scientists have adopted zero-based counting; why can't they - * tolerate little-endian numbers? It makes a lot of sense!) + * All string representations are big-endian (big-place-value digits + * first). (Computer scientists have adopted zero-based counting; why + * can't they tolerate little-endian numbers?) * * No string representation has a ``base indicator'' like ``0x''. * - * An exception is made for zero: it is converted to ``0'' and not the empty string. + * An exception is made for zero: it is converted to ``0'' and not the + * empty string. * - * If you want different conventions, write your - * own routines to go between BigUnsignedInABase and strings. It's not hard. + * If you want different conventions, write your own routines to go + * between BigUnsignedInABase and strings. It's not hard. */ operator std::string() const; BigUnsignedInABase(const std::string &s, Base base); - // PICKING APART - // These accessors can be used to get the pieces of the number public: + + // ACCESSORS Base getBase() const { return base; } - NumberlikeArray::getCapacity; // (NlA) - NumberlikeArray::getLength; // (NlA) - // Note that getDigit returns 0 if the digit index is beyond the length of the number. - // A routine that uses this accessor can safely assume a BigUnsigned has 0s infinitely to the left. + + // Expose these from NumberlikeArray directly. + NumberlikeArray::getCapacity; + NumberlikeArray::getLength; + + /* Returns the requested digit, or 0 if it is beyond the length (as if + * the number had 0s infinitely to the left). */ Digit getDigit(Index i) const { return i >= len ? 0 : blk[i]; } - // Note how we replace one level of abstraction with another. - bool isZero() const { return NumberlikeArray::isEmpty(); } // Often convenient for loops - // EQUALITY TEST -public: - // Equality test + // The number is zero if and only if the canonical length is zero. + bool isZero() const { return NumberlikeArray::isEmpty(); } + + /* Equality test. For the purposes of this test, two BigUnsignedInABase + * values must have the same base to be equal. */ bool operator ==(const BigUnsignedInABase &x) const { return base == x.base && NumberlikeArray::operator ==(x); }