estack.h

void add_to_top (CESI ptr);

Adds a value to the expression on the top of the estack.

add_to_top adds the expression pointed to by ptr to the expression currently at the top of the estack and stores the result to the top of the estack, in place of the expression that was added to.

add1_to_top

void add1_to_top (void);

Adds 1 to the top of the estack.

add1_to_top adds 1 (or 1.0) to the value on the top of the estack. This routine basically calls add_to_top with "1" as the pointed-to value.

all_tail

short all_tail (CESI_Callback_t f, ESI start_ptr);

Checks whether all elements in the list have some property.

all_tail is similar to map_tail, but callback function f is not void. It needs to return a Boolean value (TRUE or FALSE). If f returns FALSE, any further processing of the list tail will be stopped, even if END_TAG is not reached yet. The result of all_tail is the last value returned from f. In other words, it returns TRUE if and only if the callback function f returns TRUE for each expression in the tail of expressions indexed by element_ptr.

all_tail is very useful to check whether all elements of a list possess some property. Suppose that you defined the following function which checks whether an entry on the expression stack is a positive integer:

short is_positive_integer (ESI ptr)
{
  return (*ptr == POSINT_TAG);
}

and suppose that start_ptr points to the first element of the list (one byte below LIST_TAG). Then, you can use the following call to check whether all elements of the lists are positive integers:

are_all_positive_integers = all_tail (is_positive_integer, start_ptr);

and_onto_top

void and_onto_top (CESI ptr);

Logical ANDs the expression onto the estack.

and_onto_top replaces the top expression on the estack with the logical AND of itself and ptr.

any_tail

short any_tail (CESI_Callback_t f, ESI start_ptr);

Checks whether any element in the list has some property.

any_tail is similar like all_tail, except further processing of the list will be stopped if f returns TRUE instead of FALSE. In other words, it returns TRUE if and only if the callback function f returns TRUE for at least one expression in the tail of expressions indexed by element_ptr. any_tail is very useful to check whether any element of a list possesses some property. Assuming the same assumptions as in the example given with all_tail, the following call will check whether any element of the list is a positive integer:

is_any_positive_integer = any_tail (is_positive_integer, start_ptr);

are_expressions_identical

short are_expressions_identical (CESI ptr1, CESI ptr2);

Checks whether two expressions are identical.

are_expressions_identical returns TRUE if expressions pointed to by ptr1 and ptr2 are syntactically identical, else returns FALSE. At the moment, I am not exactly sure what is the criteria for equivalence. I only know that a+b and b+a are not identical for example. And, floats are never identical to rational numbers. So far, I only know that this function surely returns TRUE when two expressions are absolutely identical. But, if this is the only case of equivalence, this routine should be very simple. But it is not. It is very complicated and recursive, so I am really not sure which pairs of expressions may be treated as "identical". Any additional info is welcomed.

can_be_approxed

short can_be_approxed (CESI ptr, short Complex);

Checks whether an expression can be approximated to a number.

can_be_approxed returns TRUE if the expression pointed to by ptr can be approximated to a number (including transfinite ones) or a list of numbers (such expression are for example 'ln(2+sin(1))/5', '1/0' or 'x^2+1-x*x'), else returns FALSE. Complex is a Boolean parameter: if it is TRUE, complex results will be allowed, but if it is FALSE, complex results will be treated as "can not be approxed".

Note: can_be_approxed performs much detailed investigation than functions likely_approx_to_number and likely_approx_to_complex_number.

check_estack_size

void check_estack_size (unsigned short Size);

Checks if there is enough room on the expression stack.

check_estack_size checks if there is enough room to push Size bytes to the expression stack. If there is not enough space, it tries to enlarge the stack (using HeapRealloc) to make additional space. It throws an error if the requirement cannot be satisfied. Note that all "push_..." functions call this routine, so all of them may throw an error if there is not enough memory.

compare_complex_magnitudes

short compare_complex_magnitudes (CESI ptr1, CESI ptr2);

Compares magnitudes of two complex number entries on the expression stack.

compare_complex_magnitudes compares two complex number entries (which may be real also) on the expression stack pointed to by ptr1 and ptr2, and returns a value which is

< 0 if the magnitude of the number pointed to by ptr1 is less than the magnitude of the number pointed to by ptr2
== 0 if the magnitude of the number pointed to by ptr1 is the same as the magnitude of the number pointed to by ptr2
> 0 if the magnitude of the number pointed to by ptr1 is greater than the magnitude of the number pointed to by ptr2

compare_expressions

short compare_expressions (CESI ptr1, CESI ptr2);

Compares two expressions.

compare_expressions returns 0 if two expressions pointed to by ptr1 and ptr2 are equal in the sense that they have the same structure, variables, function names, and numbers that compare equal. A float and a rational number compare equal if converting the rational number to a float produces an identical number. If the expressions are not, it returns a non-zero value which may be positive or negative (more precise, 1 or -1). Positive result means that the expression pointed to by ptr1 is "more main" that the expression pointed to by ptr2, and negative result means "less main". Principally, variables are more main than symbolic constants such as pi, which are more main than numbers. In expressions such as 'expand(...,var)' or 'Integral(...,var)', a variable var is "most main". Otherwise, the 26 Roman one-letter variables order r>>s>>...>>z>>a>>b>>...>>q ('>>' means "more main"), which order more main than all other variables, which order alphabetically. Functions and operators are typically ordered by recursively comparing their first arguments, with ties broken by comparing their second arguments, etc. then finally comparing the operators or functions, if necessary. For example:

-2.0 and -2 are equal;
-2.0 is less main than -1;
pi is more main than 4;
x is more main than 4;
x is less main than r;
x is more main than ln(y);
x is less main than ln(x).

Note: Both expressions should be in internal canonic form (see push_internal_simplify), else this function may not work as expected.

compare_Floats

long compare_Floats (CESI ptr1, CESI ptr2);

Compares two floating point entries on the expression stack.

compare_Floats compares two floating point entries on the expression stack pointed to by ptr1 and ptr2, and returns a value which is

< 0 if the number pointed to by ptr1 is less than the number pointed to by ptr2
== 0 if the number pointed to by ptr1 is the same as the number pointed to by ptr2
> 0 if the number pointed to by ptr1 is greater than the number pointed to by ptr2

So, this function is similar like fcmp, except the arguments are different (fcmp uses floating point arguments, and compare_Floats uses pointers to floating point entries on the expression stack).

delete_between

void delete_between (ESI ptr1, ESI ptr2);

Deletes a sequence of bytes from the expression stack.

delete_between deletes a sequence of bytes between ptr1 and ptr2 (more precise, starting at ptr1+1 and ending at ptr2) from the expression stack. It does this by moving the memory from ptr2+1 to top_estack downwards (using memmove) and adjusting top_estack. This routine assumes that ptr1 and ptr2 really point to parts of the expression stack and that ptr2 is above ptr1, otherwise the result is unpredictable.

delete_expression

void delete_expression (ESI ptr);

Deletes an expression from the expression stack.

delete_expression deletes an entry on the expression stack pointed to by ptr (it needs to point to the entry tag) from the stack. The entry need not be a simple entity; it may be a complex symbolic expression too. This is achieved by calling next_expression_index and delete_between.

deleted_between

unsigned short deleted_between (ESI ptr1, ESI ptr2);

Deletes a sequence of bytes from the expression stack.

deleted_between acts like delete_between, but it also returns a number of deleted bytes. Note that delete_between calls memmove for moving memory after ptr2, but deleted_between uses an embedded loop sequence for the same task. I don't know why these two routines use different methods: as I can see, the final effect is the same. Maybe I am wrong?

deleted_expression

unsigned short deleted_expression (ESI ptr);

Deletes an expression from the expression stack.

deleted_expression acts like delete_expression, but it also returns a number of deleted bytes. It calls deleted_between instead of delete_between.

did_push_cnvrt_Float_to_integer

short did_push_cnvrt_Float_to_integer (CESI ptr);

Pushes a floating point entry converted to an integer, but only if it is an exact whole number.

did_push_cnvrt_Float_to_integer is a subroutine used in push_cnvrt_integer_if_whole_nmb. It assumes that ptr points to a floating point entry. If it is a whole number (including big numbers too), did_push_cnvrt_Float_to_integer pushes the number converted to a tagged integer to the expression stack, and returns TRUE, otherwise it does nothing and returns FALSE.

display_statements

HANDLE display_statements (CESI ptr, unsigned short Newlines, unsigned short FullPrec);

Converts tokenized expressions or TI-Basic statements to the printable form.

