Destiny Project

Generic Quantity Class

Introduction

The generic quantity class is established for the purpose of representing a quantity that is capable of holding either a logical value, a logical vector, a number, a numeric vector, a binary pattern, a vector of binary patterns, or a string of characters.

Logical Quantities

A simple logical quantity is one that is subject to the normal rules of three-state logic. The three states that can be represented by a logical quantity are True, False, and Indeterminate (or Maybe). A logical vector quantity holds an ordered array of a finite number of logical values.

Internal Representation

Relying, as they do, on three-state logic for their functionality, logical quantities cannot be represented by the standard two-state C++ bool type. Instead, a separate enumerated boolTrinary type has been defined with the three states btFalse, btTrue, and btMaybe. Thus, a simple logical quantity is currently represented internally as boolTrinary and logical vectors are represented as Standard Template Library vectors of boolTrinary.

Numeric Quantities

A simple numeric quantity is a number that is subject to the normal rules of arithmetic. The concept of a simple numeric quantity corresponds to the standard C++ definition of an arithmetic type. Similarly, a numeric vector quantity holds an ordered array of a finite number of numbers and behaves according to the standard rules of vector mathematics.

Internal Representation

The current generation of operating systems within our target domain implements a long integer with 32 bits. In the same systems, a double is implemented with 64 bits: 12 bits for the exponent and 52 bits for the mantissa. Thus a double has greater range at integer precision. For this reason, simple numeric quantities are currently represented internally as doubles and numeric vectors are represented as Standard Template Library vectors of doubles.

Binary Quantities

A simple binary quantity holds a bit pattern of up to 32 bits. Binary quantities are useful with the standard bitwise operators of C++ (and, or, exclusive or, not). A binary vector quantity holds an ordered array of a finite number of 32-bit binary patterns.

Internal Representation

The current generation of operating systems within our target domain implements both integers and long integers with 32 bits. For this reason, simple binary quantities are currently represented internally as unsigned integers and binary vectors are represented as Standard Template Library vectors of unsigned integers.

String Quantities

A string quantity holds an ordered array of a finite number of standard ASCII characters. Strings may be concatenated, and when strings are compared lexical ordering is used.

Internal Representation

The current implementation derives a great deal of its functionality and portability from the Standard Template Library. For this reason, string quantities are currently represented internally as Standard Template Library strings. Support for Unicode characters has not yet been implemented.

Quantity Constructors

Logical Quantities

Logical quantities can be constructed from a standard bool or a boolTrinary initial value, or from a bool literal (either true or false). Logical vector quantities can be constructed from Standard Template Library vectors of either bool or boolTrinary.

Numeric Quantities

Numeric quantities can be constructed from initial values of either double, int, or unsigned int, or from an arithmetic literal. Numeric vector quantities can be constructed from Standard Template Library vectors of either double, int, or unsigned int.

Binary Quantities

Binary quantities can be constructed from initial values of either int or unsigned int, or from an integral arithmetic literal, if a second argument of Quantity::Binary is specified in the declaration. Binary vector quantities can be constructed from Standard Template Library vectors of either int, or unsigned int if a second argument of Quantity::BinaryVector is specified for the constructor.

String Quantities

String quantities can be constructed from an initial Standard Template Library string, a character pointer to a null-terminated string, or a quoted string literal.

Quantity Operations

Logical Operations

Assignment

Assigning a logical quantity, a bool, a boolTrinary, or a Boolean literal to any quantity will result in a logical quantity with the specified value. Assigning a logical vector quantity or a Standard Template Library vector of either bool or boolTrinary to any quantity will result in a logical vector quantity with the specified values.

Logical Negation

Logical negation operations may be performed on any quantity. If the operand is not a logical or logical vector quantity, however, the result is that of applying the operator to the result of the quantity's ValueBoolean function. (In most cases, the ValueBoolean function merely indicates whether the size and contents of the quantity are both non-zero.)

The operator ! (logical negation) negates the logical trinary operand. If the operand is a logical vector, the negation is applied to each element of the vector.

