Next: Predicates, Previous: Interactive Lisp Functions, Up: Internals

The functions described here perform various operations on the Calc stack and trail. They are to be used in interactive Calc commands.

— Function: **calc-push-list**` vals n`

Push the Calc objects in list

valsonto the stack at stack leveln. Ifnis omitted it defaults to 1, so that the elements are pushed at the top of the stack. Ifnis greater than 1, the elements will be inserted into the stack so that the last element will end up at leveln, the next-to-last at leveln+1, etc. The elements ofvalsare assumed to be valid Calc objects, and are not evaluated, rounded, or renormalized in any way. Ifvalsis an empty list, nothing happens.The stack elements are pushed without any sub-formula selections. You can give an optional third argument to this function, which must be a list the same size as

valsof selections. Each selection must be`eq`

to some sub-formula of the corresponding formula invals, or`nil`

if that formula should have no selection.

— Function: **calc-top-list**` n m`

Return a list of the

nobjects starting at levelmof the stack. Ifmis omitted it defaults to 1, so that the elements are taken from the top of the stack. Ifnis omitted, it also defaults to 1, so that the top stack element (in the form of a one-element list) is returned. Ifmis greater than 1, themth stack element will be at the end of the list, them+1st element will be next-to-last, etc. Ifnormare out of range, the command is aborted with a suitable error message. Ifnis zero, the function returns an empty list. The stack elements are not evaluated, rounded, or renormalized.If any stack elements contain selections, and selections have not been disabled by the

j e(`calc-enable-selections`

) command, this function returns the selected portions rather than the entire stack elements. It can be given a third “selection-mode” argument which selects other behaviors. If it is the symbol`t`

, then a selection in any of the requested stack elements produces an “invalid operation on selections” error. If it is the symbol`full`

, the whole stack entry is always returned regardless of selections. If it is the symbol`sel`

, the selected portion is always returned, or`nil`

if there is no selection. (This mode ignores thej ecommand.) If the symbol is`entry`

, the complete stack entry in list form is returned; the first element of this list will be the whole formula, and the third element will be the selection (or`nil`

).

— Function: **calc-pop-stack**` n m`

Remove the specified elements from the stack. The parameters

nandmare defined the same as for`calc-top-list`

. The return value of`calc-pop-stack`

is uninteresting.If there are any selected sub-formulas among the popped elements, and

j ehas not been used to disable selections, this produces an error without changing the stack. If you supply an optional third argument of`t`

, the stack elements are popped even if they contain selections.

— Function: **calc-record-list**` vals tag`

This function records one or more results in the trail. The

valsare a list of strings or Calc objects. Thetagis the four-character tag string to identify the values. Iftagis omitted, a blank tag will be used.

— Function: **calc-normalize**` n`

This function takes a Calc object and “normalizes” it. At the very least this involves re-rounding floating-point values according to the current precision and other similar jobs. Also, unless the user has selected No-Simplify mode (see Simplification Modes), this involves actually evaluating a formula object by executing the function calls it contains, and possibly also doing algebraic simplification, etc.

— Function: **calc-top-list-n**` n m`

This function is identical to

`calc-top-list`

, except that it calls`calc-normalize`

on the values that it takes from the stack. They are also passed through`check-complete`

, so that incomplete objects will be rejected with an error message. All computational commands should use this in preference to`calc-top-list`

; the only standard Calc commands that operate on the stack without normalizing are stack management commands like`calc-enter`

and`calc-roll-up`

. This function accepts the same optional selection-mode argument as`calc-top-list`

.

— Function: **calc-top-n**` m`

This function is a convenient form of

`calc-top-list-n`

in which only a single element of the stack is taken and returned, rather than a list of elements. This also accepts an optional selection-mode argument.

— Function: **calc-enter-result**` n tag vals`

This function is a convenient interface to most of the above functions. The

valsargument should be either a single Calc object, or a list of Calc objects; the object or objects are normalized, and the topnstack entries are replaced by the normalized objects. Iftagis non-`nil`

, the normalized objects are also recorded in the trail. A typical stack-based computational command would take the form,(calc-enter-resultntag(cons 'calcFunc-func(calc-top-list-nn)))If any of the

nstack elements replaced contain sub-formula selections, and selections have not been disabled byj e, this function takes one of two courses of action. Ifnis equal to the number of elements invals, then each element ofvalsis spliced into the corresponding selection; this is what happens when you use the <TAB> key, or when you use a unary arithmetic operation like`sqrt`

. Ifvalshas only one element butnis greater than one, there must be only one selection among the topnstack elements; the element fromvalsis spliced into that selection. This is what happens when you use a binary arithmetic operation like+. Any other combination ofnandvalsis an error when selections are present.

— Function: **calc-unary-op**` tag func arg`

This function implements a unary operator that allows a numeric prefix argument to apply the operator over many stack entries. If the prefix argument

argis`nil`

, this uses`calc-enter-result`

as outlined above. Otherwise, it maps the function over several stack elements; see Prefix Arguments. For example,(defun calc-zeta (arg) (interactive "P") (calc-unary-op "zeta" 'calcFunc-zeta arg))

— Function: **calc-binary-op**` tag func arg ident unary`

This function implements a binary operator, analogously to

`calc-unary-op`

. The optionalidentandunaryarguments specify the behavior when the prefix argument is zero or one, respectively. If the prefix is zero, the valueidentis pushed onto the stack, if specified, otherwise an error message is displayed. If the prefix is one, the unary functionunaryis applied to the top stack element, or, ifunaryis not specified, nothing happens. When the argument is two or more, the binary functionfuncis reduced across the topargstack elements; when the argument is negative, the function is mapped between the next-to-top-argstack elements and the top element.

— Function: **calc-stack-size**

Return the number of elements on the stack as an integer. This count does not include elements that have been temporarily hidden by stack truncation; see Truncating the Stack.

— Function: **calc-cursor-stack-index**` n`

Move the point to the

nth stack entry. Ifnis zero, this will be the ‘.’ line. Ifnis from 1 to the current stack size, this will be the beginning of the first line of that stack entry's display. If line numbers are enabled, this will move to the first character of the line number, not the stack entry itself.

— Function: **calc-substack-height**` n`

Return the number of lines between the beginning of the

nth stack entry and the bottom of the buffer. Ifnis zero, this will be one (assuming no stack truncation). If all stack entries are one line long (i.e., no matrices are displayed), the return value will be equaln+1 as long asnis in range. (Note that in Big mode, the return value includes the blank lines that separate stack entries.)

— Function: **calc-refresh**

Erase the

*Calculator*buffer and reformat its contents from memory. This must be called after changing any parameter, such as the current display radix, which might change the appearance of existing stack entries. (During a keyboard macro invoked by theXkey, refreshing is suppressed, but a flag is set so that the entire stack will be refreshed rather than just the top few elements when the macro finishes.)