calc: Stack Lisp Functions
18.5.7.3 Stack-Oriented Functions
.................................
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 VALS onto the stack at stack level N.
If N is omitted it defaults to 1, so that the elements are pushed
at the top of the stack. If N is greater than 1, the elements will
be inserted into the stack so that the last element will end up at
level N, the next-to-last at level N+1, etc. The elements of VALS
are assumed to be valid Calc objects, and are not evaluated,
rounded, or renormalized in any way. If VALS is 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 VALS of selections. Each selection
must be ‘eq’ to some sub-formula of the corresponding formula in
VALS, or ‘nil’ if that formula should have no selection.
-- Function: calc-top-list n m
Return a list of the N objects starting at level M of the stack.
If M is omitted it defaults to 1, so that the elements are taken
from the top of the stack. If N is omitted, it also defaults to 1,
so that the top stack element (in the form of a one-element list)
is returned. If M is greater than 1, the Mth stack element will be
at the end of the list, the M+1st element will be next-to-last,
etc. If N or M are out of range, the command is aborted with a
suitable error message. If N is 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 the ‘j e’
command.) 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 N and
M are 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 e’ has 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 VALS
are a list of strings or Calc objects. The TAG is the
four-character tag string to identify the values. If TAG is
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 (
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 VALS argument should be either a single Calc
object, or a list of Calc objects; the object or objects are
normalized, and the top N stack entries are replaced by the
normalized objects. If TAG is non-‘nil’, the normalized objects
are also recorded in the trail. A typical stack-based
computational command would take the form,
(calc-enter-result N TAG (cons 'calcFunc-FUNC
(calc-top-list-n N)))
If any of the N stack elements replaced contain sub-formula
selections, and selections have not been disabled by ‘j e’, this
function takes one of two courses of action. If N is equal to the
number of elements in VALS, then each element of VALS is 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’. If VALS has only one element but N is greater than one,
there must be only one selection among the top N stack elements;
the element from VALS is spliced into that selection. This is what
happens when you use a binary arithmetic operation like ‘+’. Any
other combination of N and VALS is 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 ARG is ‘nil’, this uses ‘calc-enter-result’ as
outlined above. Otherwise, it maps the function over several stack
elements; 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 optional IDENT and UNARY arguments specify
the behavior when the prefix argument is zero or one, respectively.
If the prefix is zero, the value IDENT is pushed onto the stack, if
specified, otherwise an error message is displayed. If the prefix
is one, the unary function UNARY is applied to the top stack
element, or, if UNARY is not specified, nothing happens. When the
argument is two or more, the binary function FUNC is reduced across
the top ARG stack elements; when the argument is negative, the
function is mapped between the next-to-top -ARG stack 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; Truncating the Stack.
-- Function: calc-cursor-stack-index n
Move the point to the Nth stack entry. If N is zero, this will be
the ‘.’ line. If N is 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. If N is 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
equal N+1 as long as N is 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 the
‘X’ key, 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.)
Info Catalog
calc: Interactive Lisp Functions
calc: Internals
calc: Predicates