!  
btFalse btTrue
btMaybe btMaybe
btTrue btFalse

Logical And and Logical Or

Logical and and or operations may be performed on any quantity. If the operands are not either both simple logical quantities or both logical vector quantities of the same size, however, the result is that of applying the operator to the result of the quantity's ValueBoolean function. (In most cases, the ValueBoolean function merely indicates whether the size and contents of the quantity are both non-zero.) When the operands are logical vectors of the same size, the operation is applied pair-wise to the corresponding elements of the vectors, resulting in a logical vector quantity.

The operator && (logical and) performs a trinary and between the two operands.

&& btFalse btMaybe btTrue
btFalse btFalse btFalse btFalse
btMaybe btFalse btMaybe btMaybe
btTrue btFalse btMaybe btTrue

The operator || (logical or) performs a trinary or between the two operands.

|| btFalse btMaybe btTrue
btFalse btFalse btMaybe btTrue
btMaybe btMaybe btMaybe btTrue
btTrue btTrue btTrue btTrue

Comparison

The comparison operator == (equality) is true if and only if the quantities are either both logical quantities and contain the same value or the quantities are both logical vectors of equal size and each pair of corresponding elements is equal. Operator != (not equal) gives the opposite result of ==. Operators > (greater) and < (less than) always return false; operators >= (greater than or equal), and <= (less than or equal) are thus no different from ==.

Subscript

The operator [ ] (subscript) selects the indexed quantity from a vector quantity and returns a quantity which contains only the indexed vector element. The subscripted result element is a copy of the element of the original vector, so assigning to it will not change the original vector. It is not an error, though usually without utility, to select subscript 0 from a simple (non-vector) quantity; the result is a copy of the original quantity. It is an error to select a non-zero subscript from a simple quantity or to select an element with a subscript beyond the bounds of a vector quantity; the result is a quantity of type Quantity::Unknown.

Numeric Operations

Assignment

Assignment of a numeric or numeric vector quantity to a quantity of any type results in a copy of the numeric or numeric vector quantity. Assignment of a value of type double, int, or unsigned int, or of an arithmetic literal, to a quantity of any type results in a numeric quantity with the specified value, except assignment of an integral value or literal to a binary or binary vector quantity (which results in a binary quantity). Assignment of a vector of double, int, or unsigned int to a quantity of any type results in a numeric vector quantity containing the specified values, except assignment of a vector of integral type to a binary or binary vector quantity (which results in a binary vector quantity).

Comparison

The comparison operator == (equality) is true if and only if the quantities are either both numeric quantities and contain the same value or the quantities are both numeric vectors of equal size and each pair of corresponding elements is equal. Operator != (not equal) gives the opposite result of ==. Operators > (greater), < (less than), >= (greater than or equal), and <= (less than or equal) compare arithmetically in the case of simple (non-vector) numeric quantities; when used with numeric vectors it is the magnitudes of the vectors which are arithmetically compared. Used between simple numeric quantities and numeric vector quantities, >, <, >=, and <= perform an arithmetic comparison between the value of the simple numeric and the magnitude of the numeric vector. To reiterate, the equality operators test strict equality, while the comparison operators test magnitudes.

Subscript

The operator [ ] (subscript) selects the indexed quantity from a vector quantity and returns a quantity which contains only the indexed vector element. The subscripted result element is a copy of the element of the original vector, so assigning to it will not change the original vector. It is not an error, though usually without utility, to select subscript 0 from a simple (non-vector) quantity; the result is a copy of the original quantity. It is an error to select a non-zero subscript from a simple quantity or to select an element with a subscript beyond the bounds of a vector quantity; the result is a quantity of type Quantity::Unknown.

Arithmetic Negation

Arithmetic negation operations are valid only if the operand is either a simple numeric quantity or a numeric vector quantity. If an arithmetic negation operation is applied to other types of quantities, the result will be a quantity of type Quantity::Unknown.

The operator - (arithmetic negation) results in a quantity with a value which is the negative of the original value of the operand.

Addition

