Mostly fixing and standardising documentation.
This commit is contained in:
parent
0f8bc990f2
commit
22fa7314d6
24 changed files with 770 additions and 503 deletions
|
|
@ -41,13 +41,12 @@ const char *hex_digits = "0123456789ABCDEF";
|
|||
/*
|
||||
* Doctrine from here on in is that ALL integers are bignums, it's just
|
||||
* that integers less than 65 bits are bignums of one cell only.
|
||||
*
|
||||
* TODO: I have no idea at all how I'm going to print bignums!
|
||||
*/
|
||||
|
||||
/**
|
||||
* return the numeric value of this cell, as a C primitive double, not
|
||||
* as a cons-space object. Cell may in principle be any kind of number.
|
||||
* return the numeric value of the cell indicated by this `pointer`, as a C
|
||||
* primitive double, not as a cons_space_object. The indicated cell may in
|
||||
* principle be any kind of number; if it is not a number, will return `NAN`.
|
||||
*/
|
||||
long double numeric_value( struct cons_pointer pointer ) {
|
||||
long double result = NAN;
|
||||
|
|
@ -75,7 +74,10 @@ long double numeric_value( struct cons_pointer pointer ) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Allocate an integer cell representing this value and return a cons pointer to it.
|
||||
* Allocate an integer cell representing this `value` and return a cons_pointer to it.
|
||||
* @param value an integer value;
|
||||
* @param more `NIL`, or a pointer to the more significant cell(s) of this number.
|
||||
* *NOTE* that if `more` is not `NIL`, `value` *must not* exceed `MAX_INTEGER`.
|
||||
*/
|
||||
struct cons_pointer make_integer( int64_t value, struct cons_pointer more ) {
|
||||
struct cons_pointer result = NIL;
|
||||
|
|
@ -94,7 +96,13 @@ struct cons_pointer make_integer( int64_t value, struct cons_pointer more ) {
|
|||
return result;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Internal to `operate_on_integers`, do not use.
|
||||
* @param c a pointer to a cell, assumed to be an integer cell;
|
||||
* @param op a character representing the operation: expectedto be either
|
||||
* '+' or '*'; behaviour with other values is undefined.
|
||||
* \see operate_on_integers
|
||||
*/
|
||||
__int128_t cell_value( struct cons_pointer c, char op, bool is_first_cell ) {
|
||||
long int val = nilp( c ) ? 0 : pointer2cell( c ).payload.integer.value;
|
||||
long int carry = is_first_cell ? 0 : ( MAX_INTEGER + 1 );
|
||||
|
|
@ -115,8 +123,15 @@ __int128_t cell_value( struct cons_pointer c, char op, bool is_first_cell ) {
|
|||
* possibly, later, other operations. Apply the operator `op` to the
|
||||
* integer arguments `a` and `b`, and return a pointer to the result. If
|
||||
* either `a` or `b` is not an integer, returns `NIL`.
|
||||
*
|
||||
* @param a a pointer to a cell, assumed to be an integer cell;
|
||||
* @param b a pointer to a cell, assumed to be an integer cell;
|
||||
* @param op a character representing the operation: expected to be either
|
||||
* '+' or '*'; behaviour with other values is undefined.
|
||||
* \see add_integers
|
||||
* \see multiply_integers
|
||||
*/
|
||||
/* TODO: there is a significant bug here, which manifests in multiply but
|
||||
/* \todo there is a significant bug here, which manifests in multiply but
|
||||
* may not manifest in add. The value in the least significant cell ends
|
||||
* up significantly WRONG, but the value in the more significant cell
|
||||
* ends up correct. */
|
||||
|
|
@ -148,7 +163,7 @@ struct cons_pointer operate_on_integers( struct cons_pointer a,
|
|||
|
||||
switch ( op ) {
|
||||
case '*':
|
||||
rv = av * bv * ( ( carry == 0 ) ? 1 : carry );
|
||||
rv = av * ( bv + carry );
|
||||
break;
|
||||
case '+':
|
||||
rv = av + bv + carry;
|
||||
|
|
@ -170,7 +185,7 @@ struct cons_pointer operate_on_integers( struct cons_pointer a,
|
|||
if ( MAX_INTEGER >= rv ) {
|
||||
carry = 0;
|
||||
} else {
|
||||
// TODO: we're correctly detecting overflow, but not yet correctly
|
||||
// \todo we're correctly detecting overflow, but not yet correctly
|
||||
// handling it.
|
||||
carry = rv >> 60;
|
||||
debug_printf( DEBUG_ARITH,
|
||||
|
|
@ -210,8 +225,8 @@ struct cons_pointer operate_on_integers( struct cons_pointer a,
|
|||
}
|
||||
|
||||
/**
|
||||
* Return the sum of the integers pointed to by `a` and `b`. If either isn't
|
||||
* an integer, will return nil.
|
||||
* Return a pointer to an integer representing the sum of the integers
|
||||
* pointed to by `a` and `b`. If either isn't an integer, will return nil.
|
||||
*/
|
||||
struct cons_pointer add_integers( struct cons_pointer a,
|
||||
struct cons_pointer b ) {
|
||||
|
|
@ -220,8 +235,8 @@ struct cons_pointer add_integers( struct cons_pointer a,
|
|||
}
|
||||
|
||||
/**
|
||||
* Return the product of the integers pointed to by `a` and `b`. If either isn't
|
||||
* an integer, will return nil.
|
||||
* Return a pointer to an integer representing the product of the integers
|
||||
* pointed to by `a` and `b`. If either isn't an integer, will return nil.
|
||||
*/
|
||||
struct cons_pointer multiply_integers( struct cons_pointer a,
|
||||
struct cons_pointer b ) {
|
||||
|
|
@ -253,7 +268,7 @@ struct cons_pointer integer_to_string_add_digit( int digit, int digits,
|
|||
* to be looking to the next. H'mmmm.
|
||||
*/
|
||||
/*
|
||||
* TODO: this blows up when printing three-cell integers, but works fine
|
||||
* \todo this blows up when printing three-cell integers, but works fine
|
||||
* for two-cell. What's happening is that when we cross the barrier we
|
||||
* SHOULD print 2^120, but what we actually print is 2^117. H'mmm.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
/**
|
||||
/*
|
||||
* integer.h
|
||||
*
|
||||
* functions for integer cells.
|
||||
|
|
@ -13,9 +13,6 @@
|
|||
|
||||
long double numeric_value( struct cons_pointer pointer );
|
||||
|
||||
/**
|
||||
* Allocate an integer cell representing this value and return a cons pointer to it.
|
||||
*/
|
||||
struct cons_pointer make_integer( int64_t value, struct cons_pointer more );
|
||||
|
||||
struct cons_pointer add_integers( struct cons_pointer a,
|
||||
|
|
|
|||
|
|
@ -34,7 +34,9 @@ struct cons_pointer add_2( struct stack_frame *frame,
|
|||
struct cons_pointer arg1,
|
||||
struct cons_pointer arg2 );
|
||||
|
||||
|
||||
/**
|
||||
* return true if this `arg` points to a number whose value is zero.
|
||||
*/
|
||||
bool zerop( struct cons_pointer arg ) {
|
||||
bool result = false;
|
||||
struct cons_space_object cell = pointer2cell( arg );
|
||||
|
|
@ -56,7 +58,13 @@ bool zerop( struct cons_pointer arg ) {
|
|||
}
|
||||
|
||||
/**
|
||||
* TODO: cannot throw an exception out of here, which is a problem
|
||||
* Return the closest possible `binary64` representation to the value of
|
||||
* this `arg`, expected to be an integer, ratio or real, or `NAN` if `arg`
|
||||
* is not any of these.
|
||||
*
|
||||
* @arg a pointer to an integer, ratio or real.
|
||||
*
|
||||
* \todo cannot throw an exception out of here, which is a problem
|
||||
* if a ratio may legally have zero as a divisor, or something which is
|
||||
* not a number is passed in.
|
||||
*/
|
||||
|
|
@ -97,7 +105,13 @@ long double to_long_double( struct cons_pointer arg ) {
|
|||
|
||||
|
||||
/**
|
||||
* TODO: cannot throw an exception out of here, which is a problem
|
||||
* Return the closest possible `int64_t` representation to the value of
|
||||
* this `arg`, expected to be an integer, ratio or real, or `NAN` if `arg`
|
||||
* is not any of these.
|
||||
*
|
||||
* @arg a pointer to an integer, ratio or real.
|
||||
*
|
||||
* \todo cannot throw an exception out of here, which is a problem
|
||||
* if a ratio may legally have zero as a divisor, or something which is
|
||||
* not a number (or is a big number) is passed in.
|
||||
*/
|
||||
|
|
@ -106,7 +120,7 @@ int64_t to_long_int( struct cons_pointer arg ) {
|
|||
struct cons_space_object cell = pointer2cell( arg );
|
||||
switch ( cell.tag.value ) {
|
||||
case INTEGERTV:
|
||||
/* TODO: if (integerp(cell.payload.integer.more)) {
|
||||
/* \todo if (integerp(cell.payload.integer.more)) {
|
||||
* throw an exception!
|
||||
* } */
|
||||
result = cell.payload.integer.value;
|
||||
|
|
@ -123,9 +137,9 @@ int64_t to_long_int( struct cons_pointer arg ) {
|
|||
|
||||
|
||||
/**
|
||||
* return a cons_pointer indicating a number which is the sum of
|
||||
* the numbers indicated by `arg1` and `arg2`.
|
||||
*/
|
||||
* return a cons_pointer indicating a number which is the sum of
|
||||
* the numbers indicated by `arg1` and `arg2`.
|
||||
*/
|
||||
struct cons_pointer add_2( struct stack_frame *frame,
|
||||
struct cons_pointer frame_pointer,
|
||||
struct cons_pointer arg1,
|
||||
|
|
@ -222,7 +236,8 @@ struct cons_pointer add_2( struct stack_frame *frame,
|
|||
* Add an indefinite number of numbers together
|
||||
* @param env the evaluation environment - ignored;
|
||||
* @param frame the stack frame.
|
||||
* @return a pointer to an integer or real.
|
||||
* @return a pointer to an integer, ratio or real.
|
||||
* @exception if any argument is not a number, returns an exception.
|
||||
*/
|
||||
struct cons_pointer lisp_add( struct stack_frame
|
||||
*frame, struct cons_pointer frame_pointer, struct
|
||||
|
|
@ -356,7 +371,8 @@ struct cons_pointer multiply_2( struct stack_frame *frame,
|
|||
* Multiply an indefinite number of numbers together
|
||||
* @param env the evaluation environment - ignored;
|
||||
* @param frame the stack frame.
|
||||
* @return a pointer to an integer or real.
|
||||
* @return a pointer to an integer, ratio or real.
|
||||
* @exception if any argument is not a number, returns an exception.
|
||||
*/
|
||||
struct cons_pointer lisp_multiply( struct
|
||||
stack_frame
|
||||
|
|
@ -431,7 +447,7 @@ struct cons_pointer negative( struct cons_pointer frame,
|
|||
|
||||
/**
|
||||
* return a cons_pointer indicating a number which is the result of
|
||||
* subtracting the numbers indicated by `arg2` from that indicated by `arg1`,
|
||||
* subtracting the number indicated by `arg2` from that indicated by `arg1`,
|
||||
* in the context of this `frame`.
|
||||
*/
|
||||
struct cons_pointer subtract_2( struct stack_frame *frame,
|
||||
|
|
@ -526,10 +542,12 @@ struct cons_pointer subtract_2( struct stack_frame *frame,
|
|||
}
|
||||
|
||||
/**
|
||||
* Subtract one number from another.
|
||||
* Subtract one number from another. If more than two arguments are passed
|
||||
* in the frame, the additional arguments are ignored.
|
||||
* @param env the evaluation environment - ignored;
|
||||
* @param frame the stack frame.
|
||||
* @return a pointer to an integer or real.
|
||||
* @return a pointer to an integer, ratio or real.
|
||||
* @exception if either argument is not a number, returns an exception.
|
||||
*/
|
||||
struct cons_pointer lisp_subtract( struct
|
||||
stack_frame
|
||||
|
|
@ -539,10 +557,12 @@ struct cons_pointer lisp_subtract( struct
|
|||
}
|
||||
|
||||
/**
|
||||
* Divide one number by another.
|
||||
* Divide one number by another. If more than two arguments are passed
|
||||
* in the frame, the additional arguments are ignored.
|
||||
* @param env the evaluation environment - ignored;
|
||||
* @param frame the stack frame.
|
||||
* @return a pointer to an integer or real.
|
||||
* @exception if either argument is not a number, returns an exception.
|
||||
*/
|
||||
struct cons_pointer lisp_divide( struct
|
||||
stack_frame
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
/**
|
||||
/*
|
||||
* peano.h
|
||||
*
|
||||
* Basic peano arithmetic
|
||||
|
|
@ -18,7 +18,7 @@ struct cons_pointer negative( struct cons_pointer frame,
|
|||
struct cons_pointer arg );
|
||||
|
||||
/**
|
||||
* TODO: cannot throw an exception out of here, which is a problem
|
||||
* \todo cannot throw an exception out of here, which is a problem.
|
||||
* if a ratio may legally have zero as a divisor, or something which is
|
||||
* not a number is passed in.
|
||||
*/
|
||||
|
|
@ -35,7 +35,7 @@ lisp_add( struct stack_frame *frame, struct cons_pointer frame_pointer,
|
|||
struct cons_pointer env );
|
||||
|
||||
/**
|
||||
* Multiply an indefinite number of numbers together
|
||||
* Multiply an indefinite number of numbers together.
|
||||
* @param env the evaluation environment - ignored;
|
||||
* @param frame the stack frame.
|
||||
* @return a pointer to an integer or real.
|
||||
|
|
|
|||
|
|
@ -46,8 +46,8 @@ int64_t least_common_multiple( int64_t m, int64_t n ) {
|
|||
/**
|
||||
* return a cons_pointer indicating a number which is of the
|
||||
* same value as the ratio indicated by `arg`, but which may
|
||||
* be in a simplified representation. If `arg` isn't a ratio,
|
||||
* will throw exception.
|
||||
* be in a simplified representation.
|
||||
* @exception If `arg` isn't a ratio, will return an exception.
|
||||
*/
|
||||
struct cons_pointer simplify_ratio( struct cons_pointer frame_pointer,
|
||||
struct cons_pointer arg ) {
|
||||
|
|
@ -83,8 +83,9 @@ struct cons_pointer simplify_ratio( struct cons_pointer frame_pointer,
|
|||
|
||||
/**
|
||||
* return a cons_pointer indicating a number which is the sum of
|
||||
* the ratios indicated by `arg1` and `arg2`. If you pass non-ratios,
|
||||
* this is going to break horribly.
|
||||
* the ratios indicated by `arg1` and `arg2`.
|
||||
* @exception will return an exception if either `arg1` or `arg2` is not a
|
||||
* rational number.
|
||||
*/
|
||||
struct cons_pointer add_ratio_ratio( struct cons_pointer frame_pointer,
|
||||
struct cons_pointer arg1,
|
||||
|
|
@ -100,7 +101,6 @@ struct cons_pointer add_ratio_ratio( struct cons_pointer frame_pointer,
|
|||
if ( ratiop( arg1 ) && ratiop( arg2 ) ) {
|
||||
struct cons_space_object cell1 = pointer2cell( arg1 );
|
||||
struct cons_space_object cell2 = pointer2cell( arg2 );
|
||||
// TODO: to be entirely reworked for bignums. All vars must be lisp integers.
|
||||
int64_t dd1v =
|
||||
pointer2cell( cell1.payload.ratio.dividend ).payload.integer.value,
|
||||
dd2v =
|
||||
|
|
@ -160,7 +160,8 @@ struct cons_pointer add_ratio_ratio( struct cons_pointer frame_pointer,
|
|||
/**
|
||||
* return a cons_pointer indicating a number which is the sum of
|
||||
* the intger indicated by `intarg` and the ratio indicated by
|
||||
* `ratarg`. If you pass other types, this is going to break horribly.
|
||||
* `ratarg`.
|
||||
* @exception if either `intarg` or `ratarg` is not of the expected type.
|
||||
*/
|
||||
struct cons_pointer add_integer_ratio( struct cons_pointer frame_pointer,
|
||||
struct cons_pointer intarg,
|
||||
|
|
@ -190,8 +191,9 @@ struct cons_pointer add_integer_ratio( struct cons_pointer frame_pointer,
|
|||
|
||||
/**
|
||||
* return a cons_pointer to a ratio which represents the value of the ratio
|
||||
* indicated by `arg1` divided by the ratio indicated by `arg2`. If either
|
||||
* of these aren't RTIO cells, something horrid will happen and it is YOUR FAULT.
|
||||
* indicated by `arg1` divided by the ratio indicated by `arg2`.
|
||||
* @exception will return an exception if either `arg1` or `arg2` is not a
|
||||
* rational number.
|
||||
*/
|
||||
struct cons_pointer divide_ratio_ratio( struct cons_pointer frame_pointer,
|
||||
struct cons_pointer arg1,
|
||||
|
|
@ -210,8 +212,9 @@ struct cons_pointer divide_ratio_ratio( struct cons_pointer frame_pointer,
|
|||
|
||||
/**
|
||||
* return a cons_pointer indicating a number which is the product of
|
||||
* the ratios indicated by `arg1` and `arg2`. If you pass non-ratios,
|
||||
* this is going to break horribly.
|
||||
* the ratios indicated by `arg1` and `arg2`.
|
||||
* @exception will return an exception if either `arg1` or `arg2` is not a
|
||||
* rational number.
|
||||
*/
|
||||
struct cons_pointer multiply_ratio_ratio( struct cons_pointer frame_pointer, struct
|
||||
cons_pointer arg1, struct
|
||||
|
|
@ -258,7 +261,8 @@ struct cons_pointer multiply_ratio_ratio( struct cons_pointer frame_pointer, str
|
|||
/**
|
||||
* return a cons_pointer indicating a number which is the product of
|
||||
* the intger indicated by `intarg` and the ratio indicated by
|
||||
* `ratarg`. If you pass other types, this is going to break horribly.
|
||||
* `ratarg`.
|
||||
* @exception if either `intarg` or `ratarg` is not of the expected type.
|
||||
*/
|
||||
struct cons_pointer multiply_integer_ratio( struct cons_pointer frame_pointer,
|
||||
struct cons_pointer intarg,
|
||||
|
|
@ -285,8 +289,9 @@ struct cons_pointer multiply_integer_ratio( struct cons_pointer frame_pointer,
|
|||
|
||||
/**
|
||||
* return a cons_pointer indicating a number which is the difference of
|
||||
* the ratios indicated by `arg1` and `arg2`. If you pass non-ratios,
|
||||
* this is going to break horribly.
|
||||
* the ratios indicated by `arg1` and `arg2`.
|
||||
* @exception will return an exception if either `arg1` or `arg2` is not a
|
||||
* rational number.
|
||||
*/
|
||||
struct cons_pointer subtract_ratio_ratio( struct cons_pointer frame_pointer,
|
||||
struct cons_pointer arg1,
|
||||
|
|
@ -301,8 +306,10 @@ struct cons_pointer subtract_ratio_ratio( struct cons_pointer frame_pointer,
|
|||
|
||||
|
||||
/**
|
||||
* Construct a ratio frame from these two pointers, expected to be integers
|
||||
* or (later) bignums, in the context of this stack_frame.
|
||||
* Construct a ratio frame from this `dividend` and `divisor`, expected to
|
||||
* be integers, in the context of the stack_frame indicated by this
|
||||
* `frame_pointer`.
|
||||
* @exception if either `dividend` or `divisor` is not an integer.
|
||||
*/
|
||||
struct cons_pointer make_ratio( struct cons_pointer frame_pointer,
|
||||
struct cons_pointer dividend,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue