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 "illegal 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 (*Note
     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; 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 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; See 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.)