Addition operations are valid only if both of the operands are simple numeric quantities or if both of the operands are numeric vector quantities of the same size. The only other use of the + and += quantity operators is for concatenation of string quantities. If an addition operation is applied to other types of quantities, the result will be a quantity of type Quantity::Unknown.

The operators + and += (addition) sum the left-hand and right-hand operands. In the case of the += operator, the result replaces the left-hand operand.

Subtraction

Subtraction operations are valid only if both of the operands are simple numeric quantities or if both of the operands are numeric vector quantities of the same size. If a subtraction operation is applied to other types of quantities, the result will be a quantity of type Quantity::Unknown.

The operators - and -= (subtraction) subtract the right-hand operand from the left-hand operand. In the case of the -= operator, the result replaces the left-hand operand.

Multiplication

Multiplication operations are valid only if one of the operands is a simple numeric quantity and the other operand is either a numeric or numeric vector quantity. Support for cross-product computation has not yet been implemented. If a multiplication operation is applied to other types of quantities, the result will be a quantity of type Quantity::Unknown.

The operators * and *= (multiplication) multiply the two operands together. In the case of the *= operator, the result replaces the value of the left-hand operand.

Division and Modulus

Division and modulus operations are valid only if the left-hand operand is a numeric or numeric vector quantity and the right-hand operand is a simple numeric quantity. If division or modulus operations are applied to other types of quantities, the result will be a quantity of type Quantity::Unknown.

The operators / and /= (division) divide the left-hand operand by the right-hand operand. The operators % and %= (modulus) take the modulus of the left-hand operand with respect to the right-hand operand. In the cases of the /= and %= operators, the result replaces the value of the left-hand operand.

Increment and Decrement

Increment and decrement operations are valid only if the operand is a simple numeric quantity. If increment or decrement operations are applied to other types of quantities, the result will be a quantity of type Quantity::Unknown.

The operator ++ (increment) increments the numeric quantity by one. The operator -- (decrement) decrements the numeric quantity by one. The operators ++ and -- may be used either as prefix operators or as postfix operators in the usual fashion.

Binary Operations

Assignment

Assignment of a binary or binary vector quantity to a quantity of any type results in a copy of the binary or binary vector quantity. Assignment of a value of type int or unsigned int, or of an integral literal, to a quantity of binary or binary vector type results in a binary quantity with the specified value. Assignment of a vector of int or unsigned int to a quantity of binary or binary vector type results in a binary vector quantity containing the specified values. Assignment of arithmetic values or vectors thereof to a quantity which is not of either binary or binary vector type will not result in a binary or binary vector quantity, but will result instead in either a numeric or numeric vector quantity.

Bitwise Shifting

Bitwise shift operations are valid only if the left-hand operand is a binary or binary vector quantity and the right-hand operand is a simple numeric quantity. If bitwise shift operations are applied to other types of quantities, the result will be a quantity of type Quantity::Unknown.

Operators >> and >>= (right shift) shift the binary quantity, or each element of the binary vector quantity, right by the number of bits given in the numeric quantity. Operators << and <<= (left shift) shift the binary quantity, or each element of the binary vector quantity, left by the number of bits given in the numeric quantity. In the cases of the >>= and <<= operators, the result replaces the value of the left-hand operand.

Bitwise Logic

Bitwise logic operations are valid only for quantities of binary or binary vector type. If bitwise logic operations are applied to other types of quantities, the result will be a quantity of type Quantity::Unknown.

The operator ~ (bitwise negation) operates on a binary quantity as though it were a 32-bit unsigned integer; if applied to a binary vector, each vector element is negated as though it were a 32-bit unsigned integer.

The operators & and &= (bitwise and), | and |= (bitwise inclusive or), and ^ and ^= (bitwise exclusive or) are used to perform their respective operations between two binary quantities. If applied between binary and binary vector types, the result is a vector in which each element is the result of applying the bitwise operation between the corresponding element of the original binary vector and the simple binary quantity. If applied between two binary vector quantities (which must be of the same size), the result is a vector in which each element is the result of applying the operation pair-wise between the corresponding elements of the two binary vector quantities. In the cases of the &=, |=, and ^= operators, the result replaces the left-hand operand.

