[svn:parrot-pdd] r33181 - trunk/docs/pdds/draft

Author: allison
Date: Mon Nov 24 23:41:10 2008
New Revision: 33181

Modified:
   trunk/docs/pdds/draft/pdd14_numbers.pod

Log:
[pdds] Add interface definition for Integer PMC.


Modified: trunk/docs/pdds/draft/pdd14_numbers.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd14_numbers.pod	(original)
+++ trunk/docs/pdds/draft/pdd14_numbers.pod	Mon Nov 24 23:41:10 2008
@@ -49,9 +49,172 @@
 
 =head2 Integer PMC
 
+The C<Integer> PMC is a high-level integer type, providing the features of a
+integer data type appropriate for use in a high-level language. Some languages
+may be able to use Parrot's C<Integer> directly as their integer data type,
+others may subclass C<Integer> to add their own functionality, and others may
+implement their own high-level integer data type.
+
+The C<Integer> PMC has a single attribute, the integer value.
+
+=head3 Integer Vtable Functions
+
+=over 4
+
+=item init()
+
+Initialize the C<Integer> to 0.
+
+=item set_pmc(PMC *value) and set_integer_same(PMC* value)
+
+Set the C<Integer> to the integer value of the PMC argument.
+
+=item set_integer_native(INTVAL value)
+
+Set the C<Integer> to the passed-in integer value.
+
+=item set_number_native(FLOATVAL value), set_bool(INTVAL value), set_bigint_int(INTVAL value), set_string_native(STRING *value)
+
+Morphs the C<Integer> PMC to a C<Float>, C<Boolean>, C<BigInt>, or C<String>
+PMC, and sets the value from the passed in value.
+
+{{NOTE: the morphing behavior is currently under consideration and may be
+rejected.}}
+
+=item get_integer()
+
+Retrieves the integer value of the C<Integer>.
+
+=item get_bool()
+
+Returns the boolean value of the C<Integer> (false if 0, true otherwise).
+
+=item get_number()
+
+Returns the integer value of the C<Integer> as a floating-point number.
+
+=item get_bignum()
+
+Returns the integer value of the C<Integer> in a new C<BigInt> PMC.
+
+=item get_string() and get_repr()
+
+Returns the integer value of the C<Integer> as a string.
+
+=item [add|subtract|multiply|divide|floor_divide|modulus|pow]_int(INTVAL b, PMC *dest)
+
+Add/subtract/multiply/divide/modulus/exponent an integer value with the
+C<Integer> PMC, and return the result as a new PMC (the C<dest> parameter is
+unused). Overflow of the native integer storage auto-promotes the result PMC
+to a C<BigInt>.
+
+=item i_[add|subtract|multiply|divide|floor_divide|modulus|pow]_int(INTVAL b)
+
+Add/subtract/multiply/divide/modulus/exponent an integer value with the
+C<Integer> PMC, and set the C<Integer> to the resulting value. Overflow of the
+native integer storage auto-promotes the C<Integer> to a C<BigInt>.
+
+{{NOTE: there is some discussion of having this promotion of storage happen
+purely internally (perhaps by swapping vtables), rather than converting to a
+different PMC type.}}
+
+=item i_[add|subtract|multiply|divide|floor_divide|modulus|pow]_float(INTVAL b)
+
+Add/subtract/multiply/divide/modulus/exponent an integer value with the
+C<Integer> PMC, and set the C<Integer> to the resulting value, morphing it to a
+C<Float>.
+
+=item increment()
+
+Add 1 to the value of the integer.
+
+=item decrement()
+
+Subtract 1 from the value of the integer.
+
+=item absolute()
+
+Return an C<Integer> PMC set to the absolute value of the current C<Integer>.
+
+=item i_absolute()
+
+Set the C<Integer> to the absolute value of itself.
+
+=item freeze()
+
+Freeze the C<Integer> PMC for storage.
+
+=item thaw()
+
+Thaw the C<Integer> PMC from storage.
+
+
+=back
+
+=head3 Integer Multis
+
+Many of the math vtable functions are defined instead as multiple dispatch
+functions.
+
+=over 4
+
+=item [add|subtract|multiply|divide|floor_divide|modulus|pow](PMC *value, PMC *dest)
+
+Perform the addition/subtraction/multiplication/division/modulus/exponent
+operation, and return a new PMC containing the resulting value. Multiple
+dispatch variants are defined for C<Integer>, C<Complex>, C<BigInt>, C<String>,
+and C<DEFAULT>.
+
+Overflow of the native integer storage auto-promotes the result PMC to a
+C<BigInt>.
+
+=item i_[add|subtract|multiply|divide|floor_divide|modulus|pow](PMC *value)
+
+Perform the addition/subtraction/multiplication/division/modulus/exponent
+operation, morphing the C<Integer> to the passed in type, and setting it to the
+result. Multiple dispatch variants are defined for C<Integer>, C<Complex>,
+C<BigInt>, and C<DEFAULT>.
+
+Overflow of the native integer storage auto-promotes the C<Integer> to a
+C<BigInt>.
+
+=item is_equal(PMC *value)
+
+Compare the C<Integer> to the passed in PMC, return true (1) if they are equal,
+and false (0) otherwise. Multiple dispatch variants are defined for C<BigInt>
+and C<DEFAULT>. {{NOTE: Presumably the C<String>, C<Integer>, and C<Float>
+cases are all covered by C<DEFAULT>.}}
+
+=item cmp(PMC *value)
+
+Compare the C<Integer> to the passed in PMC, return 1 if C<Integer> is greater,
+-1 if the PMC is greater, and 0 if they are equal. Multiple dispatch variants
+are defined for C<String>, C<Float>, and C<DEFAULT>. {{NOTE: Presumably the
+C<Integer> and C<BigInt> cases are covered by C<DEFAULT>.}}
+
+=item cmp_num(PMC *value)
+
+Compare the C<Integer> to the passed in PMC, return 1 if C<Integer> is greater,
+-1 if the PMC is greater, and 0 if they are equal. Multiple dispatch variants
+are defined for C<String>, C<Float>, and C<DEFAULT>. {{NOTE: Presumably the
+C<Integer> and C<BigInt> cases are covered by C<DEFAULT>.}}
+
+=back
+
+=head3 Integer Methods
+
+=over 4
+
+=item get_as_base(INTVAL base)
+
+Convert the decimal integer to another base (anything from base 2 to base 36).
+Return the result as a string.
+
+=back
+
 =head2 Float PMC
 
-=head2 BigNum PMC
+=head2 BigInt PMC
 
 The big number library provides Parrot with both a collection of (nearly)
 infinite precision numeric types and an implementation of an extended decimal
@@ -394,7 +557,7 @@
 =head1 Tests
 
 The Standard Decimal Arithmetic provides a collection of tests for both its
-base and extended behaviour.  Initially it is hoped that this library can pass
+base and extended behavior.  Initially it is hoped that this library can pass
 all base tests, with extended tests to be included at a later date as it is
 extended to cope with values such as +Inf.