display_statements converts the expression (or a group of tokenized TI-Basic statements) pointed to by ptr from RPN form to the standard printable ("algebraic") form, and returns a handle to the memory block where the converted string is stored (you don't need to allocate anything by yourself, this function will do it instead; note that this routine may cause heap compression). It will return H_NULL if memory is full. Newline is a Boolean flag: when it is nonzero, all newline characters will be replaced with ':', otherwise they will remain intact. FullPrec is also a Boolean flag: when it is non-zero, all floating point values will be converted using the maximal precision (14 digits), else current precision settings (from TI-Basic MODE dialog) will be used. Here is an illustrative example for usage of this command (take a look at the "Integrate" example as well):

push_parse_text ("expand((x+1)(x+2)(x+3))");
NG_rationalESI (top_estack);
handle = display_statements (top_estack, 1, 1);
printf_xy (0, 40, "%s", HeapDeref (handle));
HeapFree (handle);

See push_parse_text, NG_rationalESI, HeapDeref and HeapFree to understand how this example works.

Note: Handles returned by display_statements aren't locked so any heap compression will move the block associated with the handle. Therefore it is safer to lock them using HLock and HeapUnlock than to just dereference them using HeapDeref.

display_statements will always convert expressions into the "canonic printing (external) form". For example, both x*3 and 3*x will be displayed as 3*x, x*y^(-1) will be displayed as x/y etc.

Note: Although display_statements is very similar to Parse1DExpr and both of them may usually be used for the same purposes, display_statements is used in TIOS for printing TI-Basic statements (from programs) and for the detokenization (in NG_RPNToText), and Parse1DExpr is used for printing expressions.

estack_number_to_Float

float estack_number_to_Float (CESI ptr);

Converts entry on the expression stack to floating point number.

estack_number_to_Float converts an entry on the expression stack pointed to by ptr (it needs to point to the entry tag) to a floating point value and returns the result. Note that the entry need not be represented by FLOAT_TAG: it also may be represented by an integer, or by a fraction. This function does not remove the entry from the stack.

Note: estack_number_to_Float will throw an error if the entry on the stack is not a floating point number, a fraction or an integer, so you will need to use ER_catch to catch eventual errors.

estack_to_short

short estack_to_short (CESI ptr, short *value_ptr);

Converts entry on the expression stack to signed short integer.

estack_to_short converts an entry on the expression stack pointed to by ptr (it needs to point to the entry tag) to a signed short integer and stores the result in the location pointed to by value_ptr. Note that the entry need not be represented by POSINT_TAG or NEGINT_TAG: it also may be represented by FLOAT_TAG for example, but the value itself needs to be a whole number. This function does not remove the entry from the stack.

estack_to_short returns 1 if the conversion was successful, 0 in the case of overflow (in this case the stored result will be -32768 or 32767 depending of the direction of the overflow), and -1 if the entry can not be represented as a whole number (in this case the result is undefined).

estack_to_ushort

short estack_to_ushort (CESI ptr, unsigned short *value_ptr);

Converts entry on the expression stack to unsigned short integer.

estack_to_ushort converts an entry on the expression stack pointed to by ptr (it needs to point to the entry tag) to a unsigned short integer and stores the result in the location pointed to by value_ptr. Note that the entry need not be represented by POSINT_TAG or NEGINT_TAG: it also may be represented by FLOAT_TAG for example, but the value itself needs to be a whole number. This function does not remove the entry from the stack.

estack_to_short returns 1 if the conversion was successful, 0 in the case of overflow (in this case the stored result will be 0 or 65535 depending of the direction of the overflow), and -1 if the entry can not be represented as a whole number (in this case the result is undefined).

ESTACK

#define ESTACK(idx) (*(idx))

Reads the expression stack at a specific index.

The ESTACK macro can be used to read the expression stack at the index idx. It simply dereferences idx, since the ESI and CESI types are in fact pointers to quantums of type ESQ.

factor_base_index

ESI factor_base_index (CESI ptr);

Gets the index of the base of an expression.

If ptr points to the POW_TAG, which is a case when it points to an expression of form base ^ exponent factor_base_index returns the pointer to base. If ptr does not point to the POW_TAG, factor_base_index returns ptr (i.e. the pointer to the expression itself).

factor_exponent_index

ESI factor_exponent_index (CESI ptr);

Gets the index of the exponent of an expression.

If ptr points to the POW_TAG, which is a case when it points to an expression of form base ^ exponent factor_exponent_index returns the pointer to exponent. If ptr does not point to the POW_TAG, factor_exponent_index returns a pointer to a simple expression which consists only of the number 1 (floating point or integer, depending on whether the approximation mode is active or not).

gcd_exact_whole_Floats

float gcd_exact_whole_Floats (CESI ptr1, CESI ptr2);

Finds the greatest common divisor of two floating point entries.

gcd_exact_whole_Floats finds the greatest common divisor of two floating point entries pointed to by ptr1 and ptr2 and returns the result (the result is a garbage if ptr1 or ptr2 doesn't point to floating point entries).

Note: Although the name of the function suggests that both entries need to be whole numbers, this is not true. This function, in fact, returns "generalized" GCD of two numbers x and y which is defined as the greatest number z which has a property that both x/z and y/z are whole numbers.

get_key_ptr

char *get_key_ptr (ESQ Tag1, ESQ Tag2);

Converts a tag code to a tag name.

get_key_ptr returns a static pointer to the string which represents the name of the tag Tag1. Tag2 is used only if Tag1 is an extended tag (i.e. EXT_TAG, EXT_INSTR_TAG or EXT_SYSTEM_TAG) which can't be fully represented using only one byte.

If the tag corresponds to a function, AMS 1.xx does not append '(' at the end of the string, but AMS 2.xx does. Thus, anyone who intends to use this function for function tokens should use extra code to handle both cases.

GetValue

long GetValue (CESI ptr, long low, long high);

Converts entry on the expression stack to short integer and checks whether it is in a given range.

GetValue converts an entry on the expression stack pointed to by ptr (it needs to point on the entry tag) to a short integer value using estack_to_short or estack_to_ushort, depending on the sign of low. Then, a "Domain Error" is thrown if the value is smaller than low or greater than high, otherwise the value will be returned as the result of the function. It will also throw a "Data type" error if the entry can not be represented as an integer.

HToESI

ESI HToESI (HANDLE Handle);

Converts a handle to an expression stack index.

HToESI is a simple but very useful routine. It returns a pointer to the last byte of the MULTI_EXPR structure referenced by Handle. Therefore it allows for the use of TIOS variables as input data in expression stack routines. Assuming that Handle is a handle of a TIOS variable which contains an expression, HToESI will return a pointer to the tag of the expression contained in the variable. Such a pointer may be used in any routine which needs an argument of type CESI, like NG_approxESI, etc. (except in functions which manipulate the actual memory space on the expression stack, like delete_between). In fact, HToESI simply dereferences Handle and adds the size plus 1 to the address. It also may be used to determine the type of a TIOS variable, because after execution the result points to the data type tag of the variable data.

Note: If the handle is not locked, HToESI must be called again after a heap compression since the block of memory associated with the handle may have moved.

im_index

ESI im_index (CESI ptr);

Gets the index of the imaginary part of an expression.

If ptr points to the COMPLEX_TAG (i.e. if the expression is complex), im_index returns the pointer to the imaginary part of the expression. If ptr does not point to the COMPLEX_TAG (i.e. if the expression is real), im_index returns a pointer to a simple zero expression, i.e. expression which consists only of the number 0 (floating point or integer, depending on whether the approximation mode is active or not).

Note: The expression should be in internal canonic form (see push_internal_simplify), else this function is not reliable.

index_below_display_expression_aux

ESI index_below_display_expression_aux (CESI ptr);

Main routine for detokenizing.

index_below_display_expression_aux is main (recursive) routine for detokenizing. As it is just an auxiliary routine used in display_statements and Parse1DExpr, it shouldn't need to be used directly.

index_main_var

ESI index_main_var (CESI ptr);

Searches an expression for a first encountered variable.

index_main_var returns the index of the first encountered variable in the expression pointed to by ptr. More precise, it repeatedly decreases value of ptr by one until the tag of a variable, a number or a symbolic constant (like pi) is reached. As expressions are usually organized in "internal canonic" form (see notes given with description of numeric_factor_index) in which all constants are always "below" variables on the stack, a variable will always be reached before any constant, except if there are not any variables in the expression (in this case, a pointer to a constant is returned). Obviously, this function is not reliable if the expression is not in the internal canonic form (see push_internal_simplify).

index_numeric_term

ESI index_numeric_term (CESI ptr);

Searches terms in the expression for a numeric term.

If ptr points to the ADD_TAG, which is a case when it points to an expression of form term1 + term2 + ... (i.e. if the expression is a sum of simpler terms), index_numeric_term returns the pointer to the eventual numeric term in the expression. If the expression is a number, index_numeric_term returns ptr (i.e. the pointer to the expression itself). If ptr does not point to the ADD_TAG (i.e. if the expression is not a sum of simpler terms), or if there are not any numeric terms in the expression, index_numeric_factor returns a pointer to a simple expression which consists only of the number 0 (floating point or integer, depending on whether the approximation mode is active or not).

Note: This function is not implemented to be very universal. TIOS always "reorganizes" expressions on such way that numeric terms are at the beginning of the expression (for example, x+3 will be reorganized into 3+x, although it will be displayed just reversed, i.e. as x+3), and this function assumes that the expression is organized on such way. In other words, it must be in internal canonic form (such expressions always have at most one term with a numeric tag, in which case it is the deepest term). Fortunately, all expressions in argument are always in internal canonic form. However, this is not true after push_parse_text function, nor after an evaluation using NG_rationalESI or NG_approxESI. In other words, results of these commands are not always "correctly" organized. To force converting an expression to the internal canonic form, always call push_internal_simplify after usage of any of the functions mentioned above.

index_of_lead_base_of_lead_term

ESI index_of_lead_base_of_lead_term (CESI ptr);

Gets the index of the base of the lead term of an expression.

index_of_lead_base_of_lead_term first calls lead_term_index, then apply lead_base_index on the result. So, it returns the pointer to the base of the lead factor of the first term of the expression pointed to by ptr.

integer_non_unknown

short integer_non_unknown (CESI ptr);

Tests if an expression is an integer.

Returns 1 if the expression pointed to by ptr is an integer or floating-point value; returns -1 for constants like p or e. Returns 0 for everything else - this includes expressions like ln(2), 2p, or Ö(2).

is0

short is0 (CESI ptr);

Tests if an expression is equal to 0.

Returns TRUE if the expression pointed to by ptr is equal to zero (integer or floating point).

is1

short is1 (CESI ptr);

Tests if an expression is equal to 1.

Returns TRUE if the expression pointed to by ptr is equal to one (integer or floating point).

is_advanced_tag

short is_advanced_tag (ESQ Tag);

Checks whether a tag is an advanced tag.

is_advanced_tag returns TRUE if a byte Tag is an advanced tag, otherwise it returns FALSE. Advanced tags are all tags which do not represent a variable, a number (integer, fraction or float) or an expression which consists only of simple operations "+", "-", "*", "/" and "^" (including element-by-element versions "+.", "-.", "*.", "/." and "^.").

is_antisymmetric

short is_antisymmetric (CESI expr_ptr, CESI var_ptr);

Checks for a antisymmetry.

is_antisymmetric returns TRUE if the expression pointed to by expr_ptr is such that it changes the sign but keeps the same magnitude when the variable pointed to by var_ptr changes it sign, otherwise it returns FALSE.

is_complex0

short is_complex0 (CESI ptr);

Checks whether an expression is reducible to zero.

is_complex0 returns TRUE if the expression pointed to by ptr is a zero (signed, unsigned, or even complex), otherwise it returns FALSE.

Note: The information about this routine in releases of TIGCCLIB before 2.3 was wrong.

is_complex_number

short is_complex_number (CESI ptr);

Checks whether an expression is a number.

is_complex_number returns TRUE if the expression (in RPN form, of course) pointed to by ptr is a "number" (integer, rational, floating point, or complex, but not irrational), otherwise it returns FALSE. Note that 'sqrt(2)' is not a "number" in this convention. A complex number is a "number" if both real and imaginary parts are "numbers" in a sense of the convention given above.

Note: The information about this routine in releases of TIGCCLIB before 2.3 was wrong.

is_constant

short is_constant (CESI ptr);

Checks whether an expression is constant.

is_constant returns TRUE if the expression pointed to by ptr does not rely on any variables (initialized, built-in, but not constants like p), otherwise it returns FALSE.

is_Float_exact_whole_number

short is_Float_exact_whole_number (CESI ptr);

Checks whether a floating point entry is an exact whole number.

is_Float_exact_whole_number returns TRUE if the floating point entry pointed to by ptr is an exact whole number whose magnitude is less than the smallest whole number that is not represented exactly (1e15), otherwise it returns FALSE.

is_free_of_tag

short is_free_of_tag (CESI ptr, ESQ Tag);

Checks whether an expression is free of a particular tag.

is_free_of_tag is a recursive function which returns TRUE if the expression structure pointed to by ptr is free of tag Tag, otherwise it returns FALSE.

is_independent_of_de_seq_vars

short is_independent_of_de_seq_vars (CESI ptr);

Checks whether an expression is independent of differential equation and sequence variables.

is_independent_of_de_seq_vars returns TRUE if the expression pointed to by expr_ptr is independent of system variables which are used for differential equation and sequence graphing (i.e. variables u1-u99 and y1'-y99'), otherwise it returns FALSE.

is_independent_of_elements

short is_independent_of_elements (CESI expr_ptr, CESI varlist_ptr);

Checks whether an expression is independent of the elements of a list.

is_independent_of_elements is very similar to is_independent_of_tail. Assuming that varlist_ptr points to the list of variables or expressions (more precise, to the LIST_TAG of such list), is_independent_of_elements returns TRUE if the expression pointed to by expr_ptr is independent of all variables from the list pointed to by varlist_ptr, otherwise it returns FALSE. More precisely,

is_independent_of_elements (expr_ptr, varlist_ptr)

is the same as

is_independent_of_tail (expr_ptr, varlist_ptr - 1)

is_independent_of_tail

short is_independent_of_tail (CESI expr_ptr, CESI start_ptr);

Checks whether an expression is independent of a sequence of variables (or expressions).

is_independent_of_tail returns TRUE if the expression pointed to by expr_ptr is independent of all entries on the expression stack stored below start_ptr up to END_TAG tag, otherwise it returns FALSE.

is_independent_of

short is_independent_of (CESI expr_ptr, CESI var_ptr);

Checks whether an expression is independent of a variable (or expression).

is_independent_of returns TRUE if the expression pointed to by expr_ptr is independent of the variable pointed to by var_ptr, else returns FALSE. Although var_ptr may point to something which is not a variable, the independence of the "expression" is not well defined, so avoid such situations until more information about what such "independence" means (TI says that this means "syntactical independence", but this is not well defined either).

Note: This routine (and all other "independence" routines also) is not reliable if expressions are not in internal canonic form (see push_internal_simplify).

is_matrix

short is_matrix (CESI ptr);

Checks whether an expression is a matrix.

is_matrix returns TRUE if the expression pointed to by ptr is a matrix (i.e. a list which consists of equally sized lists), otherwise it returns FALSE.

is_minus1

short is_minus1 (CESI ptr);

Tests if an expression is equal to -1.

Returns TRUE if the expression pointed to by ptr is equal to negative one (integer or floating point).

is_monomial_in_kernel

short is_monomial_in_kernel (CESI ptr);

Checks whether an expression is a monomial in kernel.

is_monomial_in_kernel returns TRUE if the expression pointed to by ptr is a monomial in kernel, i.e. if it is a monomial function of kernels, where "kernel" means any irrational subexpression, else returns FALSE. For example, 'sin(x)*ln(y)' is not monomial (in respect to 'x' and 'y'), but it is monomial in kernel (in respect to 'sin(x)' and 'ln(y)').

is_monomial

short is_monomial (CESI ptr);

Checks whether an expression is a monomial.

is_monomial returns TRUE if the expression pointed to by ptr is a monomial expression, otherwise it returns FALSE. For example, the expression 'x*y^3' is a monomial, and x+y*z' or 'ln(x)' are not.

is_narrowly_independent_of

short is_narrowly_independent_of (CESI expr_ptr, CESI var_ptr);

Checks whether an expression is narrowly independent of a variable (???).

is_narrowly_independent_of returns TRUE if the expression pointed to by expr_ptr is narrowly independent of the variable pointed to by var_ptr, otherwise it returns FALSE. I am not sure what "narrowly independent" really means, and what the difference between this function and is_independent_of is.

is_negative

short is_negative (CESI ptr);

Tests if an expression is less than 0.

Returns TRUE if the expression pointed to by ptr is known to be negative, FALSE otherwise.

is_never0

short is_never0 (CESI ptr);

Tests if an expression is never 0.

Returns TRUE if the expression pointed to by ptr cannot be equal to zero.

is_nonnegative

short is_nonnegative (CESI ptr);

Tests if an expression is >= 0.

Returns TRUE if the expression pointed to by ptr is known to be positive or zero, FALSE otherwise.

is_nonpositive

short is_nonpositive (CESI ptr);

Tests if an expression is <= 0.

Returns TRUE if the expression pointed to by ptr is known to be negative or zero, FALSE otherwise.

is_polynomial_in_var_or_kern

short is_polynomial_in_var_or_kern (CESI test, CESI var_or_kern);

Checks if an expression is a polynomial with respect to another expression.

is_polynomial_in_var_or_kern returns TRUE if the expression pointed to by test is a polynomial with respect to the expression var_or_kern, otherwise it returns FALSE. The definition of "polynomial with respect to" is more complicated when dealing with expressions in var_or_kern. For example, "x+sin(x)" is polynomial with respect to "sin(x)" but not to "x". Interestingly, when testing with respect to "sin(x)", "x" seems to be treated like a constant.

is_positive

short is_positive (CESI ptr);

Tests if an expression is greater than 0.

Returns TRUE if the expression pointed to by ptr is known to be positive (not zero), FALSE otherwise.

is_square_matrix

short is_square_matrix (CESI ptr);

Checks whether an expression is a square matrix.

is_square_matrix returns TRUE if the expression pointed to by ptr is a square matrix, otherwise it returns FALSE.

is_symmetric

short is_symmetric (CESI expr_ptr, CESI var_ptr);

Checks for symmetry.

is_symmetric returns TRUE if the expression pointed to by expr_ptr is such that it remains the same when the variable pointed to by var_ptr changes its sign, otherwise it returns FALSE.

is_tail_independent_of

short is_tail_independent_of (CESI start_ptr, CESI var_ptr);

Checks whether a sequence of expressions is independent of a variable (or expression).

is_tail_independent_of returns TRUE if all expressions on the expression stack which are stored below start_ptr up to END_TAG are independent of the variable pointed to by var_ptr, otherwise it returns FALSE.

is_totally_polynomial

short is_totally_polynomial (CESI ptr);

Checks if an expression is polynomial in all variables.

is_totally_polynomial returns TRUE if the expression pointed to by ptr is polynomial with respect to all variables - that is, consists only of variables raised to positive constant powers (with coefficients) and multiplied or added together. Otherwise it returns FALSE.

is_valid_smap_aggregate

short is_valid_smap_aggregate (CESI ptr);

Checks whether an expression is a valid aggregate type.

is_valid_smap_aggregate returns TRUE if the expression pointed to by ptr is a valid aggregate type (i.e. list or valid matrix), otherwise it returns FALSE. This is not a simple check whether a tag pointed to by ptr is LIST_TAG. For example, list which consists of lists which are not equally sized (like {{1,2,3},{4,5}}) are not valid. Also, matrices whose elements are list or matrices are also not valid aggregate types.

is_variable

short is_variable (CESI ptr);

Checks if the expression is a variable.

is_variable returns TRUE if the expression is a variable and FALSE if it is not.

is_whole_number

short is_whole_number (CESI ptr);

Tests if an expression is a whole number.

Returns TRUE if the expression pointed to by ptr is a whole number (it can be a floating-point value).

last_element_index

ESI last_element_index (CESI ptr);

Searches for the last expression in the list.

last_element_index calls next_expression_index in a loop starting from ptr until END_TAG is reached, then returns the pointer to the last encountered expression before END_TAG. So, assuming that ptr points to a member of the list (including argument lists too), last_element_index will return the pointer to the last element of the list.

lead_base_index

ESI lead_base_index (CESI ptr);

Gets the index of the base of the lead factor of an expression.

lead_base_index first calls lead_factor_index, then applies factor_base_index to the result. So, it returns the pointer to the base of the lead factor (i.e. the lead base) of the expression pointed to by ptr.

lead_exponent_index

ESI lead_exponent_index (CESI ptr);

Gets the index of the exponent of the lead factor of an expression.

lead_exponent_index first calls lead_factor_index, then applies factor_exponent_index to the result. So, it returns the pointer to the exponent of the lead factor (i.e. the lead exponent) of the expression pointed to by ptr.

lead_factor_index

ESI lead_factor_index (CESI ptr);

Gets the index of the lead factor of an expression.

If ptr points to the MUL_TAG, which is the case when it points to an expression of form factor1 * factor2 * ... (i.e. if the expression is a product of simpler factors), lead_factor_index returns the pointer to factor1 (i.e. to the lead factor). If ptr does not point to the MUL_TAG (i.e. if the expression is not a product of simpler factors), lead_factor_index returns ptr (i.e. the pointer to the expression itself).

Note: Expressions in internal canonic form have the most main factor shallowest, with less main factors deeper (see compare_expressions for more info about "main" ordering). Also, the lead factor of an internally-simplified product is never a product. For example, lead factor of '(3*x^2)*y' converted into canonic form is 'x^2'. Internally-simplified numeric denominator factors are combined with numeric numerator factors into a fractional numeric factor. Non-numeric denominator factors are internally simplified to be merged with numerator factors as negative powers. For example, the lead factor of '2/x' converted into canonic form is 'x^-1'. A factor having a sum as its base orders shallower than a factor having the sum�s main variable as its base. For example, the lead factor of '(x+1)^-2*x^3' converted into canonic form is '(x+1)^-2'. See push_internal_simplify for more info about how to convert an expression into the internal canonic form.

lead_term_index

ESI lead_term_index (CESI ptr);

Gets the index of the lead term of an expression.

If ptr points to the ADD_TAG, which is a case when it points to an expression of form term1 + term2 + ... (i.e. if the expression is a sum of simpler terms), lead_term_index returns the pointer to term1 (i.e. to the lead term). If ptr does not point to the ADD_TAG (i.e. if the expression is not a sum of simpler terms), lead_term_index returns ptr (i.e. the pointer to the expression itself).

Note: Expressions in internal canonic form have the most main term shallowest, with less main terms deeper (see compare_expressions about more info about "main" ordering). Also, the lead term of an internally-simplified sum is never a sum. For example, the lead term of '(2+x)+y' converted to canonic form is 'x'. By default, similar powers of the main variable are collected in internal canonic forms. For example, the lead term of 'x^2*y+x^2+5' converted to canonic form is 'x^2*(y+1)'. See push_internal_simplify for more info about how to convert an expression into the internal canonic form.

likely_approx_to_complex_number

short likely_approx_to_complex_number (CESI ptr);

Checks if it is likely that an expression can be approxed to a complex number.

likely_approx_to_complex_number is very similar to likely_approx_to_number, except that it checks for the possibility of approximation to numbers which need not be real numbers.

likely_approx_to_number

short likely_approx_to_number (CESI ptr);

Checks is it likely that an expression can be approxed to a real number.

If likely_approx_to_number returned TRUE, it is sure that the expression pointed to by ptr can be approxed to a real number, but returning FALSE does not mean that the approximation is not possible: it only means that the approximation to a number is not obvious. For example, it is obvious that expression 'ln(2+sin(1))/5' can be approxed to a number, but this is not so obvious for expression 'x^2+1-x*x', because it contains a symbolic variable name. See can_be_approxed for a more detailed investigation of possibility of approximation.

main_gen_var_index

ESI main_gen_var_index (CESI ptr);

Searches an expression for a generalized variable.

main_gen_var_index is a variant of index_main_var, but it searches for a "generalized variable", which may also be a subexpression. For example, if the expression is 'sin(x)+y', index_main_var will return a pointer to 'x', but main_gen_var_index will return a pointer to 'sin(x)'. Generalized variable can be an ordinary variable, the base of a noninteger power, or a kernel (like 'sin(x)'), meaning any other irrational subexpression.

More precise, main_gen_var_index skips all ADD_TAG, MUL_TAG and POW_TAG tags, then stops at the first tag which is not equal to some of them. In addition to this, if the tag is POW_TAG, function next_expression_index will be called, to get access to the base of the power (note that "powers" cannot be "reorganized" on such way that constants are always in front of variables, because '2^x' and 'x^2' are not the same expression). This implies that "main generalized variable" of a sum, a product or an integer power is equal to the main generalized variable of a lead term, a lead factor or a base respectively. Otherwise, main generalized variable is the expression itself. For example, main "generalized variables" of expressions 'sin(x)^2*y+ln(z)', '3^(1/5)+2' and '(x+y)^(1/2)+x' are 'sin(x)', '3' and 'x+y' respectively.

map_tail_Int

short map_tail_Int (ESI_Callback_Int_t f, ESI start_ptr, short n);

Applies an extended function to all elements in the list.

map_tail_Int is very similar to map_tail, except callback function f has one additional parameter n. Each time f is called, the parameter n passed to map_tail_Int is passed to f. Also, the callback function is not void but returns a Boolean value (TRUE or FALSE). The result of map_tail_Int is the logical OR of all the values returned by f.

map_tail

void map_tail (ESI_Callback_t f, ESI start_ptr);

Applies a function to all elements in the list.

map_tail first pushes END_TAG on the expression stack, then calls callback function f for every expression on the expression stack (in reversed order), starting from the expression pointed to by start_ptr until END_TAG is reached. Each time f is called, a pointer to the actual expression is passed to it. This function is very useful if you want to apply some operation on all elements of the list (then start_ptr need to point to the first element of the list). If the callback function does not push anything on the stack, the END_TAG pushed by map_tail should probably be deleted.

Note: map_tail calls next_expression_index to step from one expression to another.

map_unary_over_comparison

void map_unary_over_comparison (ESI_Callback_t f, ESI cmptag_ptr);

Calls callback function for both comparison terms and pushes the comparison tag.

map_unary_over_comparison assumes that cmptag_ptr points to a comparison tag. It calls the callback function f twice, passing to it pointers to both comparison terms, i.e. the two expressions below the comparison tag (the callback function should push something to the expression stack). The callback function is applied first to the deeper argument on the stack, then to the shallower argument. Finally, map_unary_over_comparison will push the tag pointed to by cmptag_ptr (one byte) to the expression stack. This function is useful to perform some transformations on both sides of a comparison (e.g. to transform 'n<5' into 'n!<120'). Beware that squaring of both sides of an inequality can cause loss of solutions, and squaring both sides of an equation may introduce spurious solutions!

min_quantum

ESQ min_quantum (ESQ Tag1, ESQ Tag2);

Finds smaller of two tags.

min_quantum returns Tag1 if it is smaller than Tag2, else returns Tag2.

move_between_to_top

void move_between_to_top (ESI ptr1, ESI ptr2);

Moves a sequence of bytes to the top of the expression stack.

move_between_to_top moves a sequence of bytes between ptr1 and ptr2 (more precise, starting at ptr1+1 and ending at ptr2) to the top of the expression stack. It acts like a combination of push_between and delete_between (in fact, it is). This routine assumes that ptr1 and ptr2 really point to parts of the expression stack and that ptr2 is above ptr1, otherwise the result is unpredictable.

moved_between_to_top

unsigned short moved_between_to_top (ESI ptr1, ESI ptr2);

Moves a sequence of bytes to the top of the expression stack.

moved_between_to_top acts like move_between_to_top, but it also returns a number of moved bytes. It calls deleted_between instead of delete_between.

negate_top

void negate_top (void);

Negates the top of the estack.

negate_top changes the sign of the expression on the top of the estack.

next_expression_index

ESI next_expression_index (CESI ptr);

Finds the next entry on the expression stack.

Assuming that ptr points to an expression entry on the expression stack, next_expression_index returns the pointer which points to an expression which is located just below the expression pointed to by ptr. So, by successive calls to next_expression_index starting from top_estack, you can locate all expressions on the stack. This command will throw an error if ptr points to the END_TAG, so be careful.

Note: next_expression_index calls index_after_match_endtag for TI-Basic functions and program tags, so that inline functions are counted as entire expressions rather than of their components.

NG_approxESI

void NG_approxESI (CESI ptr);

Evaluates an expression in "APPROX" mode.

NG_approxESI executes the entry on the expression stack pointed to by ptr (it needs to point to the entry tag) in "APPROX" mode, then pushes the result (i.e. a new expression) on the top of the expression stack. The pushed result is NOT in internal canonic form (if necessary, do push_internal_simplify to force conversion to the internal canonic form). The following example illustrates this very powerful command:

push_parse_text ("sin(1.3)+log(2)/7");
NG_approxESI (top_estack);
printf_xy (0, 50, "%f", estack_number_to_Float (top_estack));

See push_parse_text and estack_number_to_Float to understand how this example works.

Note: The expression must not contain TI-Basic statements. For executing TI-Basic statements, use NG_execute. Also, this command may cause expansion of the expression stack or heap compression, and may throw various errors is something is wrong.

NG_execute

void NG_execute (HANDLE Handle, short approx_flag);

Executes TI-Basic statements.

NG_execute executes a sequence of TI-Basic statements in tokenized form, which are located in a memory block pointed to by handle Handle. It is a handle to a MULTI_EXPR structure. To create such a block, the functions push_parse_text and HS_popEStack may be very useful, like in the following example:

push_parse_text ("ClrGraph:Graph sin(x)");
handle = HS_popEStack ();
NG_execute (handle, FALSE);
HeapFree (handle);

If approx_flag is non-zero, the sequence will be executed in "approx" mode (like running with [DIAMOND]+[ENTER]). Otherwise, the current mode settings will be used. This routine is called after NG_RPNToText from the home screen.

NG_execute can also evaluate expressions. In this case, the result of the evaluation is pushed on the top of the expression stack.

Note: This routine always clears the error context, resets control flags, may cause estack expansion or heap compression. It may throw various errors if something is wrong.

NG_graphESI

void NG_graphESI (CESI ptr, HANDLE Handle);

Evaluates an expressions for graphing purposes.

NG_graphESI is the function used in TIOS during drawing function graphs. It evaluates the entry on the expression stack pointed to by ptr in "APPROX" mode then pushes the result on the top of the expression stack, similar to what NG_approxESI does, but NG_graphESI requires that all variables in the expression must be defined, i.e. the expression must evaluate to a number (else "Undefined variable" error will be thrown). Handle is the handle of the function in which the expression is defined. I don't know exactly when and why this function needs this handle (probably to check which variables are parameters of the function, which variables are local etc.). When I tried to pass H_NULL to this function, nothing bad happened. However, in the absence of more info, avoid this function.

NG_rationalESI

void NG_rationalESI (CESI ptr);

Evaluates an expression in "EXACT" mode.

NG_rationalESI executes the entry on the expression stack pointed to by ptr (it needs to point to the entry tag) in "EXACT" mode, then pushes the result (i.e. a new expression) on the top of the expression stack. See the example of usage given with display_statements. The same notes given with NG_approxESI are true with this command too.

Note: The expression must not contain TI-Basic statements. For executing TI-Basic statements, use NG_execute. Also, this command may cause expansion of the expression stack or heap compression, and may throw various errors is something is wrong.

NG_RPNToText

HANDLE NG_RPNToText (HANDLE hRPN, unsigned short NewLines, unsigned short FullPrec);

Detokenizes a tokenized structure associated with a handle.

NG_RPNToText detokenizes a tokenized structure (an expression, TI-Basic statement or a group of statements) associated with handle hRPN and returns a handle to the memory block where detokenized string is stored (you don't need to allocate anything by yourself, this function will do it instead). The first word of the data associated with hRPN should be the length of the data which is used to find the first tag of the tokenized data. It throws an error if the detokenization fails. This function is mainly identical to display_statements except NG_RPNToText requires a handle instead of the pointer to the structure which needs to be detokenized. See display_statements for more info.

NG_tokenize

short NG_tokenize (HANDLE hTEXT, unsigned short *ErrCode, unsigned short *ErrOffset);

Tokenizes text associated with a handle and pushes them to the expression stack.

NG_tokenize is more powerful variant of push_parse_text. It tokenizes the text associated with the handle hTEXT, and pushes the converted text to the expression stack. Returns TRUE if the operation was successful, otherwise it returns FALSE. If there was an error, then the variable pointed to by ErrCode contains the error code, and the variable pointed to by ErrOffset contains the offset in the text where the error occurred. If there were not any errors, then the variable pointed to by ErrCode contains multi state (this is the result returned from push_parse_text) and ErrOffset is undefined. This routine may expand the expression stack, may cause the heap compression, or even may throw an error if something goes really wrong (not enough memory, for example).

norm1_complex_Float

float norm1_complex_Float (CESI ptr);

Finds the 1-norm of a complex number entry.

norm1_complex_Float finds the 1-norm (i.e. the sum of absolute values of real and imaginary part) of the complex number entry pointed to by ptr and returns the result. If the entry is not a complex or real floating point number, the result is garbage (in the case of a real number, norm1_complex_Float reduces to a simple absolute value).

numeric_factor_index

ESI numeric_factor_index (CESI ptr);

Searches factors in the expression for a numeric factor.

If ptr points to the MUL_TAG, which is a case when it points to an expression of form factor1 * factor2 * ... (i.e. if the expression is a product of simpler factors), numeric_factor_index returns the pointer to the eventual numeric factor in the expression. If the expression is a number, numeric_factor_index returns ptr (i.e. the pointer to the expression itself). If ptr does not point to the MUL_TAG (i.e. if the expression is not a product of simpler factors), or if there is not any numeric factors in the expression, lead_factor_index returns a pointer to a simple expression which consists only of the number 1 (floating point or integer, depending of whether the approximation mode is active or not).

Note: This function is not implemented to be very universal. TIOS always "reorganizes" expressions on such way that numeric factors are at the beginning of the expression (i.e. x*3 will be reorganized into 3*x), and this function assumes that the expression is organized on such way. This is the so-called "internal canonic" form, and such expressions always have at most one factor with a numeric tag, in which case it is the deepest factor. So, '3*x^2*y' contains a numeric factor (3), but '2*x+3' does not. Also, numeric factors in numerators and denominators are always simplified into a single numeric factor in internal canonic forms (so, the numeric factor of '6*x/(4*y)' after conversion to canonic form is 3/2. Fortunately, all expressions in arguments are always in internal canonic form. However, this is not true after push_parse_text function, nor after an evaluation using NG_rationalESI or NG_approxESI. In other words, results of these commands are not always "correctly" organized. To force converting an expression to the internal canonic form, always call push_internal_simplify after usage any of functions mentioned above.

Parms2D

void Parms2D (CESI ptr, short *Width, short *Bottom, short *Top);

Gets information about dimensions of block which will be "pretty printed".

Parms2D gets information about the screen space which will be occupied by displayed expression. It should be called after calling Parse2DExpr (or Parse2DMultiExpr), and ptr should be a result returned from it. Params2D stores the information in three variables pointed to by Width, Bottom and Top. Width is the width of the displayed block, and Top and Bottom are distances of top and bottom edge of the block measured from the wanted y position. More precise, if the expression is printed at (x, y) using Print2DExpr, the left corner of the occupied space will be at (x, y-*Top), and the right corner of the occupied space will be at (x+*Width, y+*Bottom). So, the 2D expression has an imaginary center line above which is the "Top", and below (counting this line too) is the "Bottom".

Parse1DExpr

HANDLE Parse1DExpr (CESI ptr, unsigned short FullPrec, unsigned short width);

Parses a tokenized expression to be printed.

Parse1DExpr does a similar job as display_statements (i.e. converts a RPN expression to the TEXT and returns the handle to the text), but the parameters are somewhat different. Here, width is the maximum width of text result (0 indicates no width restriction). So, when necessary, symbolic expressions are truncated to width-1 characters and terminated with an ellipsis character ('...'). When ptr points to a tagged floating point number, the number is rounded to fit in width characters. When the number cannot be rounded to fit in width characters, an ellipsis character ('...') is returned. See display_statements for more info.

Parse2DExpr

ESI Parse2DExpr (CESI ptr, unsigned short FullPrec);

Parses a tokenized expression to be pretty printed using Print2DExpr.

Parse2DExpr parses the expression pointed to by ptr, so it can be displayed with Print2DExpr. This function splits up expression into blocks with information about their relative position and size. This splitting is performed for efficiency reasons, so the expression may be displayed again without having to calculate the positions again. Parse2DExpr returns the pointer to a created structure (it needs to be passed to Print2DExpr). This pointer is in fact the new value of top_estack, because the created structure (known as "boxed RPN") is also pushed on the expression stack. FullPrec is a Boolean flag: when it is non-zero, all floating point values will be converted using the maximal precision (14 digits), else current precision settings (from TI-Basic MODE dialog) will be used. If there is not enough memory, a special symbol is pushed onto the expression stack to signify this. This routine may cause heap compression. See Print2DExpr for an example of usage.

Parse2DExpr will always convert expressions into the "canonic printing (external) form". For example, both x*3 and 3*x will be displayed as 3*x, x*y^(-1) will be displayed as x/y etc.

Note: Break key (ON) is checked during execution of this function, and pressing it will throw an error!

Parse2DMultiExpr

ESI Parse2DMultiExpr (HANDLE Handle, unsigned short FullPrec);

Parses a multi-statement expression associated with a handle to be pretty printed using Print2DExpr.

Parse2DMultiExpr parses a multi-expression (see MULTI_EXPR) associated with Handle so that it can be displayed with Print2DExpr. Parameter FullPrec has the same meaning as in Parse2DExpr. The expression associated with Handle may contain multiple expressions separated with NEXTEXPR_TAG (in opposite to Parse2DExpr). I must admit that I don't understand this function very well, so avoid it except if you know about it more than I know...

Print2DExpr

void Print2DExpr (CESI ptr, WINDOW *w, short x, short y);

Performs "pretty printing" (or "2D printing") of an expression.

Print2DExpr prints the expression in "pretty" or "2D" style. Before printing, the expression needs first to be "parsed" using Parse2DExpr, and argument ptr should be a result returned from Parse2DExpr (an error may be thrown if ptr points to something else). w is a pointer to the WINDOW structure which describes the window in which the expression will be displayed (see wingraph.h header file for more info about windows). If you didn't create your own windows in the program, you can pass DeskTop as the parameter (as in the example given below). x and y are coordinates (window-relative) where the expression will be printed. x determines the left edge of the expression, and the expression goes (in y direction) both above and below the value of y. See Parms2D for exact information about dimensions of displayed expression. If the displayed expression can not fit into the given window, it will be simply clipped at edges of the window.

Here is an example (called "Pretty Print") which first calculates the integral of 1/((x-3)(x^2+4)), then "pretty prints" the result on the screen:

// Calculate an integral and pretty print it

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define MIN_AMS 101           // Compile for AMS 1.01 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

#include <tigcclib.h>         // Include All Header Files

// Main Function
void _main(void)
{
  TRY
    push_END_TAG ();
    push_quantum (VAR_X_TAG);
    push_parse_text ("1/((x-3)(x^2+4))");
    push_quantum (INTEGRATE_TAG);
    NG_rationalESI (top_estack);
    WinClr (DeskTop);
    Print2DExpr (Parse2DExpr (top_estack, FALSE), DeskTop, 0, 50);
  ONERR
    DrawStr (20, 20, "Error!", A_NORMAL);
  ENDTRY
  ngetchx ();
}

It is also possible to use

Parse2DExpr (top_estack, FALSE);
Print2DExpr (top_estack, DeskTop, 0, 50);

instead of

Print2DExpr (Parse2DExpr (top_estack, FALSE), DeskTop, 0, 50);

You can use Parms2D to get information about the height and the width of the printed expression without displaying it on the screen. This may be used to determine coordinates where the expression needs to be displayed.

push_ANSI_string

void push_ANSI_string (const char *str);

Pushes a standard C string to the expression stack.

push_ANSI_string is an alias (known from earlier versions of the TIGCC Library) for the TIOS function push_zstr.

push_between

void push_between (void *ptr1, void *ptr2);

Pushes a sequence of bytes to the expression stack.

push_between pushes a sequence of bytes starting at ptr1+1 and ending at ptr2 to the expression stack.

Note: The break key (ON) is checked during execution of this routine, and an error is thrown if it is pressed!

push_cnvrt_integer_if_whole_nmb

void push_cnvrt_integer_if_whole_nmb (CESI ptr);

Pushes a floating point entry eventually converted to an integer.

push_cnvrt_integer_if_whole_nmb checks the entry on the expression stack pointed to by ptr. If it is not a floating point value (represented by FLOAT_TAG), or if it is a floating point value which is not a whole number, yet another copy of the entry is pushed on the expression stack. If the entry is a floating point value which is a whole number, this number is pushed on the expression stack, but this time as an integer (i.e. with POSINT_TAG or NEGINT_TAG).

push_END_TAG

void push_END_TAG (void);

Pushes end-of-list marker to the expression stack.

push_END_TAG pushes END_TAG to the expression stack. This is the same as push_quantum (END_TAG).

push_END_TAG may be useful when you want to push a list on the expressions stack: first push END_TAG, then all elements of the list in reverse order, and finally push LIST_TAG (using push_LIST_TAG).

push_expr_quantum

void push_expr_quantum (CESI ptr, ESQ Tag);

Pushes an expression followed by a tag to the expression stack.

push_expr_quantum pushes an entry (expression) pointed to by ptr (it needs to point to the entry tag) to the top of the expression stack, then pushes a byte Tag. The entry does not need to be a simple entity; it may be a complex symbolic expression, too. This is achieved by calling next_expression_index and push_between. This function is useful when you need to perform a unary operation on the expression.

push_expr2_quantum

void push_expr2_quantum (CESI ptr1, CESI ptr2, ESQ Tag);

Pushes two expressions followed by a tag to the expression stack.

push_expr2_quantum pushes two entries (expressions) on the expression stack pointed to by ptr1 and ptr2 to the top of the stack, then pushes a byte Tag. This function is useful when you need to perform a binary operation on two expressions.

push_expression

void push_expression (CESI ptr);

Pushes an expression to the expression stack.

push_expression pushes an entry (expression) pointed to by ptr (it needs to point to the entry tag) to the top of the expression stack. The entry does not need to be a simple entity; it may be a complex symbolic expression, too. This is achieved by calling next_expression_index and push_between.

push_Float_to_nonneg_int

void push_Float_to_nonneg_int (float value);

Rounds a floating point value to an integer, then pushes it to the expression stack.

push_Float_to_nonneg_int rounds value to the nearest integer, then pushes it to the expression stack, as a tagged integer value. The sign of value is ignored. This routine may throw an error if the truncated integer part of value is not representable as a big integer.

push_Float_to_rat

void push_Float_to_rat (CESI ptr);

Pushes a rational approximation of a floating point entry.

push_Float_to_rat finds a rational approximation of the floating point entry pointed to by ptr (of course, ptr points to the tag), and pushes it on the top of the expression stack. The relative error can be specified using the AMS global variable RAtionalize_tol. This routine works well even with transfinite floats (e.g. POSITIVE_INF will be pushed as INFINITY_TAG).

push_Float

void push_Float (float value);

Pushes a floating point value to the expression stack.

push_Float rounds value to the 14 significant digits (using round14), then pushes it to the expression stack. If value is not representable as a finite float, the most appropriate transfinite tag is pushed.

push_internal_simplify

void push_internal_simplify (CESI ptr);

Converts an expression into internal canonic form and pushes the result to the expression stack.

This extremely important low-level subroutine converts an expression pointed to by ptr to the internal canonic form (see top_estack for more info about the internal canonic form), and pushes the converted expression at the top of the expression stack. This routine accepts all valid (algebraic, calculus, relational, logical or Boolean) tokenized expressions. During the conversion, various simplifications may be performed as well. This routine may cause heap compression, stack expansion, and may throw an error if something goes wrong.

push_LIST_TAG

void push_LIST_TAG (void);

Pushes list tag to the expression stack.

push_LIST_TAG pushes LIST_TAG to the expression stack. This is the same as push_quantum (LIST_TAG).

push_LIST_TAG may be useful when you want to push a list on the expressions stack: first push END_TAG (using push_END_TAG), then all elements of the list in reverse order, and finally push LIST_TAG.

push_long_to_integer

void push_long_to_integer (long value);

Pushes a signed long integer to the expression stack.

push_long_to_integer pushes the long integer value value to the expression stack. It is the same as push_longint, except that it is implemented in the operating system instead of by TIGCC.

push_longint

void push_longint (long value);

Pushes a long integer to the expression stack.

push_longint pushes the long integer value value to the expression stack.

Note: push_longint is not a TIOS entry; it is implemented "by hand" using push_quantum. This means that either push_shortint or push_longint should be used in a program, but using both is usually not desirable.

push_longlongint

void push_longlongint (long long value);

Pushes a double-long integer to the expression stack.

push_longlongint pushes the double-long integer value value to the expression stack.

Note: push_longlongint is not a TIOS entry; it is implemented "by hand" using push_quantum.

push_next_arb_int

void push_next_arb_int (void);

Pushes a next "arbitrary integer" symbol to the expression stack.

push_next_arb_int pushes a next "arbitrary integer" symbol (i.e. symbol @nxxx) to the top of the expression stack. More precise, it increments an internal counter for arbitrary integers, pushes the counter on the stack, then pushes ARB_INT_TAG. The counter wraps to zero after 255 is reached.

push_next_arb_real

void push_next_arb_real (void);

Pushes a next "arbitrary real" symbol to the expression stack.

push_next_arb_int pushes a next "arbitrary real" symbol (i.e. symbol @xxx) to the top of the expression stack. More precise, it increments an internal counter for arbitrary reals, pushes the counter on the stack, then pushes ARB_REAL_TAG. The counter wraps to zero after 255 is reached.

push_next_internal_var

void push_next_internal_var (ESQ Tag);

Pushes an internal variable to the expression stack.

push_next_internal_var is an auxiliary function used in calculus operations. It pushes the sequence 0, Tag+1, count, 0 to the expression stack, where count is the internal counter of internal variables. Then, the counter is increased by one. TIOS usually passes 0 or 1 for Tag, so it manages a two independent sets of internal variables. You can see that internal variable names consist of two bytes (see VAR_NAME_TAG): one byte is "set number", and another byte is "number of a variable in the set".

push_offset_array

unsigned short push_offset_array (CESI elements_ptr, unsigned short **dest);

Pushes an array of offsets to the list items.

This function is not complicated, but it is a bit hard to explain. It first increments the pointer to the top of the expression stack to the nearest even address, then pushes a word array which contains the offsets to all entries on the expression stack below elements_ptr until END_TAG is reached. The offset is expressed relative to the elements_ptr. push_offset_array returns the size of pushed array in words (i.e. the number of elements), and stores in the pointer variable pointed to by dest the top address of pushed array. For example, if you execute the following sequence

unsigned int *offsets;
ESI esi;
unsigned int count;
...
esi=top_estack;
count=push_offset_array (esi, &offsets);

then esi-offsets[0], esi-offsets[-1], esi-offsets[-2], ..., esi-offsets[1-count] will point to entries on the expression stack. esi-offsets[0] will point to the further entry from the top of the expression stack, esi-offsets[-1] will point to the next one, and finally, esi-offsets[1-count] will point to the entry on the top of the expression stack (more precise, offsets[1-count] is always zero). This function is useful when you need a fast way to access to all entries on the expression stack many times.

push_overflow_to_infinity

void push_overflow_to_infinity (ESQ inf_tag);

Displays a warning, and pushes a tag to the expression stack.

push_overflow_to_infinity displays the warning message "Warning: Overflow replaced by INF or -INF", then pushes byte inf_tag to the expression stack (it is usually INFINITY_TAG or NEGINFINITY_TAG).

push_parse_text

short push_parse_text (const char *str);

Parses an expression given in a string and pushes tokenized expression to the expression stack.

push_parse_text is an extremely powerful function: it parses the expression given in the string str, and pushes the expressions (in RPN form) to the expression stack. This function also can parse TI-Basic statements (after parsing, the tokenized form of these statements is pushed on the expression stack too). push_parse_text returns FALSE if the expression is a multi expression (i.e. if it contains ":" [separator], "->" [store] or TI-Basic statements), otherwise it returns TRUE. This routine may cause expansion of the expression stack or heap compression. TIGCCLIB internally uses this function (together with estack_number_to_Float) in the implementation of atof function. For more examples of usage of this function, see NG_approxESI, NG_rationalESI, NG_execute etc. The "inverse" function of push_parse_text is display_statements.

If you want to perform highly advanced symbolic operations with expressions, you should know that expressions created by push_parse_text are not always organized on a way which allows the most efficient symbolic processing (so-called internal canonic form). For example, TIOS always converts 'x*3' into '3*x' and converts 'x-y' into 'x+y*(-1)', although it will be printed as 'x-y'. However, expressions created by push_parse_text are always as-is, i.e. '3*x' will be just '3*x', not 'x*3'. Some routines (like numeric_factor_index for example) may be fooled if the expression is not "sorted" correctly. Also, some routines (like lead_term_index, lead_factor_index etc.) may also be fooled with expressions like 'x-y' and 'x/y', because operators '-' and '/' are usually never seen in expressions during symbolic processing (the processing is more unique if addition and subtraction are treated as the same operation; the same is true for '*' and '/'). So, if you planed to perform some advanced symbolic processing which is based on accessing various part of the expression, always call push_internal_simplify after calling push_parse_text. This function pushes on the expression stack the same expression but converted in internal canonic form.

Note: push_parse_text will throw an error if the string contains expression with wrong syntax, so you need to use TRY etc. to catch eventual errors. And, the string must be built using TI-Basic conventions (for example, you must use 0xAD ("small" minus) instead of '-' for unary minus, etc. See NG_tokenize for a more powerful function which doesn't throw any errors, and which can determine the exact location and type of the error.

push_quantum_pair

void push_quantum_pair (ESQ Tag1, ESQ Tag2);

Pushes two bytes (tags) to the expression stack.

push_quantum_pair pushes the bytes Tag1 and Tag2 to the expression stack. Basically, it acts like:

push_quantum (Tag1);
push_quantum (Tag2);

but it is a little more optimized.

push_quantum

void push_quantum (ESQ Tag);

Pushes a byte (tag) to the expression stack.

push_quantum is the basic function for manipulating the expression stack, and many other functions are based on it. It pushes a byte Tag to the expression stack. For example, you can push a complex value to the expression stack using the following construction:

push_Float (real_part);
push_Float (imaginary_part);
push_quantum (COMPLEX_TAG);

See push_Float, and info about top_estack and Tags for more info about this example.

Note: This routine (as well as all other "push_..." routines) may cause heap compression, and may throw an error if there is not enough space on the expression stack.

push_reversed_tail

void push_reversed_tail (CESI ptr);

Pushes elements of the list up to tail onto the stack in reversed order.

push_reversed_tail first pushes END_TAG to the expression stack, then pushes all expressions starting from the expression pointed to by ptr one by one (by calling next_expression_index) until END_TAG is reached. So after calling this function, the expressions up to tail will be pushed onto the stack in reversed order. See other "tail" operations like map_tail.

push_round_Float

void push_round_Float (CESI ptr);

Pushes an approximation of a floating point entry.

push_round_Float first finds a rational approximation of the floating point entry pointed to by ptr using push_Float_to_rat, then converts this fraction back to the floating point number and pushes it on the top of the expressions stack. The summary effect is rounding float to the precision of about 1e-5.

push_shortint

void push_shortint (short value);

Pushes a short integer to the expression stack.

push_shortint pushes the short integer value value to the expression stack.

Note: push_shortint is not a TIOS entry; it is implemented "by hand" using push_quantum. This means that either push_shortint or push_longint should be used in a program, but using both is usually not desirable.

push_simplify

void push_simplify (CESI ptr);

Simplifies the argument and pushes onto the estack.

push_simplify is like push_internal_simplify, but does not convert into internal canonic form.

push_transpose_aux

void push_transpose_aux (CESI ptr, short ConjFlag);

Pushes transposed matrix to the expression stack.

Assuming that ptr points to the tag of a matrix (which is, in fact, a list of equally sized lists), push_transpose_aux pushes the transpose of the matrix to the expression stack. If ConjFlag is TRUE, a complex conjugate transpose will be produced, and if ConjFlag is FALSE, an ordinary transpose will be produced. For complex conjugate transposition, the matrix should be in canonic internal form (see push_internal_simplify). If ptr doesn't point to a matrix, the behavior is unpredictable.

push_ulong_to_integer

void push_ulong_to_integer (unsigned long value);

Pushes an unsigned long integer to the expression stack.

push_ulong_to_integer pushes the long integer value value to the expression stack. It is the same as push_long_to_integer, except that the value is interpreted as an unsigned value.

push_ushort_to_integer

void push_ushort_to_integer (unsigned short value);

Pushes an unsigned short integer to the expression stack.

push_ushort_to_integer pushes the short integer value value to the expression stack. It is the same as push_shortint, except that the value is interpreted as an unsigned value, and that it is implemented in the operating system instead of by TIGCC.

push_zstr

void push_zstr (const char *str);

Pushes a standard C string to the expression stack.

push_zstr pushes the string str to the expression stack. str is a standard ANSI (zero-terminated) string.

re_index

ESI re_index (CESI ptr);

Gets the index of the real part of an expression.

If ptr points to the COMPLEX_TAG (i.e. if the expression is complex), re_index returns the pointer to the real part of the expression. If ptr does not point to the COMPLEX_TAG (i.e. if the expression is real), re_index returns ptr (i.e. the pointer to the expression itself).

Note: The expression should be in internal canonic form (see push_internal_simplify), else this function is not reliable.

reductum_index

ESI reductum_index (CESI ptr);

Gets the index of remaining terms of an expression.

If ptr points to the ADD_TAG, which is a case when it points to an expression of form term1 + term2 + ... (i.e. if the expression is a sum of simpler terms), reductum_index returns the pointer to the subexpression term2 + ... (which is a reductum subexpression of the given expression). If ptr does not point to the ADD_TAG (i.e. if the expression is not a sum of simpler terms), reductum_index returns a pointer to a simple zero expression, i.e. expression which consists only of number 0 (floating point or integer, depending of whether the approximation mode is active or not).

Note: Expressions in internal canonic form have the most main term shallowest (see lead_term_index. So, the reductum of '2+x+y' converted to canonic form is 'y+2'. By default, similar powers of the main variable are collected in internal canonic forms. For example, the reductum of 'x^2*y+x^2+5' converted to canonic form is '5'. See push_internal_simplify for more info about how to convert an expression into the internal canonic form.

remaining_element_count

unsigned short remaining_element_count (CESI start_ptr);

Returns number of elements remaining.

remaining_element_count counts how many expressions are stored on the expressions stack below the expression pointed to by ptr (including this one). END_TAG is treated as the terminator, so eventual expressions below END_TAG are not counted. So, if ptr points to an element of the list, remaining_element_count returns the number of elements in the list starting from this element up to the end of the list.

remaining_element_count works using repeated calling next_expression_index and increasing a counter until END_TAG is reached.

remaining_factors_index

ESI remaining_factors_index (CESI ptr);

Gets the index of remaining factors of an expression.

If ptr points to the MUL_TAG, which is a case when it points to an expression of form factor1 * factor2 * ... (i.e. if the expression is a sum of simpler terms), remaining_factors_index returns the pointer to the subexpression term2 * ... (i.e. to the remaining factors of the expression). If ptr does not point to the MUL_TAG (i.e. if the expression is not a product of simpler factors), remaining_factors_index returns a pointer to a simple expression which consists only of number 1.

Note: Expressions in internal canonic form have the most main factor shallowest, with less main factors below that (see compare_expressions for more info about "main" ordering). Also, the lead factor of an internally-simplified product is never a product. For example, remaining factors of '(3*x^2)*y' converted into canonic form are '3*y'. By default, similar powers of the main variable are collected, so remaining factor of 'x^2*y+x^2' after conversion into canonic form is 'y+1'. Internally-simplified numeric denominator factors are combined with numeric numerator factors into a fractional numeric factor. Non-numeric denominator factors are internally simplified to be merged with numerator factors as negative powers. See push_internal_simplify for more info about how to convert an expression into the internal canonic form.

reset_control_flags

void reset_control_flags (void);

Resets the control flags for operations with the expression stack.

reset_control_flags resets various control flags which control operations which use the expression stack. It is good idea to call this function before starting any calculation using the expression stack.

reset_estack_size

void reset_estack_size (unsigned short NewSize);

Reallocates the expression stack.

reset_estack_size changes the size of the expression stack to NewSize. It throws an error if the requirement cannot be satisfied. If NewSize is smaller than the current amount of used space, then the expression stack is set to the current amount of used space instead of NewSize. Default size of the expression stack is 16384 bytes.

should_and_did_push_approx_arg2

short should_and_did_push_approx_arg2 (CESI arg1_ptr, CESI arg2_ptr);

Pushes a second floating point argument, if possible.

This function is combination of "push" and "check" operations. If the entry on the expressions stack pointed to by arg1_ptr is not a floating point number (i.e. if arg1_ptr does not point to FLOAT_TAG), this function does nothing and returns FALSE. Otherwise, it checks if it is likely that the entry on the expression stack pointed to by arg2_ptr can be approxed to a real number (using likely_approx_to_number). If it is, should_and_did_push_approx_arg2 pushes the approximated value to the expression stack and returns TRUE, otherwise it does nothing more and returns FALSE.

signum_Float

long signum_Float (CESI ptr);

Finds the signum of a floating point entry.

signum_Float finds the signum of the floating point entry pointed to by ptr (i.e. returns 1 if the entry is positive, -1 if it is negative, 0 if it is zero). If the entry is not a floating point number, the result is garbage.

subtract_from_top

void subtract_from_top (CESI ptr);

Subtracts a value from the top of the estack.

subtract_from_top subtracts the expression pointed to by ptr from the expression currently at the top of the estack.

subtract1_from_top