Comparison

The comparison operator == (equality) is true if and only if the quantities are either both binary quantities and contain the same value or the quantities are both binary vectors of equal size and each pair of corresponding elements is equal. Operator != (not equal) gives the opposite result of ==. Operators > (greater) and < (less than) always return false; operators >= (greater than or equal), and <= (less than or equal) are thus no different from ==.

Subscript

The operator [ ] (subscript) selects the indexed quantity from a vector quantity and returns a quantity which contains only the indexed vector element. The subscripted result element is a copy of the element of the original vector, so assigning to it will not change the original vector. It is not an error, though usually without utility, to select subscript 0 from a simple (non-vector) quantity; the result is a copy of the original quantity. It is an error to select a non-zero subscript from a simple quantity or to select an element with a subscript beyond the bounds of a vector quantity; the result is a quantity of type Quantity::Unknown.

String Operations

Assignment

Assigning a string quantity, a Standard Template Library string, a character pointer, or a quoted string literal to any quantity will result in a string quantity with the specified value.

Concatenation

The operators + and += between two string quantities have as their result the concatenation of the right-hand string to the end of the left-hand string. In the case of the += operator, this result replaces the original value of the left-hand string.

Comparison

The comparison operator == (equality) is true if and only if the strings contain the same characters in the same order. The comparison operators > (greater) and < (less than) perform comparisons using lexical ordering. Operator != (not equal) gives the opposite result of ==. Operators >= (greater than or equal), and <= (less than or equal) behave as logical disjunctions of == and either > or <.

Subscript

The operator [ ] (subscript) selects the indexed character from the string quantity and returns a string quantity which contains only the indexed character. The subscripted result element is a copy of the element of the original string, so assigning to it will not change the original string. It is an error to select an element with a subscript beyond the bounds of a string quantity; the result is a quantity of type Quantity::Unknown.

Quantity Functions

Type Functions

Size

The Size function returns the number of elements in the quantity. Applied to simple quantities, the result is one. Applied to vector quantities, the result is the number of vector elements. Applied to string quantities, the result is the number of characters in the string.

Type

The Type function returns the type of the quantity. The following types are currently supported:

Type Tests

Type tests return a bool indicating whether the quantity type was a member of the set of types to which the test responds affirmatively. In general, the type test functions are to be preferred in application code over testing the result of the Type function against the various Quantity::ElementType enumerations.

IsBinary returns true for binary or binary vector quantities. IsLogical returns true for logical or logical vector quantities. IsNumeric returns true for numeric or numeric vector quantities. IsString returns true for string quantities.

IsSimple returns true for binary, logical, or numeric quantities. IsVector returns true for binary vector, logical vector, or numeric vector quantities.

Value Functions

Magnitude

The Magnitude function returns a double representing the magnitude of a numeric quantity or a numeric vector quantity. If applied to other types of quantities, the Magnitude function returns 0.0. The Magnitude function is used implicitly when performing > or < comparisons with a numeric vector quantity.

Value Conversion

The family of value functions converts the value(s) of a quantity into various standard types.

ValueBool converts a quantity into a standard bool. Its result is similar to that of the ValueBoolean function (see below), except that a value of btTrue is converted to true, while btMaybe and btFalse are converted to false.

ValueBoolVector converts a quantity into a Standard Template Library vector of bool. Its result is similar to that of the ValueBooleanVector function (see below), except that values of btTrue are converted to true, while btMaybe and btFalse are converted to false.

ValueBoolean converts a quantity into a boolTrinary. When applied to a simple logical quantity or a logical vector quantity of size one, the return is the logical value. Applied to longer logical vectors, the return indicates the logical trinary or of all vector elements. Applied to non-logical simple quantities, the result indicates whether the numeric or binary quantity is non-zero. Applied to non-logical vector quantities, the result indicates whether the vector has any non-zero elements. Applied to string quantities, the result indicates whether the string contains any characters.

ValueBooleanVector converts a quantity into a Standard Template Library vector of boolTrinary. When applied to a logical vector quantity, the return is the logical vector. When applied to a simple logical quantity, a vector of size one is created to hold the value. When applied to other simple quantities, a vector of size one is created to hold a value which is converted according to the rules for the ValueBoolean function (see above). Applied to other vector quantities, the result is a vector of values, each element of which represents the value of the corresponding element of the original vector converted as for simple quantities by the ValueBoolean function. Applied to string quantities, the result is a vector of size one holding a value which indicates whether the string contains any characters.

ValueDouble converts a quantity into a double. When applied to simple numeric quantities or single-element numeric vectors, the return is the numeric value. When applied to simple binary quantities or single-element binary vectors, the usual conversion from unsigned integer to double is performed. When applied to simple logical quantities or single-element logical vectors, values of btTrue are converted to one while values of btMaybe and btFalse are converted to zero. [NOTE: This is an area of possible change. Later versions may use something more conducive to real reasoning, such as one for true, minus one for false, and zero for unknown (maybe). For now, the usual C convention applies.] When applied to single-character strings, the value is that of the character code, converted to type double. When applied to longer vectors or strings, a value of zero is returned.

ValueDoubleVector converts a quantity into a Standard Template Library vector of double. Applied to simple quantities, the result is a single-element vector holding the value as converted for the ValueDouble function. Applied to vector quantities, the result is a vector of values, each element of which represents the value of the corresponding element of the original vector converted as for simple quantities by the ValueDouble function. Applied to string quantities, the result is a vector of values, each element of which represents the value of the corresponding character code converted as for single-character strings by the ValueDouble function.

ValueInteger converts a quantity into an int. When applied to simple numeric quantities or single-element numeric vectors, the usual conversion from double to integer is performed. When applied to simple binary quantities or single-element binary vectors, the usual conversion from unsigned integer to integer is performed. When applied to simple logical quantities or single-element logical vectors, values of btTrue are converted to one while values of btMaybe and btFalse are converted to zero. When applied to single-character strings, the value is that of the character code, converted to type int. When applied to longer vectors or strings, a value of zero is returned.

ValueIntegerVector converts a quantity into a Standard Template Library vector of int. Applied to simple quantities, the result is a single-element vector holding the value as converted for the ValueInteger function. Applied to vector quantities, the result is a vector of values, each element of which represents the value of the corresponding element of the original vector converted as for simple quantities by the ValueInteger function. Applied to string quantities, the result is a vector of values, each element of which represents the value of the corresponding character code converted as for single-character strings by the ValueInteger function.

ValueString converts a quantity into a Standard Template Library string. When applied to string quantities, the result is a string containing the characters from the string quantity. Simple logical quantities are converted as the strings "true", "false", and "maybe". Simple numeric quantities are converted as for printf with a format string of "20lG". Simple binary quantities are converted as a string of hexadecimal digits. Vector quantities are converted as a comma-delimited list of the results of converting each element of the vector according to the rules for simple quantities which is enclosed by braces (e.g. "{true, true, false, maybe}"); a single space trails each comma.

ValueUnsigned converts a quantity into an unsigned int. When applied to simple binary quantities or single-element binary vectors, this is a copy of the binary value. When applied to simple numeric quantities or single-element numeric vectors, the usual conversion from double to unsigned integer is performed. When applied to simple logical quantities or single-element logical vectors, values of btTrue are converted to one while values of btMaybe and btFalse are converted to zero. When applied to single-character strings, the value is that of the character code, converted to type unsigned int. When applied to longer vectors or strings, a value of zero is returned.

ValueUnsignedVector converts a quantity into a Standard Template Library vector of unsigned int. Applied to simple quantities, the result is a single-element vector holding the value as converted for the ValueUnsigned function. Applied to vector quantities, the result is a vector of values, each element of which represents the value of the corresponding element of the original vector converted as for simple quantities by the ValueUnsigned function. Applied to string quantities, the result is a vector of values, each element of which represents the value of the corresponding character code converted as for single-character strings by the ValueUnsigned function.


Back to the Destiny documents