This is gcl.info, produced by makeinfo version 6.7 from gcl.texi.

This is a Texinfo GNU Common Lisp Manual based on the draft ANSI
standard for Common Lisp.

   Copyright 1994 William F. Schelter

INFO-DIR-SECTION GNU Common Lisp
START-INFO-DIR-ENTRY
* gcl: (gcl.info). GNU Common Lisp Manual
END-INFO-DIR-ENTRY


File: gcl.info,  Node: ignore-errors,  Next: define-condition,  Prev: handler-case,  Up: Conditions Dictionary

9.2.28 ignore-errors [Macro]
----------------------------

'ignore-errors' {form}* => {result}*

Arguments and Values::
......................

forms--an implicit progn.

   results--In the normal situation, the values of the forms are
returned; in the exceptional situation, two values are returned: nil and
the condition.

Description::
.............

ignore-errors is used to prevent conditions of type error from causing
entry into the debugger.

   Specifically, ignore-errors executes forms in a dynamic environment
where a handler for conditions of type error has been established; if
invoked, it handles such conditions by returning two values, nil and the
condition that was signaled, from the ignore-errors form.

   If a normal return from the forms occurs, any values returned are
returned by ignore-errors.

Examples::
..........

      (defun load-init-file (program)
        (let ((win nil))
          (ignore-errors ;if this fails, don't enter debugger
            (load (merge-pathnames (make-pathname :name program :type :lisp)
                                   (user-homedir-pathname)))
            (setq win t))
          (unless win (format t "~&Init file failed to load.~
          win))

      (load-init-file "no-such-program")
      |>  Init file failed to load.
     NIL

See Also::
..........

*note handler-case:: , *note Condition System Concepts::

Notes::
.......

      (ignore-errors . forms)

   is equivalent to:

      (handler-case (progn . forms)
        (error (condition) (values nil condition)))

   Because the second return value is a condition in the exceptional
case, it is common (but not required) to arrange for the second return
value in the normal case to be missing or nil so that the two situations
can be distinguished.


File: gcl.info,  Node: define-condition,  Next: make-condition,  Prev: ignore-errors,  Up: Conditions Dictionary

9.2.29 define-condition [Macro]
-------------------------------

[Editorial Note by KMP: This syntax stuff is still very confused and
needs lots of work.]

   'define-condition' name ({parent-type}*) ({!slot-spec}*) {option}*
=> name

   slot-spec ::=slot-name | (slot-name !slot-option)

   slot-option ::=[[ {:reader symbol}* | 
                {:writer !function-name}* | 
                {:accessor symbol}* | 
                {:allocation !allocation-type} | 
                {:initarg symbol}* | 
                {:initform form} | 
                {:type type-specifier} ]]

   option ::=[[ (:default-initargs . initarg-list) | 
           (:documentation string) | 
           (:report report-name) ]]

   function-name ::={symbol | (setf symbol)}

   allocation-type ::=:instance | :class

   report-name ::=string | symbol | lambda expression

Arguments and Values::
......................

name--a symbol.

   parent-type--a symbol naming a condition type.  If no parent-types
are supplied, the parent-types default to (condition).

   default-initargs--a list of keyword/value pairs.

   [Editorial Note by KMP: This is all mixed up as to which is a slot
option and which is a main option.  I'll sort that out.  Also, some of
this is implied by the bnf and needn't be stated explicitly.]

   Slot-spec - the name of a slot or a list consisting of the slot-name
followed by zero or more slot-options.

   Slot-name - a slot name (a symbol), the list of a slot name, or the
list of slot name/slot form pairs.

   Option - Any of the following:

:reader
     :reader can be supplied more than once for a given slot and cannot
     be nil.

:writer
     :writer can be supplied more than once for a given slot and must
     name a generic function.

:accessor
     :accessor can be supplied more than once for a given slot and
     cannot be nil.

:allocation
     :allocation can be supplied once at most for a given slot.  The
     default if :allocation is not supplied is :instance.

:initarg
     :initarg can be supplied more than once for a given slot.

:initform
     :initform can be supplied once at most for a given slot.

:type
     :type can be supplied once at most for a given slot.

:documentation
     :documentation can be supplied once at most for a given slot.

:report
     :report can be supplied once at most.

Description::
.............

define-condition defines a new condition type called name, which is a
subtype of

   the type or types named by parent-type.  Each parent-type argument
specifies a direct supertype of the new condition.  The new condition
inherits slots and methods from each of its direct supertypes, and so
on.

   If a slot name/slot form pair is supplied, the slot form is a form
that can be evaluated by make-condition to produce a default value when
an explicit value is not provided.  If no slot form is supplied, the
contents of the slot is initialized in an implementation-dependent way.

   If the type being defined and some other type from which it inherits
have a slot by the same name, only one slot is allocated in the
condition, but the supplied slot form overrides any slot form that might
otherwise have been inherited from a parent-type.  If no slot form is
supplied, the inherited slot form (if any) is still visible.

   Accessors are created according to the same rules as used by
defclass.

   A description of slot-options follows:

:reader
     The :reader slot option specifies that an unqualified method is to
     be defined on the generic function named by the argument to :reader
     to read the value of the given slot.

*
     The :initform slot option is used to provide a default initial
     value form to be used in the initialization of the slot.  This form
     is evaluated every time it is used to initialize the slot.  The
     lexical environment in which this form is evaluated is the lexical
     environment in which the define-condition form was evaluated.  Note
     that the lexical environment refers both to variables and to
     functions.  For local slots, the dynamic environment is the dynamic
     environment in which make-condition was called; for shared slots,
     the dynamic environment is the dynamic environment in which the
     define-condition form was evaluated.

     [Reviewer Note by Barmar: Issue CLOS-CONDITIONS doesn't say this.]
     No implementation is permitted to extend the syntax of
     define-condition to allow (slot-name form) as an abbreviation for
     (slot-name :initform form).

:initarg
     The :initarg slot option declares an initialization argument named
     by its symbol argument and specifies that this initialization
     argument initializes the given slot.  If the initialization
     argument has a value in the call to initialize-instance, the value
     is stored into the given slot, and the slot's :initform slot
     option, if any, is not evaluated.  If none of the initialization
     arguments specified for a given slot has a value, the slot is
     initialized according to the :initform slot option, if specified.

:type
     The :type slot option specifies that the contents of the slot is
     always of the specified type.  It effectively declares the result
     type of the reader generic function when applied to an object of
     this condition type.  The consequences of attempting to store in a
     slot a value that does not satisfy the type of the slot is
     undefined.

:default-initargs

     [Editorial Note by KMP: This is an option, not a slot option.]

     This option is treated the same as it would be defclass.

:documentation

     [Editorial Note by KMP: This is both an option and a slot option.]

     The :documentation slot option provides a documentation string for
     the slot.

:report

     [Editorial Note by KMP: This is an option, not a slot option.]

     Condition reporting is mediated through the print-object method for
     the condition type in question, with *print-escape* always being
     nil.  Specifying (:report report-name) in the definition of a
     condition type C is equivalent to:

           (defmethod print-object ((x c) stream)
             (if *print-escape* (call-next-method) (report-name x stream)))

     If the value supplied by the argument to :report (report-name) is a
     symbol or a lambda expression, it must be acceptable to function.
     (function report-name) is evaluated in the current lexical
     environment.  It should return a function of two arguments, a
     condition and a stream, that prints on the stream a description of
     the condition.  This function is called whenever the condition is
     printed while *print-escape* is nil.

     If report-name is a string, it is a shorthand for

           (lambda (condition stream)
             (declare (ignore condition))
             (write-string report-name stream))

     This option is processed after the new condition type has been
     defined, so use of the slot accessors within the :report function
     is permitted.  If this option is not supplied, information about
     how to report this type of condition is inherited from the
     parent-type.

   The consequences are unspecifed if an attempt is made to read a slot
that has not been explicitly initialized and that has not been given a
default value.

   The consequences are unspecified if an attempt is made to assign the
slots by using setf.

   If a define-condition form appears as a top level form, the compiler
must make name recognizable as a valid type name, and it must be
possible to reference the condition type as the parent-type of another
condition type in a subsequent define-condition form in the file being
compiled.

Examples::
..........

The following form defines a condition of type peg/hole-mismatch which
inherits from a condition type called blocks-world-error:

     (define-condition peg/hole-mismatch
                       (blocks-world-error)
                       ((peg-shape  :initarg :peg-shape
                                    :reader peg/hole-mismatch-peg-shape)
                        (hole-shape :initarg :hole-shape
                                    :reader peg/hole-mismatch-hole-shape))
       (:report (lambda (condition stream)
                  (format stream "A ~A peg cannot go in a ~A hole."
                          (peg/hole-mismatch-peg-shape  condition)
                          (peg/hole-mismatch-hole-shape condition)))))

   The new type has slots peg-shape and hole-shape, so make-condition
accepts :peg-shape and :hole-shape keywords.  The readers
peg/hole-mismatch-peg-shape and peg/hole-mismatch-hole-shape apply to
objects of this type, as illustrated in the :report information.

   The following form defines a condition type named machine-error which
inherits from error:

     (define-condition machine-error
                       (error)
                       ((machine-name :initarg :machine-name
                                      :reader machine-error-machine-name))
       (:report (lambda (condition stream)
                  (format stream "There is a problem with ~A."
                          (machine-error-machine-name condition)))))

   Building on this definition, a new error condition can be defined
which is a subtype of machine-error for use when machines are not
available:

     (define-condition machine-not-available-error (machine-error) ()
       (:report (lambda (condition stream)
                  (format stream "The machine ~A is not available."
                          (machine-error-machine-name condition)))))

   This defines a still more specific condition, built upon
machine-not-available-error, which provides a slot initialization form
for machine-name but which does not provide any new slots or report
information.  It just gives the machine-name slot a default
initialization:

     (define-condition my-favorite-machine-not-available-error
                       (machine-not-available-error)
       ((machine-name :initform "mc.lcs.mit.edu")))

   Note that since no :report clause was given, the information
inherited from machine-not-available-error is used to report this type
of condition.

      (define-condition ate-too-much (error)
          ((person :initarg :person :reader ate-too-much-person)
           (weight :initarg :weight :reader ate-too-much-weight)
           (kind-of-food :initarg :kind-of-food
                         :reader :ate-too-much-kind-of-food)))
     =>  ATE-TOO-MUCH
      (define-condition ate-too-much-ice-cream (ate-too-much)
        ((kind-of-food :initform 'ice-cream)
         (flavor       :initarg :flavor
                       :reader ate-too-much-ice-cream-flavor
                       :initform 'vanilla ))
        (:report (lambda (condition stream)
                   (format stream "~A ate too much ~A ice-cream"
                           (ate-too-much-person condition)
                           (ate-too-much-ice-cream-flavor condition)))))
     =>  ATE-TOO-MUCH-ICE-CREAM
      (make-condition 'ate-too-much-ice-cream
                      :person 'fred
                      :weight 300
                      :flavor 'chocolate)
     =>  #<ATE-TOO-MUCH-ICE-CREAM 32236101>
      (format t "~A" *)
      |>  FRED ate too much CHOCOLATE ice-cream
     =>  NIL

See Also::
..........

*note make-condition:: , *note defclass:: , *note Condition System
Concepts::


File: gcl.info,  Node: make-condition,  Next: restart,  Prev: define-condition,  Up: Conditions Dictionary

9.2.30 make-condition [Function]
--------------------------------

'make-condition' type &rest slot-initializations => condition

Arguments and Values::
......................

type--a type specifier (for a subtype of condition).

   slot-initializations--an initialization argument list.

   condition--a condition.

Description::
.............

Constructs and returns a condition of type type using
slot-initializations for the initial values of the slots.  The newly
created condition is returned.

Examples::
..........

      (defvar *oops-count* 0)

      (setq a (make-condition 'simple-error
                              :format-control "This is your ~:R error."
                              :format-arguments (list (incf *oops-count*))))
     =>  #<SIMPLE-ERROR 32245104>

      (format t "~&~A~
      |>  This is your first error.
     =>  NIL

      (error a)
      |>  Error: This is your first error.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Return to Lisp Toplevel.
      |>  Debug>

Affected By::
.............

The set of defined condition types.

See Also::
..........

*note define-condition:: , *note Condition System Concepts::


File: gcl.info,  Node: restart,  Next: compute-restarts,  Prev: make-condition,  Up: Conditions Dictionary

9.2.31 restart [System Class]
-----------------------------

Class Precedence List::
.......................

restart, t

Description::
.............

An object of type restart represents a function that can be called to
perform some form of recovery action, usually a transfer of control to
an outer point in the running program.

   An implementation is free to implement a restart in whatever manner
is most convenient; a restart has only dynamic extent relative to the
scope of the binding form which establishes it.


File: gcl.info,  Node: compute-restarts,  Next: find-restart,  Prev: restart,  Up: Conditions Dictionary

9.2.32 compute-restarts [Function]
----------------------------------

'compute-restarts' &optional condition => restarts

Arguments and Values::
......................

condition--a condition object, or nil.

   restarts--a list of restarts.

Description::
.............

compute-restarts uses the dynamic state of the program to compute a list
of the restarts which are currently active.

   The resulting list is ordered so that the innermost (more-recently
established) restarts are nearer the head of the list.

   When condition is non-nil, only those restarts are considered that
are either explicitly associated with that condition, or not associated
with any condition; that is, the excluded restarts are those that are
associated with a non-empty set of conditions of which the given
condition is not an element.  If condition is nil, all restarts are
considered.

   compute-restarts returns all applicable restarts, including anonymous
ones, even if some of them have the same name as others and would
therefore not be found by find-restart when given a symbol argument.

   Implementations are permitted, but not required, to return distinct
lists from repeated calls to compute-restarts while in the same dynamic
environment.  The consequences are undefined if the list returned by
compute-restarts is every modified.

Examples::
..........

      ;; One possible way in which an interactive debugger might present
      ;; restarts to the user.
      (defun invoke-a-restart ()
        (let ((restarts (compute-restarts)))
          (do ((i 0 (+ i 1)) (r restarts (cdr r))) ((null r))
            (format t "~&~D: ~A~
          (let ((n nil) (k (length restarts)))
            (loop (when (and (typep n 'integer) (>= n 0) (< n k))
                    (return t))
                  (format t "~&Option: ")
                  (setq n (read))
                  (fresh-line))
            (invoke-restart-interactively (nth n restarts)))))

      (restart-case (invoke-a-restart)
        (one () 1)
        (two () 2)
        (nil () :report "Who knows?" 'anonymous)
        (one () 'I)
        (two () 'II))
      |>  0: ONE
      |>  1: TWO
      |>  2: Who knows?
      |>  3: ONE
      |>  4: TWO
      |>  5: Return to Lisp Toplevel.
      |>  Option: |>>4<<|
     =>  II

      ;; Note that in addition to user-defined restart points, COMPUTE-RESTARTS
      ;; also returns information about any system-supplied restarts, such as
      ;; the "Return to Lisp Toplevel" restart offered above.


Affected By::
.............

Existing restarts.

See Also::
..........

*note find-restart:: , *note invoke-restart:: , *note restart-bind::


File: gcl.info,  Node: find-restart,  Next: invoke-restart,  Prev: compute-restarts,  Up: Conditions Dictionary

9.2.33 find-restart [Function]
------------------------------

'find-restart' identifier &optional condition restart

Arguments and Values::
......................

identifier--a non-nil symbol, or a restart.

   condition--a condition object, or nil.

   restart--a restart or nil.

Description::
.............

find-restart searches for a particular restart in the current dynamic
environment.

   When condition is non-nil, only those restarts are considered that
are either explicitly associated with that condition, or not associated
with any condition; that is, the excluded restarts are those that are
associated with a non-empty set of conditions of which the given
condition is not an element.  If condition is nil, all restarts are
considered.

   If identifier is a symbol, then the innermost (most recently
established) applicable restart with that name is returned.  nil is
returned if no such restart is found.

   If identifier is a currently active restart, then it is returned.
Otherwise, nil is returned.

Examples::
..........

      (restart-case
          (let ((r (find-restart 'my-restart)))
            (format t "~S is named ~S" r (restart-name r)))
        (my-restart () nil))
      |>  #<RESTART 32307325> is named MY-RESTART
     =>  NIL
      (find-restart 'my-restart)
     =>  NIL

Affected By::
.............

Existing restarts.

   restart-case, restart-bind, with-condition-restarts.

See Also::
..........

*note compute-restarts::

Notes::
.......

      (find-restart identifier)
      == (find identifier (compute-restarts) :key :restart-name)

   Although anonymous restarts have a name of nil, the consequences are
unspecified if nil is given as an identifier.  Occasionally, programmers
lament that nil is not permissible as an identifier argument.  In most
such cases, compute-restarts can probably be used to simulate the
desired effect.


File: gcl.info,  Node: invoke-restart,  Next: invoke-restart-interactively,  Prev: find-restart,  Up: Conditions Dictionary

9.2.34 invoke-restart [Function]
--------------------------------

'invoke-restart' restart &rest arguments => {result}*

Arguments and Values::
......................

restart--a restart designator.

   argument--an object.

   results--the values returned by the function associated with restart,
if that function returns.

Description::
.............

Calls the function associated with restart, passing arguments to it.
Restart must be valid in the current dynamic environment.

Examples::
..........

      (defun add3 (x) (check-type x number) (+ x 3))

      (foo 'seven)
      |>  Error: The value SEVEN was not of type NUMBER.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Specify a different value to use.
      |>   2: Return to Lisp Toplevel.
      |>  Debug> |>>(invoke-restart 'store-value 7)<<|
     =>  10

Side Effects::
..............

A non-local transfer of control might be done by the restart.

Affected By::
.............

Existing restarts.

Exceptional Situations::
........................

If restart is not valid, an error of type control-error is signaled.

See Also::
..........

*note find-restart:: , *note restart-bind:: , *note restart-case:: ,
*note invoke-restart-interactively::

Notes::
.......

The most common use for invoke-restart is in a handler.  It might be
used explicitly, or implicitly through invoke-restart-interactively or a
restart function.

   Restart functions call invoke-restart, not vice versa.  That is,
invoke-restart provides primitive functionality, and restart functions
are non-essential "syntactic sugar."


File: gcl.info,  Node: invoke-restart-interactively,  Next: restart-bind,  Prev: invoke-restart,  Up: Conditions Dictionary

9.2.35 invoke-restart-interactively [Function]
----------------------------------------------

'invoke-restart-interactively' restart => {result}*

Arguments and Values::
......................

restart--a restart designator.

   results--the values returned by the function associated with restart,
if that function returns.

Description::
.............

invoke-restart-interactively calls the function associated with restart,
prompting for any necessary arguments.  If restart is a name, it must be
valid in the current dynamic environment.

   invoke-restart-interactively prompts for arguments by executing the
code provided in the :interactive keyword to restart-case or
:interactive-function keyword to restart-bind.

   If no such options have been supplied in the corresponding
restart-bind or restart-case, then the consequences are undefined if the
restart takes required arguments.  If the arguments are optional, an
argument list of nil is used.

   Once the arguments have been determined, invoke-restart-interactively
executes the following:

      (apply #'invoke-restart restart arguments)

Examples::
..........

      (defun add3 (x) (check-type x number) (+ x 3))

      (add3 'seven)
      |>  Error: The value SEVEN was not of type NUMBER.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Specify a different value to use.
      |>   2: Return to Lisp Toplevel.
      |>  Debug> |>>(invoke-restart-interactively 'store-value)<<|
      |>  Type a form to evaluate and use: |>>7<<|
     =>  10

Side Effects::
..............

If prompting for arguments is necesary, some typeout may occur (on query
I/O).

   A non-local transfer of control might be done by the restart.

Affected By::
.............

*query-io*, active restarts

Exceptional Situations::
........................

If restart is not valid, an error of type control-error is signaled.

See Also::
..........

*note find-restart:: , *note invoke-restart:: , *note restart-case:: ,
*note restart-bind::

Notes::
.......

invoke-restart-interactively is used internally by the debugger and may
also be useful in implementing other portable, interactive debugging
tools.


File: gcl.info,  Node: restart-bind,  Next: restart-case,  Prev: invoke-restart-interactively,  Up: Conditions Dictionary

9.2.36 restart-bind [Macro]
---------------------------

'restart-bind' ({(name function {!key-val-pair}*)}) {form}*
=> {result}*

   key-val-pair ::=:interactive-function interactive-function | 
                 :report-function report-function | 
                 :test-function test-function

Arguments and Values::
......................

name--a symbol; not evaluated.

   function--a form; evaluated.

   forms--an implicit progn.

   interactive-function--a form; evaluated.

   report-function--a form; evaluated.

   test-function--a form; evaluated.

   results--the values returned by the forms.

Description::
.............

restart-bind executes the body of forms in a dynamic environment where
restarts with the given names are in effect.

   If a name is nil, it indicates an anonymous restart; if a name is a
non-nil symbol, it indicates a named restart.

   The function, interactive-function, and report-function are
unconditionally evaluated in the current lexical and dynamic environment
prior to evaluation of the body.  Each of these forms must evaluate to a
function.

   If invoke-restart is done on that restart, the function which
resulted from evaluating function is called, in the dynamic environment
of the invoke-restart, with the arguments given to invoke-restart.  The
function may either perform a non-local transfer of control or may
return normally.

   If the restart is invoked interactively from the debugger (using
invoke-restart-interactively), the arguments are defaulted by calling
the function which resulted from evaluating interactive-function.  That
function may optionally prompt interactively on query I/O, and should
return a list of arguments to be used by invoke-restart-interactively
when invoking the restart.

   If a restart is invoked interactively but no interactive-function is
used, then an argument list of nil is used.  In that case, the function
must be compatible with an empty argument list.

   If the restart is presented interactively (e.g., by the debugger),
the presentation is done by calling the function which resulted from
evaluating report-function.  This function must be a function of one
argument, a stream.  It is expected to print a description of the action
that the restart takes to that stream.  This function is called any time
the restart is printed while *print-escape* is nil.

   In the case of interactive invocation, the result is dependent on the
value of :interactive-function as follows.

:interactive-function
     Value is evaluated in the current lexical environment and should
     return a function of no arguments which constructs a list of
     arguments to be used by invoke-restart-interactively when invoking
     this restart.  The function may prompt interactively using query
     I/O if necessary.

:report-function
     Value is evaluated in the current lexical environment and should
     return a function of one argument, a stream, which prints on the
     stream a summary of the action that this restart takes.  This
     function is called whenever the restart is reported (printed while
     *print-escape* is nil).  If no :report-function option is provided,
     the manner in which the restart is reported is
     implementation-dependent.

:test-function
     Value is evaluated in the current lexical environment and should
     return a function of one argument, a condition, which returns true
     if the restart is to be considered visible.

Affected By::
.............

*query-io*.

See Also::
..........

*note restart-case:: , *note with-simple-restart::

Notes::
.......

restart-bind is primarily intended to be used to implement restart-case
and might be useful in implementing other macros.  Programmers who are
uncertain about whether to use restart-case or restart-bind should
prefer restart-case for the cases where it is powerful enough, using
restart-bind only in cases where its full generality is really needed.


File: gcl.info,  Node: restart-case,  Next: restart-name,  Prev: restart-bind,  Up: Conditions Dictionary

9.2.37 restart-case [Macro]
---------------------------

'restart-case' restartable-form {!clause} => {result}*

   clause ::=( case-name lambda-list 
            [[:interactive interactive-expression | :report report-expression | :test test-expression]] 
            {declaration}* {form}*)

Arguments and Values::
......................

restartable-form--a form.

   case-name--a symbol or nil.

   lambda-list--an ordinary lambda list.

   interactive-expression--a symbol or a lambda expression.

   report-expression--a string, a symbol, or a lambda expression.

   test-expression--a symbol or a lambda expression.

   declaration--a declare expression; not evaluated.

   form--a form.

   results--the values resulting from the evaluation of
restartable-form, or the values returned by the last form executed in a
chosen clause, or nil.

Description::
.............

restart-case evaluates restartable-form in a dynamic environment where
the clauses have special meanings as points to which control may be
transferred.  If restartable-form finishes executing and returns any
values, all values returned are returned by restart-case and processing
has completed.  While restartable-form is executing, any code may
transfer control to one of the clauses (see invoke-restart).  If a
transfer occurs, the forms in the body of that clause is evaluated and
any values returned by the last such form are returned by restart-case.
In this case, the dynamic state is unwound appropriately (so that the
restarts established around the restartable-form are no longer active)
prior to execution of the clause.

   If there are no forms in a selected clause, restart-case returns nil.

   If case-name is a symbol, it names this restart.

   It is possible to have more than one clause use the same case-name.
In this case, the first clause with that name is found by find-restart.
The other clauses are accessible using compute-restarts.

   Each arglist is an ordinary lambda list to be bound during the
execution of its corresponding forms.  These parameters are used by the
restart-case clause to receive any necessary data from a call to
invoke-restart.

   By default, invoke-restart-interactively passes no arguments and all
arguments must be optional in order to accomodate interactive
restarting.  However, the arguments need not be optional if the
:interactive keyword has been used to inform
invoke-restart-interactively about how to compute a proper argument
list.

   Keyword options have the following meaning.

:interactive
     The value supplied by :interactive value must be a suitable
     argument to function.  (function value) is evaluated in the current
     lexical environment.  It should return a function of no arguments
     which returns arguments to be used by invoke-restart-interactively
     when it is invoked.  invoke-restart-interactively is called in the
     dynamic environment available prior to any restart attempt, and
     uses query I/O for user interaction.

     If a restart is invoked interactively but no :interactive option
     was supplied, the argument list used in the invocation is the empty
     list.

:report
     If the value supplied by :report value is a lambda expression or a
     symbol, it must be acceptable to function.  (function value) is
     evaluated in the current lexical environment.  It should return a
     function of one argument, a stream, which prints on the stream a
     description of the restart.  This function is called whenever the
     restart is printed while *print-escape* is nil.

     If value is a string, it is a shorthand for

           (lambda (stream) (write-string value stream))

     If a named restart is asked to report but no report information has
     been supplied, the name of the restart is used in generating
     default report text.

     When *print-escape* is nil, the printer uses the report information
     for a restart.  For example, a debugger might announce the action
     of typing a "continue" command by:

           (format t "~&~S -- ~A~

     which might then display as something like:

           :CONTINUE -- Return to command level

     The consequences are unspecified if an unnamed restart is specified
     but no :report option is provided.

:test
     The value supplied by :test value must be a suitable argument to
     function.  (function value) is evaluated in the current lexical
     environment.  It should return a function of one argument, the
     condition, that returns true if the restart is to be considered
     visible.

     The default for this option is equivalent to (lambda (c) (declare
     (ignore c)) t).

   If the restartable-form is a list whose car is any of the symbols
signal, error, cerror, or warn (or is a macro form which macroexpands
into such a list), then with-condition-restarts is used implicitly to
associate the indicated restarts with the condition to be signaled.

Examples::
..........

      (restart-case
          (handler-bind ((error #'(lambda (c)
                                  (declare (ignore condition))
                                  (invoke-restart 'my-restart 7))))
            (error "Foo."))
        (my-restart (&optional v) v))
     =>  7

      (define-condition food-error (error) ())
     =>  FOOD-ERROR
      (define-condition bad-tasting-sundae (food-error)
        ((ice-cream :initarg :ice-cream :reader bad-tasting-sundae-ice-cream)
         (sauce :initarg :sauce :reader bad-tasting-sundae-sauce)
         (topping :initarg :topping :reader bad-tasting-sundae-topping))
        (:report (lambda (condition stream)
                   (format stream "Bad tasting sundae with ~S, ~S, and ~S"
                           (bad-tasting-sundae-ice-cream condition)
                           (bad-tasting-sundae-sauce condition)
                           (bad-tasting-sundae-topping condition)))))
     =>  BAD-TASTING-SUNDAE
      (defun all-start-with-same-letter (symbol1 symbol2 symbol3)
        (let ((first-letter (char (symbol-name symbol1) 0)))
          (and (eql first-letter (char (symbol-name symbol2) 0))
               (eql first-letter (char (symbol-name symbol3) 0)))))
     =>  ALL-START-WITH-SAME-LETTER
      (defun read-new-value ()
        (format t "Enter a new value: ")
        (multiple-value-list (eval (read))))
     =>  READ-NEW-VALUE
      (defun verify-or-fix-perfect-sundae (ice-cream sauce topping)
        (do ()
           ((all-start-with-same-letter ice-cream sauce topping))
          (restart-case
            (error 'bad-tasting-sundae
                   :ice-cream ice-cream
                   :sauce sauce
                   :topping topping)
            (use-new-ice-cream (new-ice-cream)
              :report "Use a new ice cream."
              :interactive read-new-value
              (setq ice-cream new-ice-cream))
            (use-new-sauce (new-sauce)
              :report "Use a new sauce."
              :interactive read-new-value
              (setq sauce new-sauce))
            (use-new-topping (new-topping)
              :report "Use a new topping."
              :interactive read-new-value
              (setq topping new-topping))))
        (values ice-cream sauce topping))
     =>  VERIFY-OR-FIX-PERFECT-SUNDAE
      (verify-or-fix-perfect-sundae 'vanilla 'caramel 'cherry)
      |>  Error: Bad tasting sundae with VANILLA, CARAMEL, and CHERRY.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Use a new ice cream.
      |>   2: Use a new sauce.
      |>   3: Use a new topping.
      |>   4: Return to Lisp Toplevel.
      |>  Debug> |>>:continue 1<<|
      |>  Use a new ice cream.
      |>  Enter a new ice cream: |>>'chocolate<<|
     =>  CHOCOLATE, CARAMEL, CHERRY

See Also::
..........

*note restart-bind:: , *note with-simple-restart:: .

Notes::
.......

      (restart-case expression
         (name1 arglist1 ...options1... . body1)
         (name2 arglist2 ...options2... . body2))

   is essentially equivalent to

      (block #1=#:g0001
        (let ((#2=#:g0002 nil))
             (tagbody
             (restart-bind ((name1 #'(lambda (&rest temp)
                                     (setq #2# temp)
                                     (go #3=#:g0003))
                               ...slightly-transformed-options1...)
                            (name2 #'(lambda (&rest temp)
                                     (setq #2# temp)
                                     (go #4=#:g0004))
                               ...slightly-transformed-options2...))
             (return-from #1# expression))
               #3# (return-from #1#
                       (apply #'(lambda arglist1 . body1) #2#))
               #4# (return-from #1#
                       (apply #'(lambda arglist2 . body2) #2#)))))

   Unnamed restarts are generally only useful interactively and an
interactive option which has no description is of little value.
Implementations are encouraged to warn if an unnamed restart is used and
no report information is provided at compilation time.  At runtime, this
error might be noticed when entering the debugger.  Since signaling an
error would probably cause recursive entry into the debugger (causing
yet another recursive error, etc.)  it is suggested that the debugger
print some indication of such problems when they occur but not actually
signal errors.

      (restart-case (signal fred)
        (a ...)
        (b ...))
      ==
      (restart-case
          (with-condition-restarts fred
                                   (list (find-restart 'a)
                                         (find-restart 'b))
            (signal fred))
        (a ...)
        (b ...))


File: gcl.info,  Node: restart-name,  Next: with-condition-restarts,  Prev: restart-case,  Up: Conditions Dictionary

9.2.38 restart-name [Function]
------------------------------

'restart-name' restart => name

Arguments and Values::
......................

restart--a restart.

   name--a symbol.

Description::
.............

Returns the name of the restart, or nil if the restart is not named.

Examples::
..........

      (restart-case
          (loop for restart in (compute-restarts)
                    collect (restart-name restart))
        (case1 () :report "Return 1." 1)
        (nil   () :report "Return 2." 2)
        (case3 () :report "Return 3." 3)
        (case1 () :report "Return 4." 4))
     =>  (CASE1 NIL CASE3 CASE1 ABORT)
      ;; In the example above the restart named ABORT was not created
      ;; explicitly, but was implicitly supplied by the system.

See Also::
..........

*note compute-restarts::

   *note find-restart::


File: gcl.info,  Node: with-condition-restarts,  Next: with-simple-restart,  Prev: restart-name,  Up: Conditions Dictionary

9.2.39 with-condition-restarts [Macro]
--------------------------------------

'with-condition-restarts' condition-form restarts-form {form}*
=> {result}*

Arguments and Values::
......................

condition-form--a form; evaluated to produce a condition.

   condition--a condition object resulting from the evaluation of
condition-form.

   restart-form--a form; evaluated to produce a restart-list.

   restart-list--a list of restart objects resulting from the evaluation
of restart-form.

   forms--an implicit progn; evaluated.

   results--the values returned by forms.

Description::
.............

First, the condition-form and restarts-form are evaluated in normal
left-to-right order; the primary values yielded by these evaluations are
respectively called the condition and the restart-list.

   Next, the forms are evaluated in a dynamic environment in which each
restart in restart-list is associated with the condition.  See *note
Associating a Restart with a Condition::.

See Also::
..........

*note restart-case::

Notes::
.......

Usually this macro is not used explicitly in code, since restart-case
handles most of the common cases in a way that is syntactically more
concise.


File: gcl.info,  Node: with-simple-restart,  Next: abort (Restart),  Prev: with-condition-restarts,  Up: Conditions Dictionary

9.2.40 with-simple-restart [Macro]
----------------------------------

'with-simple-restart' (name format-control {format-argument}*) {form}*
=> {result}*

Arguments and Values::
......................

name--a symbol.

   format-control--a format control.

   format-argument--an object (i.e., a format argument).

   forms--an implicit progn.

   results--in the normal situation, the values returned by the forms;
in the exceptional situation where the restart named name is invoked,
two values--nil and t.

Description::
.............

with-simple-restart establishes a restart.

   If the restart designated by name is not invoked while executing
forms, all values returned by the last of forms are returned.  If the
restart designated by name is invoked, control is transferred to
with-simple-restart, which returns two values, nil and t.

   If name is nil, an anonymous restart is established.

   The format-control and format-arguments are used report the restart.

Examples::
..........

      (defun read-eval-print-loop (level)
        (with-simple-restart (abort "Exit command level ~D." level)
          (loop
            (with-simple-restart (abort "Return to command level ~D." level)
              (let ((form (prog2 (fresh-line) (read) (fresh-line))))
                (prin1 (eval form)))))))
     =>  READ-EVAL-PRINT-LOOP
      (read-eval-print-loop 1)
      (+ 'a 3)
      |>  Error: The argument, A, to the function + was of the wrong type.
      |>         The function expected a number.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Specify a value to use this time.
      |>   2: Return to command level 1.
      |>   3: Exit command level 1.
      |>   4: Return to Lisp Toplevel.

      (defun compute-fixnum-power-of-2 (x)
        (with-simple-restart (nil "Give up on computing 2^~D." x)
          (let ((result 1))
            (dotimes (i x result)
              (setq result (* 2 result))
              (unless (fixnump result)
                (error "Power of 2 is too large."))))))
     COMPUTE-FIXNUM-POWER-OF-2
      (defun compute-power-of-2 (x)
        (or (compute-fixnum-power-of-2 x) 'something big))
     COMPUTE-POWER-OF-2
      (compute-power-of-2 10)
     1024
      (compute-power-of-2 10000)
      |>  Error: Power of 2 is too large.
      |>  To continue, type :CONTINUE followed by an option number.
      |>   1: Give up on computing 2^10000.
      |>   2: Return to Lisp Toplevel
      |>  Debug> |>>:continue 1<<|
     =>  SOMETHING-BIG

See Also::
..........

*note restart-case::

Notes::
.......

with-simple-restart is shorthand for one of the most common uses of
restart-case.

   with-simple-restart could be defined by:

      (defmacro with-simple-restart ((restart-name format-control
                                                   &rest format-arguments)
                                     &body forms)
        `(restart-case (progn ,@forms)
           (,restart-name ()
               :report (lambda (stream)
                         (format stream ,format-control ,@format-arguments))
              (values nil t))))

   Because the second return value is t in the exceptional case, it is
common (but not required) to arrange for the second return value in the
normal case to be missing or nil so that the two situations can be
distinguished.


File: gcl.info,  Node: abort (Restart),  Next: continue,  Prev: with-simple-restart,  Up: Conditions Dictionary

9.2.41 abort [Restart]
----------------------

Data Arguments Required::
.........................

None.

Description::
.............

The intent of the abort restart is to allow return to the innermost
"command level."  Implementors are encouraged to make sure that there is
always a restart named abort around any user code so that user code can
call abort at any time and expect something reasonable to happen;
exactly what the reasonable thing is may vary somewhat.  Typically, in
an interactive listener, the invocation of abort returns to the Lisp
reader phase of the Lisp read-eval-print loop, though in some batch or
multi-processing situations there may be situations in which having it
kill the running process is more appropriate.

See Also::
..........

*note Restarts::, *note Interfaces to Restarts::, *note invoke-restart::
, *note abort (Function):: (function)


File: gcl.info,  Node: continue,  Next: muffle-warning,  Prev: abort (Restart),  Up: Conditions Dictionary

9.2.42 continue [Restart]
-------------------------

Data Arguments Required::
.........................

None.

Description::
.............

The continue restart is generally part of protocols where there is a
single "obvious" way to continue, such as in break and cerror.  Some
user-defined protocols may also wish to incorporate it for similar
reasons.  In general, however, it is more reliable to design a special
purpose restart with a name that more directly suits the particular
application.

Examples::
..........

      (let ((x 3))
        (handler-bind ((error #'(lambda (c)
                                  (let ((r (find-restart 'continue c)))
                                    (when r (invoke-restart r))))))
          (cond ((not (floatp x))
                 (cerror "Try floating it." "~D is not a float." x)
                 (float x))
                (t x)))) =>  3.0

See Also::
..........

*note Restarts::, *note Interfaces to Restarts::, *note invoke-restart::
, *note continue:: (function), *note assert:: , *note cerror::


File: gcl.info,  Node: muffle-warning,  Next: store-value,  Prev: continue,  Up: Conditions Dictionary

9.2.43 muffle-warning [Restart]
-------------------------------

Data Arguments Required::
.........................

None.

Description::
.............

This restart is established by warn so that handlers of warning
conditions have a way to tell warn that a warning has already been dealt
with and that no further action is warranted.

Examples::
..........

      (defvar *all-quiet* nil) =>  *ALL-QUIET*
      (defvar *saved-warnings* '()) =>  *SAVED-WARNINGS*
      (defun quiet-warning-handler (c)
        (when *all-quiet*
          (let ((r (find-restart 'muffle-warning c)))
            (when r
              (push c *saved-warnings*)
              (invoke-restart r)))))
     =>  CUSTOM-WARNING-HANDLER
      (defmacro with-quiet-warnings (&body forms)
        `(let ((*all-quiet* t)
               (*saved-warnings* '()))
           (handler-bind ((warning #'quiet-warning-handler))
             ,@forms
             *saved-warnings*)))
     =>  WITH-QUIET-WARNINGS
      (setq saved
        (with-quiet-warnings
          (warn "Situation #1.")
          (let ((*all-quiet* nil))
            (warn "Situation #2."))
          (warn "Situation #3.")))
      |>  Warning: Situation #2.
     =>  (#<SIMPLE-WARNING 42744421> #<SIMPLE-WARNING 42744365>)
      (dolist (s saved) (format t "~&~A~
      |>  Situation #3.
      |>  Situation #1.
     =>  NIL

See Also::
..........

*note Restarts::, *note Interfaces to Restarts::, *note invoke-restart::
, *note muffle-warning:: (function), *note warn::


File: gcl.info,  Node: store-value,  Next: use-value,  Prev: muffle-warning,  Up: Conditions Dictionary

9.2.44 store-value [Restart]
----------------------------

Data Arguments Required::
.........................

a value to use instead (on an ongoing basis).

Description::
.............

The store-value restart is generally used by handlers trying to recover
from errors of types such as cell-error or type-error, which may wish to
supply a replacement datum to be stored permanently.

Examples::
..........

      (defun type-error-auto-coerce (c)
        (when (typep c 'type-error)
          (let ((r (find-restart 'store-value c)))
            (handler-case (let ((v (coerce (type-error-datum c)
                                           (type-error-expected-type c))))
                            (invoke-restart r v))
              (error ()))))) =>  TYPE-ERROR-AUTO-COERCE
      (let ((x 3))
        (handler-bind ((type-error #'type-error-auto-coerce))
          (check-type x float)
          x)) =>  3.0

See Also::
..........

*note Restarts::, *note Interfaces to Restarts::, *note invoke-restart::
, *note store-value:: (function), ccase, *note check-type:: , ctypecase,
*note use-value:: (function and restart)


File: gcl.info,  Node: use-value,  Next: abort (Function),  Prev: store-value,  Up: Conditions Dictionary

9.2.45 use-value [Restart]
--------------------------

Data Arguments Required::
.........................

a value to use instead (once).

Description::
.............

The use-value restart is generally used by handlers trying to recover
from errors of types such as cell-error, where the handler may wish to
supply a replacement datum for one-time use.

See Also::
..........

*note Restarts::, *note Interfaces to Restarts::, *note invoke-restart::
, *note use-value:: (function), *note store-value:: (function and
restart)


File: gcl.info,  Node: abort (Function),  Prev: use-value,  Up: Conditions Dictionary

9.2.46 abort, continue, muffle-warning, store-value, use-value [Function]
-------------------------------------------------------------------------

'abort' &optional condition => #<NoValue>

   'continue' &optional condition => nil

   'muffle-warning' &optional condition => #<NoValue>

   'store-value' value &optional condition => nil

   'use-value' value &optional condition => nil

Arguments and Values::
......................

value--an object.

   condition--a condition object, or nil.

Description::
.............

Transfers control to the most recently established applicable restart
having the same name as the function.  That is, the function abort
searches for an applicable abort restart, the function continue searches
for an applicable continue restart, and so on.

   If no such restart exists, the functions continue, store-value, and
use-value return nil, and the functions abort and muffle-warning signal
an error of type control-error.

   When condition is non-nil, only those restarts are considered that
are either explicitly associated with that condition, or not associated
with any condition; that is, the excluded restarts are those that are
associated with a non-empty set of conditions of which the given
condition is not an element.  If condition is nil, all restarts are
considered.

Examples::
..........

     ;;; Example of the ABORT retart

      (defmacro abort-on-error (&body forms)
        `(handler-bind ((error #'abort))
           ,@forms)) =>  ABORT-ON-ERROR
      (abort-on-error (+ 3 5)) =>  8
      (abort-on-error (error "You lose."))
      |>  Returned to Lisp Top Level.

     ;;; Example of the CONTINUE restart

      (defun real-sqrt (n)
        (when (minusp n)
          (setq n (- n))
          (cerror "Return sqrt(~D) instead." "Tried to take sqrt(-~D)." n))
        (sqrt n))

      (real-sqrt 4) =>  2
      (real-sqrt -9)
      |>  Error: Tried to take sqrt(-9).
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Return sqrt(9) instead.
      |>   2: Return to Lisp Toplevel.
      |>  Debug> |>>(continue)<<|
      |>  Return sqrt(9) instead.
     =>  3

      (handler-bind ((error #'(lambda (c) (continue))))
        (real-sqrt -9)) =>  3

     ;;; Example of the MUFFLE-WARNING restart

      (defun count-down (x)
        (do ((counter x (1- counter)))
            ((= counter 0) 'done)
          (when (= counter 1)
            (warn "Almost done"))
          (format t "~&~D~
     =>  COUNT-DOWN
      (count-down 3)
      |>  3
      |>  2
      |>  Warning: Almost done
      |>  1
     =>  DONE
      (defun ignore-warnings-while-counting (x)
        (handler-bind ((warning #'ignore-warning))
          (count-down x)))
     =>  IGNORE-WARNINGS-WHILE-COUNTING
      (defun ignore-warning (condition)
        (declare (ignore condition))
        (muffle-warning))
     =>  IGNORE-WARNING
      (ignore-warnings-while-counting 3)
      |>  3
      |>  2
      |>  1
     =>  DONE

     ;;; Example of the STORE-VALUE and USE-VALUE restarts

      (defun careful-symbol-value (symbol)
        (check-type symbol symbol)
        (restart-case (if (boundp symbol)
                          (return-from careful-symbol-value
                                       (symbol-value symbol))
                          (error 'unbound-variable
                                 :name symbol))
          (use-value (value)
            :report "Specify a value to use this time."
            value)
          (store-value (value)
            :report "Specify a value to store and use in the future."
            (setf (symbol-value symbol) value))))
      (setq a 1234) =>  1234
      (careful-symbol-value 'a) =>  1234
      (makunbound 'a) =>  A
      (careful-symbol-value 'a)
      |>  Error: A is not bound.
      |>  To continue, type :CONTINUE followed by an option number.
      |>   1: Specify a value to use this time.
      |>   2: Specify a value to store and use in the future.
      |>   3: Return to Lisp Toplevel.
      |>  Debug> |>>(use-value 12)<<|
     =>  12
      (careful-symbol-value 'a)
      |>  Error: A is not bound.
      |>  To continue, type :CONTINUE followed by an option number.
      |>    1: Specify a value to use this time.
      |>    2: Specify a value to store and use in the future.
      |>    3: Return to Lisp Toplevel.
      |>  Debug> |>>(store-value 24)<<|
     =>  24
      (careful-symbol-value 'a)
     =>  24

     ;;; Example of the USE-VALUE restart

      (defun add-symbols-with-default (default &rest symbols)
        (handler-bind ((sys:unbound-symbol
                         #'(lambda (c)
                             (declare (ignore c))
                             (use-value default))))
          (apply #'+ (mapcar #'careful-symbol-value symbols))))
     =>  ADD-SYMBOLS-WITH-DEFAULT
      (setq x 1 y 2) =>  2
      (add-symbols-with-default 3 'x 'y 'z) =>  6


Side Effects::
..............

A transfer of control may occur if an appropriate restart is available,
or (in the case of the function abort or the function muffle-warning)
execution may be stopped.

Affected By::
.............

Each of these functions can be affected by the presence of a restart
having the same name.

Exceptional Situations::
........................

If an appropriate abort restart is not available for the function abort,
or an appropriate muffle-warning restart is not available for the
function muffle-warning, an error of type control-error is signaled.

See Also::
..........

*note invoke-restart:: , *note Restarts::, *note Interfaces to
Restarts::, *note assert:: , ccase, *note cerror:: , *note check-type::
, ctypecase, *note use-value:: , *note warn::

Notes::
.......

      (abort condition) == (invoke-restart 'abort)
      (muffle-warning)  == (invoke-restart 'muffle-warning)
      (continue)        == (let ((r (find-restart 'continue))) (if r (invoke-restart r)))
      (use-value x) == (let ((r (find-restart 'use-value))) (if r (invoke-restart r x)))
      (store-value x) == (let ((r (find-restart 'store-value))) (if r (invoke-restart r x)))

   No functions defined in this specification are required to provide a
use-value restart.


File: gcl.info,  Node: Symbols,  Next: Packages,  Prev: Conditions,  Up: Top

10 Symbols
**********

* Menu:

* Symbol Concepts::
* Symbols Dictionary::


File: gcl.info,  Node: Symbol Concepts,  Next: Symbols Dictionary,  Prev: Symbols,  Up: Symbols

10.1 Symbol Concepts
====================

Figure 10-1 lists some defined names that are applicable to the property
lists of symbols.

  get  remprop  symbol-plist  

  Figure 10-1: Property list defined names


   Figure 10-2 lists some defined names that are applicable to the
creation of and inquiry about symbols.

  copy-symbol  keywordp     symbol-package  
  gensym       make-symbol  symbol-value    
  gentemp      symbol-name                  

  Figure 10-2: Symbol creation and inquiry defined names



File: gcl.info,  Node: Symbols Dictionary,  Prev: Symbol Concepts,  Up: Symbols

10.2 Symbols Dictionary
=======================

* Menu:

* symbol::
* keyword::
* symbolp::
* keywordp::
* make-symbol::
* copy-symbol::
* gensym::
* *gensym-counter*::
* gentemp::
* symbol-function::
* symbol-name::
* symbol-package::
* symbol-plist::
* symbol-value::
* get::
* remprop::
* boundp::
* makunbound::
* set::
* unbound-variable::


File: gcl.info,  Node: symbol,  Next: keyword,  Prev: Symbols Dictionary,  Up: Symbols Dictionary

10.2.1 symbol [System Class]
----------------------------

Class Precedence List::
.......................

symbol, t

Description::
.............

Symbols are used for their object identity to name various entities in
Common Lisp, including (but not limited to) linguistic entities such as
variables and functions.

   Symbols can be collected together into packages.  A symbol is said to
be interned in a package if it is accessible in that package; the same
symbol can be interned in more than one package.  If a symbol is not
interned in any package, it is called uninterned.

   An interned symbol is uniquely identifiable by its name from any
package in which it is accessible.

   Symbols have the following attributes.  For historically reasons,
these are sometimes referred to as cells, although the actual internal
representation of symbols and their attributes is
implementation-dependent.

Name
     The name of a symbol is a string used to identify the symbol.
     Every symbol has a name,

     and the consequences are undefined if that name is altered.

     The name is used as part of the external, printed representation of
     the symbol; see *note Character Syntax::.  The function symbol-name
     returns the name of a given symbol.

     A symbol may have any character in its name.

Package
     The object in this cell is called the home package of the symbol.
     If the home package is nil, the symbol is sometimes said to have no
     home package.

     When a symbol is first created, it has no home package.  When it is
     first interned, the package in which it is initially interned
     becomes its home package.  The home package of a symbol can be
     accessed by using the function symbol-package.

     If a symbol is uninterned from the package which is its home
     package, its home package is set to nil.  Depending on whether
     there is another package in which the symbol is interned, the
     symbol might or might not really be an uninterned symbol.  A symbol
     with no home package is therefore called apparently uninterned.

     The consequences are undefined if an attempt is made to alter the
     home package of a symbol external in the COMMON-LISP package or the
     KEYWORD package.

Property list
     The property list of a symbol provides a mechanism for associating
     named attributes with that symbol.  The operations for adding and
     removing entries are destructive to the property list.  Common Lisp
     provides operators both for direct manipulation of property list
     objects (e.g., see getf, remf, and symbol-plist) and for implicit
     manipulation of a symbol's property list by reference to the symbol
     (e.g., see get and remprop).  The property list associated with a
     fresh symbol is initially null.

Value
     If a symbol has a value attribute, it is said to be bound, and that
     fact can be detected by the function boundp.  The object contained
     in the value cell of a bound symbol is the value of the global
     variable named by that symbol, and can be accessed by the function
     symbol-value.  A symbol can be made to be unbound by the function
     makunbound.

     The consequences are undefined if an attempt is made to change the
     value of a symbol that names a constant variable, or to make such a
     symbol be unbound.

Function
     If a symbol has a function attribute, it is said to be fbound, and
     that fact can be detected by the function fboundp.  If the symbol
     is the name of a function in the global environment, the function
     cell contains the function, and can be accessed by the function
     symbol-function.  If the symbol is the name of either a macro in
     the global environment (see macro-function) or a special operator
     (see special-operator-p), the symbol is fbound, and can be accessed
     by the function symbol-function, but the object which the function
     cell contains is of implementation-dependent type and purpose.  A
     symbol can be made to be funbound by the function fmakunbound.

     The consequences are undefined if an attempt is made to change the
     functional value of a symbol that names a special form.

   Operations on a symbol's value cell and function cell are sometimes
described in terms of their effect on the symbol itself, but the user
should keep in mind that there is an intimate relationship between the
contents of those cells and the global variable or global function
definition, respectively.

   Symbols are used as identifiers for lexical variables and lexical
function definitions, but in that role, only their object identity is
significant.  Common Lisp provides no operation on a symbol that can
have any effect on a lexical variable or on a lexical function
definition.

See Also::
..........

*note Symbols as Tokens::, *note Potential Numbers as Tokens::, *note
Printing Symbols::


File: gcl.info,  Node: keyword,  Next: symbolp,  Prev: symbol,  Up: Symbols Dictionary

10.2.2 keyword [Type]
---------------------

Supertypes::
............

keyword, symbol, t

Description::
.............

The type keyword includes all symbols interned the KEYWORD package.

   Interning a symbol in the KEYWORD package has three automatic
effects:

1.
     It causes the symbol to become bound to itself.
2.
     It causes the symbol to become an external symbol of the KEYWORD
     package.
3.
     It causes the symbol to become a constant variable.

See Also::
..........

*note keywordp::


File: gcl.info,  Node: symbolp,  Next: keywordp,  Prev: keyword,  Up: Symbols Dictionary

10.2.3 symbolp [Function]
-------------------------

'symbolp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type symbol; otherwise, returns false.

Examples::
..........

      (symbolp 'elephant) =>  true
      (symbolp 12) =>  false
      (symbolp nil) =>  true
      (symbolp '()) =>  true
      (symbolp :test) =>  true
      (symbolp "hello") =>  false

See Also::
..........

*note keywordp:: , symbol, *note typep::

Notes::
.......

      (symbolp object) == (typep object 'symbol)


File: gcl.info,  Node: keywordp,  Next: make-symbol,  Prev: symbolp,  Up: Symbols Dictionary

10.2.4 keywordp [Function]
--------------------------

'keywordp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is a keyword_1; otherwise, returns false.

Examples::
..........

      (keywordp 'elephant) =>  false
      (keywordp 12) =>  false
      (keywordp :test) =>  true
      (keywordp ':test) =>  true
      (keywordp nil) =>  false
      (keywordp :nil) =>  true
      (keywordp '(:test)) =>  false
      (keywordp "hello") =>  false
      (keywordp ":hello") =>  false
      (keywordp '&optional) =>  false

See Also::
..........

*note constantp:: , *note keyword:: , *note symbolp:: , *note
symbol-package::


File: gcl.info,  Node: make-symbol,  Next: copy-symbol,  Prev: keywordp,  Up: Symbols Dictionary

10.2.5 make-symbol [Function]
-----------------------------

'make-symbol' name => new-symbol

Arguments and Values::
......................

name--a string.

   new-symbol--a fresh, uninterned symbol.

Description::
.............

make-symbol creates and returns a fresh, uninterned symbol whose name is
the given name.  The new-symbol is neither bound nor fbound and has a
null property list.

   It is implementation-dependent whether the string that becomes the
new-symbol's name is the given name or a copy of it.  Once a string has
been given as the name argument to make-symbol, the consequences are
undefined if a subsequent attempt is made to alter that string.

Examples::
..........

      (setq temp-string "temp") =>  "temp"
      (setq temp-symbol (make-symbol temp-string)) =>  #:|temp|
      (symbol-name temp-symbol) =>  "temp"
      (eq (symbol-name temp-symbol) temp-string) =>  implementation-dependent
      (find-symbol "temp") =>  NIL, NIL
      (eq (make-symbol temp-string) (make-symbol temp-string)) =>  false

Exceptional Situations::
........................

Should signal an error of type type-error if name is not a string.

See Also::
..........

*note copy-symbol::

Notes::
.......

No attempt is made by make-symbol to convert the case of the name to
uppercase.  The only case conversion which ever occurs for symbols is
done by the Lisp reader.  The program interface to symbol creation
retains case, and the program interface to interning symbols is
case-sensitive.


File: gcl.info,  Node: copy-symbol,  Next: gensym,  Prev: make-symbol,  Up: Symbols Dictionary

10.2.6 copy-symbol [Function]
-----------------------------

'copy-symbol' symbol &optional copy-properties => new-symbol

Arguments and Values::
......................

symbol--a symbol.

   copy-properties--a generalized boolean.  The default is false.

   new-symbol--a fresh, uninterned symbol.

Description::
.............

copy-symbol returns a fresh, uninterned symbol, the name of which is
string= to and possibly the same as the name of the given symbol.

   If copy-properties is false, the new-symbol is neither bound nor
fbound and has a null property list.  If copy-properties is true, then
the initial value of new-symbol is the value of symbol, the initial
function definition of new-symbol is the functional value of symbol, and
the property list of new-symbol is

   a copy_2 of the property list of symbol.

Examples::
..........

      (setq fred 'fred-smith) =>  FRED-SMITH
      (setf (symbol-value fred) 3) =>  3
      (setq fred-clone-1a (copy-symbol fred nil)) =>  #:FRED-SMITH
      (setq fred-clone-1b (copy-symbol fred nil)) =>  #:FRED-SMITH
      (setq fred-clone-2a (copy-symbol fred t))   =>  #:FRED-SMITH
      (setq fred-clone-2b (copy-symbol fred t))   =>  #:FRED-SMITH
      (eq fred fred-clone-1a) =>  false
      (eq fred-clone-1a fred-clone-1b) =>  false
      (eq fred-clone-2a fred-clone-2b) =>  false
      (eq fred-clone-1a fred-clone-2a) =>  false
      (symbol-value fred) =>  3
      (boundp fred-clone-1a) =>  false
      (symbol-value fred-clone-2a) =>  3
      (setf (symbol-value fred-clone-2a) 4) =>  4
      (symbol-value fred) =>  3
      (symbol-value fred-clone-2a) =>  4
      (symbol-value fred-clone-2b) =>  3
      (boundp fred-clone-1a) =>  false
      (setf (symbol-function fred) #'(lambda (x) x)) =>  #<FUNCTION anonymous>
      (fboundp fred) =>  true
      (fboundp fred-clone-1a) =>  false
      (fboundp fred-clone-2a) =>  false

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.

See Also::
..........

*note make-symbol::

Notes::
.......

Implementors are encouraged not to copy the string which is the symbol's
name unnecessarily.  Unless there is a good reason to do so, the normal
implementation strategy is for the new-symbol's name to be identical to
the given symbol's name.


File: gcl.info,  Node: gensym,  Next: *gensym-counter*,  Prev: copy-symbol,  Up: Symbols Dictionary

10.2.7 gensym [Function]
------------------------

'gensym' &optional x => new-symbol

Arguments and Values::
......................

x--a string or a non-negative integer. 	Complicated defaulting behavior;
see below.

   new-symbol--a fresh, uninterned symbol.

Description::
.............

Creates and returns a fresh, uninterned symbol, as if by calling
make-symbol.  (The only difference between gensym and make-symbol is in
how the new-symbol's name is determined.)

   The name of the new-symbol is the concatenation of a prefix, which
defaults to "G", and

   a suffix, which is the decimal representation of a number that
defaults to the value of *gensym-counter*.

   If x is supplied, and is a string, then that string is used as a
prefix instead of "G" for this call to gensym only.

   If x is supplied, and is an integer, then that integer, instead of
the value of *gensym-counter*, is used as the suffix for this call to
gensym only.

   If and only if no explicit suffix is supplied, *gensym-counter* is
incremented after it is used.

Examples::
..........

      (setq sym1 (gensym)) =>  #:G3142
      (symbol-package sym1) =>  NIL
      (setq sym2 (gensym 100)) =>  #:G100
      (setq sym3 (gensym 100)) =>  #:G100
      (eq sym2 sym3) =>  false
      (find-symbol "G100") =>  NIL, NIL
      (gensym "T") =>  #:T3143
      (gensym) =>  #:G3144

Side Effects::
..............

Might increment *gensym-counter*.

Affected By::
.............

*gensym-counter*

Exceptional Situations::
........................

Should signal an error of type type-error if x is not a string or a
non-negative integer.

See Also::
..........

*note gentemp:: , *gensym-counter*

Notes::
.......

The ability to pass a numeric argument to gensym has been deprecated;
explicitly binding *gensym-counter* is now stylistically preferred.
(The somewhat baroque conventions for the optional argument are
historical in nature, and supported primarily for compatibility with
older dialects of Lisp.  In modern code, it is recommended that the only
kind of argument used be a string prefix.  In general, though, to obtain
more flexible control of the new-symbol's name, consider using
make-symbol instead.)


File: gcl.info,  Node: *gensym-counter*,  Next: gentemp,  Prev: gensym,  Up: Symbols Dictionary

10.2.8 *gensym-counter* [Variable]
----------------------------------

Value Type::
............

a non-negative integer.

Initial Value::
...............

implementation-dependent.

Description::
.............

A number which will be used in constructing the name of the next symbol
generated by the function gensym.

   *gensym-counter* can be either assigned or bound at any time, but its
value must always be a non-negative integer.

Affected By::
.............

gensym.

See Also::
..........

*note gensym::

Notes::
.......

The ability to pass a numeric argument to gensym has been deprecated;
explicitly binding *gensym-counter* is now stylistically preferred.


File: gcl.info,  Node: gentemp,  Next: symbol-function,  Prev: *gensym-counter*,  Up: Symbols Dictionary

10.2.9 gentemp [Function]
-------------------------

'gentemp' &optional prefix package => new-symbol

Arguments and Values::
......................

prefix--a string.  The default is "T".

   package--a package designator.  The default is the current package.

   new-symbol--a fresh, interned symbol.

Description::
.............

gentemp creates and returns a fresh symbol, interned in the indicated
package.  The symbol is guaranteed to be one that was not previously
accessible in package.  It is neither bound nor fbound, and has a null
property list.

   The name of the new-symbol is the concatenation of the prefix and a
suffix, which is taken from an internal counter used only by gentemp.
(If a symbol by that name is already accessible in package, the counter
is incremented as many times as is necessary to produce a name that is
not already the name of a symbol accessible in package.)

Examples::
..........

      (gentemp) =>  T1298
      (gentemp "FOO") =>  FOO1299
      (find-symbol "FOO1300") =>  NIL, NIL
      (gentemp "FOO") =>  FOO1300
      (find-symbol "FOO1300") =>  FOO1300, :INTERNAL
      (intern "FOO1301") =>  FOO1301, :INTERNAL
      (gentemp "FOO") =>  FOO1302
      (gentemp) =>  T1303

Side Effects::
..............

Its internal counter is incremented one or more times.

   Interns the new-symbol in package.

Affected By::
.............

The current state of its internal counter, and the current state of the
package.

Exceptional Situations::
........................

Should signal an error of type type-error if prefix is not a string.
Should signal an error of type type-error if package is not a package
designator.

See Also::
..........

*note gensym::

Notes::
.......

The function gentemp is deprecated.

   If package is the KEYWORD package, the result is an external symbol
of package.  Otherwise, the result is an internal symbol of package.

   The gentemp internal counter is independent of *gensym-counter*, the
counter used by gensym.  There is no provision for accessing the gentemp
internal counter.

   Just because gentemp creates a symbol which did not previously exist
does not mean that such a symbol might not be seen in the future (e.g.,
in a data file--perhaps even created by the same program in another
session).  As such, this symbol is not truly unique in the same sense as
a gensym would be.  In particular, programs which do automatic code
generation should be careful not to attach global attributes to such
generated symbols (e.g., special declarations) and then write them into
a file because such global attributes might, in a different session, end
up applying to other symbols that were automatically generated on
another day for some other purpose.


File: gcl.info,  Node: symbol-function,  Next: symbol-name,  Prev: gentemp,  Up: Symbols Dictionary

10.2.10 symbol-function [Accessor]
----------------------------------

'symbol-function' symbol => contents

   (setf (' symbol-function' symbol) new-contents)

Arguments and Values::
......................

symbol--a symbol.

   contents--

   If the symbol is globally defined as a macro or a special operator,
an object of implementation-dependent nature and identity is returned.
If the symbol is not globally defined as either a macro or a special
operator, and if the symbol is fbound, a function object is returned.

   new-contents--a function.

Description::
.............

Accesses the symbol's function cell.

Examples::
..........

      (symbol-function 'car) =>  #<FUNCTION CAR>
      (symbol-function 'twice) is an error   ;because TWICE isn't defined.
      (defun twice (n) (* n 2)) =>  TWICE
      (symbol-function 'twice) =>  #<FUNCTION TWICE>
      (list (twice 3)
            (funcall (function twice) 3)
            (funcall (symbol-function 'twice) 3))
     =>  (6 6 6)
      (flet ((twice (x) (list x x)))
        (list (twice 3)
              (funcall (function twice) 3)
              (funcall (symbol-function 'twice) 3)))
     =>  ((3 3) (3 3) 6)
      (setf (symbol-function 'twice) #'(lambda (x) (list x x)))
     =>  #<FUNCTION anonymous>
      (list (twice 3)
            (funcall (function twice) 3)
            (funcall (symbol-function 'twice) 3))
     =>  ((3 3) (3 3) (3 3))
      (fboundp 'defun) =>  true
      (symbol-function 'defun)
     =>  implementation-dependent
      (functionp (symbol-function 'defun))
     =>  implementation-dependent
      (defun symbol-function-or-nil (symbol)
        (if (and (fboundp symbol)
                 (not (macro-function symbol))
                 (not (special-operator-p symbol)))
            (symbol-function symbol)
            nil)) =>  SYMBOL-FUNCTION-OR-NIL
      (symbol-function-or-nil 'car) =>  #<FUNCTION CAR>
      (symbol-function-or-nil 'defun) =>  NIL

Affected By::
.............

defun

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.

   Should signal undefined-function if symbol is not fbound and an
attempt is made to read its definition.  (No such error is signaled on
an attempt to write its definition.)

See Also::
..........

*note fboundp:: , *note fmakunbound:: , *note macro-function:: ,

   *note special-operator-p::

Notes::
.......

symbol-function cannot access the value of a lexical function name
produced by flet or labels; it can access only the global function
value.

   setf may be used with symbol-function to replace a global function
definition when the symbol's function definition does not represent a
special operator.

     (symbol-function symbol) == (fdefinition symbol)

   However, fdefinition accepts arguments other than just symbols.


File: gcl.info,  Node: symbol-name,  Next: symbol-package,  Prev: symbol-function,  Up: Symbols Dictionary

10.2.11 symbol-name [Function]
------------------------------

'symbol-name' symbol => name

Arguments and Values::
......................

symbol--a symbol.

   name--a string.

Description::
.............

symbol-name returns the name of symbol.

   The consequences are undefined if name is ever modified.

Examples::
..........

      (symbol-name 'temp) =>  "TEMP"
      (symbol-name :start) =>  "START"
      (symbol-name (gensym)) =>  "G1234" ;for example

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.


File: gcl.info,  Node: symbol-package,  Next: symbol-plist,  Prev: symbol-name,  Up: Symbols Dictionary

10.2.12 symbol-package [Function]
---------------------------------

'symbol-package' symbol => contents

Arguments and Values::
......................

symbol--a symbol.

   contents--a package object or nil.

Description::
.............

Returns the home package of symbol.

Examples::
..........

      (in-package "CL-USER") =>  #<PACKAGE "COMMON-LISP-USER">
      (symbol-package 'car) =>  #<PACKAGE "COMMON-LISP">
      (symbol-package 'bus) =>  #<PACKAGE "COMMON-LISP-USER">
      (symbol-package :optional) =>  #<PACKAGE "KEYWORD">
      ;; Gensyms are uninterned, so have no home package.
      (symbol-package (gensym)) =>  NIL
      (make-package 'pk1) =>  #<PACKAGE "PK1">
      (intern "SAMPLE1" "PK1") =>  PK1::SAMPLE1, NIL
      (export (find-symbol "SAMPLE1" "PK1") "PK1") =>  T
      (make-package 'pk2 :use '(pk1)) =>  #<PACKAGE "PK2">
      (find-symbol "SAMPLE1" "PK2") =>  PK1:SAMPLE1, :INHERITED
      (symbol-package 'pk1::sample1) =>  #<PACKAGE "PK1">
      (symbol-package 'pk2::sample1) =>  #<PACKAGE "PK1">
      (symbol-package 'pk1::sample2) =>  #<PACKAGE "PK1">
      (symbol-package 'pk2::sample2) =>  #<PACKAGE "PK2">
      ;; The next several forms create a scenario in which a symbol
      ;; is not really uninterned, but is "apparently uninterned",
      ;; and so SYMBOL-PACKAGE still returns NIL.
      (setq s3 'pk1::sample3) =>  PK1::SAMPLE3
      (import s3 'pk2) =>  T
      (unintern s3 'pk1) =>  T
      (symbol-package s3) =>  NIL
      (eq s3 'pk2::sample3) =>  T

Affected By::
.............

import, intern, unintern

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.

See Also::
..........

*note intern::


File: gcl.info,  Node: symbol-plist,  Next: symbol-value,  Prev: symbol-package,  Up: Symbols Dictionary

10.2.13 symbol-plist [Accessor]
-------------------------------

'symbol-plist' symbol => plist

   (setf (' symbol-plist' symbol) new-plist)

Arguments and Values::
......................

symbol--a symbol.

   plist, new-plist--a property list.

Description::
.............

Accesses the property list of symbol.

Examples::
..........

      (setq sym (gensym)) =>  #:G9723
      (symbol-plist sym) =>  ()
      (setf (get sym 'prop1) 'val1) =>  VAL1
      (symbol-plist sym) =>  (PROP1 VAL1)
      (setf (get sym 'prop2) 'val2) =>  VAL2
      (symbol-plist sym) =>  (PROP2 VAL2 PROP1 VAL1)
      (setf (symbol-plist sym) (list 'prop3 'val3)) =>  (PROP3 VAL3)
      (symbol-plist sym) =>  (PROP3 VAL3)

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.

See Also::
..........

*note get:: , *note remprop::

Notes::
.......

The use of setf should be avoided, since a symbol's property list is a
global resource that can contain information established and depended
upon by unrelated programs in the same Lisp image.


File: gcl.info,  Node: symbol-value,  Next: get,  Prev: symbol-plist,  Up: Symbols Dictionary

10.2.14 symbol-value [Accessor]
-------------------------------

'symbol-value' symbol => value

   (setf (' symbol-value' symbol) new-value)

Arguments and Values::
......................

symbol--a symbol that must have a value.

   value, new-value--an object.

Description::
.............

Accesses the symbol's value cell.

Examples::
..........

      (setf (symbol-value 'a) 1) =>  1
      (symbol-value 'a) =>  1
      ;; SYMBOL-VALUE cannot see lexical variables.
      (let ((a 2)) (symbol-value 'a)) =>  1
      (let ((a 2)) (setq a 3) (symbol-value 'a)) =>  1
      ;; SYMBOL-VALUE can see dynamic variables.
      (let ((a 2))
        (declare (special a))
        (symbol-value 'a)) =>  2
      (let ((a 2))
        (declare (special a))
        (setq a 3)
        (symbol-value 'a)) =>  3
      (let ((a 2))
        (setf (symbol-value 'a) 3)
        a) =>  2
      a =>  3
      (symbol-value 'a) =>  3
      (let ((a 4))
        (declare (special a))
        (let ((b (symbol-value 'a)))
          (setf (symbol-value 'a) 5)
          (values a b))) =>  5, 4
      a =>  3
      (symbol-value :any-keyword) =>  :ANY-KEYWORD
      (symbol-value 'nil) =>  NIL
      (symbol-value '()) =>  NIL
      ;; The precision of this next one is implementation-dependent.
      (symbol-value 'pi) =>  3.141592653589793d0

Affected By::
.............

makunbound, set, setq

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.

   Should signal unbound-variable if symbol is unbound and an attempt is
made to read its value.  (No such error is signaled on an attempt to
write its value.)

See Also::
..........

*note boundp:: , *note makunbound:: , *note set:: , *note setq::

Notes::
.......

symbol-value can be used to get the value of a constant variable.
symbol-value cannot access the value of a lexical variable.


File: gcl.info,  Node: get,  Next: remprop,  Prev: symbol-value,  Up: Symbols Dictionary

10.2.15 get [Accessor]
----------------------

'get' symbol indicator &optional default => value

   (setf (' get' symbol indicator &optional default) new-value)

Arguments and Values::
......................

symbol--a symbol.

   indicator--an object.

   default--an object.  The default is nil.

   value--if the indicated property exists, the object that is its
value; otherwise, the specified default.

   new-value--an object.

Description::
.............

get finds a property on the property list_2 of symbol whose property
indicator is identical to indicator, and returns its corresponding
property value.

   If there are multiple properties_1 with that property indicator, get
uses the first such property.

   If there is no property with that property indicator, default is
returned.

   setf of get may be used to associate a new object with an existing
indicator already on the symbol's property list, or to create a new
assocation if none exists.

   If there are multiple properties_1 with that property indicator, setf
of get associates the new-value with the first such property.

   When a get form is used as a setf place, any default which is
supplied is evaluated according to normal left-to-right evaluation
rules, but its value is ignored.

Examples::
..........

      (defun make-person (first-name last-name)
        (let ((person (gensym "PERSON")))
          (setf (get person 'first-name) first-name)
          (setf (get person 'last-name) last-name)
          person)) =>  MAKE-PERSON
      (defvar *john* (make-person "John" "Dow")) =>  *JOHN*
      *john* =>  #:PERSON4603
      (defvar *sally* (make-person "Sally" "Jones")) =>  *SALLY*
      (get *john* 'first-name) =>  "John"
      (get *sally* 'last-name) =>  "Jones"
      (defun marry (man woman married-name)
        (setf (get man 'wife) woman)
        (setf (get woman 'husband) man)
        (setf (get man 'last-name) married-name)
        (setf (get woman 'last-name) married-name)
        married-name) =>  MARRY
      (marry *john* *sally* "Dow-Jones") =>  "Dow-Jones"
      (get *john* 'last-name) =>  "Dow-Jones"
      (get (get *john* 'wife) 'first-name) =>  "Sally"
      (symbol-plist *john*)
     =>  (WIFE #:PERSON4604 LAST-NAME "Dow-Jones" FIRST-NAME "John")
      (defmacro age (person &optional (default ''thirty-something))
        `(get ,person 'age ,default)) =>  AGE
      (age *john*) =>  THIRTY-SOMETHING
      (age *john* 20) =>  20
      (setf (age *john*) 25) =>  25
      (age *john*) =>  25
      (age *john* 20) =>  25

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.

See Also::
..........

*note getf:: , *note symbol-plist:: , *note remprop::

Notes::
.......

      (get x y) == (getf (symbol-plist x) y)

   Numbers and characters are not recommended for use as indicators in
portable code since get tests with eq rather than eql, and consequently
the effect of using such indicators is implementation-dependent.

   There is no way using get to distinguish an absent property from one
whose value is default.  However, see get-properties.


File: gcl.info,  Node: remprop,  Next: boundp,  Prev: get,  Up: Symbols Dictionary

10.2.16 remprop [Function]
--------------------------

'remprop' symbol indicator => generalized-boolean

Arguments and Values::
......................

symbol--a symbol.

   indicator--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

remprop removes from the property list_2 of symbol a property_1 with a
property indicator identical to indicator.

   If there are multiple properties_1 with the identical key, remprop
only removes the first such property.

   remprop returns false if no such property was found, or true if a
property was found.

   The property indicator and the corresponding property value are
removed in an undefined order by destructively splicing the property
list.

   The permissible side-effects correspond to those permitted for remf,
such that:

      (remprop x y) == (remf (symbol-plist x) y)

Examples::
..........

      (setq test (make-symbol "PSEUDO-PI")) =>  #:PSEUDO-PI
      (symbol-plist test) =>  ()
      (setf (get test 'constant) t) =>  T
      (setf (get test 'approximation) 3.14) =>  3.14
      (setf (get test 'error-range) 'noticeable) =>  NOTICEABLE
      (symbol-plist test)
     =>  (ERROR-RANGE NOTICEABLE APPROXIMATION 3.14 CONSTANT T)
      (setf (get test 'approximation) nil) =>  NIL
      (symbol-plist test)
     =>  (ERROR-RANGE NOTICEABLE APPROXIMATION NIL CONSTANT T)
      (get test 'approximation) =>  NIL
      (remprop test 'approximation) =>  true
      (get test 'approximation) =>  NIL
      (symbol-plist test)
     =>  (ERROR-RANGE NOTICEABLE CONSTANT T)
      (remprop test 'approximation) =>  NIL
      (symbol-plist test)
     =>  (ERROR-RANGE NOTICEABLE CONSTANT T)
      (remprop test 'error-range) =>  true
      (setf (get test 'approximation) 3) =>  3
      (symbol-plist test)
     =>  (APPROXIMATION 3 CONSTANT T)

Side Effects::
..............

The property list of symbol is modified.

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.

See Also::
..........

*note remf:: , *note symbol-plist::

Notes::
.......

Numbers and characters are not recommended for use as indicators in
portable code since remprop tests with eq rather than eql, and
consequently the effect of using such indicators is
implementation-dependent.  Of course, if you've gotten as far as needing
to remove such a property, you don't have much choice--the time to have
been thinking about this was when you used setf of get to establish the
property.


File: gcl.info,  Node: boundp,  Next: makunbound,  Prev: remprop,  Up: Symbols Dictionary

10.2.17 boundp [Function]
-------------------------

'boundp' symbol => generalized-boolean

Arguments and Values::
......................

symbol--a symbol.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if symbol is bound; otherwise, returns false.

Examples::
..........

      (setq x 1) =>  1
      (boundp 'x) =>  true
      (makunbound 'x) =>  X
      (boundp 'x) =>  false
      (let ((x 2)) (boundp 'x)) =>  false
      (let ((x 2)) (declare (special x)) (boundp 'x)) =>  true

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.

See Also::
..........

*note set:: , *note setq:: , *note symbol-value:: , *note makunbound::

Notes::
.......

The function bound determines only whether a symbol has a value in the
global environment; any lexical bindings are ignored.


File: gcl.info,  Node: makunbound,  Next: set,  Prev: boundp,  Up: Symbols Dictionary

10.2.18 makunbound [Function]
-----------------------------

'makunbound' symbol => symbol

Arguments and Values::
......................

symbol--a symbol

Description::
.............

Makes the symbol be unbound, regardless of whether it was previously
bound.

Examples::
..........

      (setf (symbol-value 'a) 1)
      (boundp 'a) =>  true
      a =>  1
      (makunbound 'a) =>  A
      (boundp 'a) =>  false

Side Effects::
..............

The value cell of symbol is modified.

Exceptional Situations::
........................

Should signal an error of type type-error if symbol is not a symbol.

See Also::
..........

*note boundp:: , *note fmakunbound::


File: gcl.info,  Node: set,  Next: unbound-variable,  Prev: makunbound,  Up: Symbols Dictionary

10.2.19 set [Function]
----------------------

'set' symbol value => value

Arguments and Values::
......................

symbol--a symbol.

   value--an object.

Description::
.............

set changes the contents of the value cell of symbol to the given value.

     (set symbol value) == (setf (symbol-value symbol) value)

Examples::
..........

      (setf (symbol-value 'n) 1) =>  1
      (set 'n 2) =>  2
      (symbol-value 'n) =>  2
      (let ((n 3))
        (declare (special n))
        (setq n (+ n 1))
        (setf (symbol-value 'n) (* n 10))
        (set 'n (+ (symbol-value 'n) n))
        n) =>  80
      n =>  2
      (let ((n 3))
        (setq n (+ n 1))
        (setf (symbol-value 'n) (* n 10))
        (set 'n (+ (symbol-value 'n) n))
        n) =>  4
      n =>  44
      (defvar *n* 2)
      (let ((*n* 3))
        (setq *n* (+ *n* 1))
        (setf (symbol-value '*n*) (* *n* 10))
        (set '*n* (+ (symbol-value '*n*) *n*))
        *n*) =>  80
       *n* =>  2
      (defvar *even-count* 0) =>  *EVEN-COUNT*
      (defvar *odd-count* 0) =>  *ODD-COUNT*
      (defun tally-list (list)
        (dolist (element list)
          (set (if (evenp element) '*even-count* '*odd-count*)
               (+ element (if (evenp element) *even-count* *odd-count*)))))
      (tally-list '(1 9 4 3 2 7)) =>  NIL
      *even-count* =>  6
      *odd-count* =>  20

Side Effects::
..............

The value of symbol is changed.

See Also::
..........

*note setq:: , *note progv:: , *note symbol-value::

Notes::
.......

The function set is deprecated.

   set cannot change the value of a lexical variable.


File: gcl.info,  Node: unbound-variable,  Prev: set,  Up: Symbols Dictionary

10.2.20 unbound-variable [Condition Type]
-----------------------------------------

Class Precedence List::
.......................

unbound-variable, cell-error, error, serious-condition, condition, t

Description::
.............

The type unbound-variable consists of error conditions that represent
attempts to read the value of an unbound variable.

   The name of the cell (see cell-error) is the name of the variable
that was unbound.

See Also::
..........

*note cell-error-name::


File: gcl.info,  Node: Packages,  Next: Numbers (Numbers),  Prev: Symbols,  Up: Top

11 Packages
***********

* Menu:

* Package Concepts::
* Packages Dictionary::


File: gcl.info,  Node: Package Concepts,  Next: Packages Dictionary,  Prev: Packages,  Up: Packages

11.1 Package Concepts
=====================

* Menu:

* Introduction to Packages::
* Standardized Packages::


File: gcl.info,  Node: Introduction to Packages,  Next: Standardized Packages,  Prev: Package Concepts,  Up: Package Concepts

11.1.1 Introduction to Packages
-------------------------------

A package establishes a mapping from names to symbols.  At any given
time, one package is current.  The current package is the one that is
the value of *package*.  When using the Lisp reader, it is possible to
refer to symbols in packages other than the current one through the use
of package prefixes in the printed representation of the symbol.

   Figure 11-1 lists some defined names that are applicable to packages.
Where an operator takes an argument that is either a symbol or a list of
symbols, an argument of nil is treated as an empty list of symbols.  Any
package argument may be either a string, a symbol, or a package.  If a
symbol is supplied, its name will be used as the package name.

  *modules*            import                     provide           
  *package*            in-package                 rename-package    
  defpackage           intern                     require           
  do-all-symbols       list-all-packages          shadow            
  do-external-symbols  make-package               shadowing-import  
  do-symbols           package-name               unexport          
  export               package-nicknames          unintern          
  find-all-symbols     package-shadowing-symbols  unuse-package     
  find-package         package-use-list           use-package       
  find-symbol          package-used-by-list                         

         Figure 11-1: Some Defined Names related to Packages       


* Menu:

* Package Names and Nicknames::
* Symbols in a Package::
* Internal and External Symbols::
* Package Inheritance::
* Accessibility of Symbols in a Package::
* Locating a Symbol in a Package::
* Prevention of Name Conflicts in Packages::


File: gcl.info,  Node: Package Names and Nicknames,  Next: Symbols in a Package,  Prev: Introduction to Packages,  Up: Introduction to Packages

11.1.1.1 Package Names and Nicknames
....................................

Each package has a name (a string) and perhaps some nicknames (also
strings).  These are assigned when the package is created and can be
changed later.

   There is a single namespace for packages.  The function find-package
translates a package name or nickname into the associated package.  The
function package-name returns the name of a package.  The function
package-nicknames returns a list of all nicknames for a package.
rename-package removes a package's current name and nicknames and
replaces them with new ones specified by the caller.


File: gcl.info,  Node: Symbols in a Package,  Next: Internal and External Symbols,  Prev: Package Names and Nicknames,  Up: Introduction to Packages

11.1.1.2 Symbols in a Package
.............................


File: gcl.info,  Node: Internal and External Symbols,  Next: Package Inheritance,  Prev: Symbols in a Package,  Up: Introduction to Packages

11.1.1.3 Internal and External Symbols
......................................

The mappings in a package are divided into two classes, external and
internal.  The symbols targeted by these different mappings are called
external symbols and internal symbols of the package.  Within a package,
a name refers to one symbol or to none; if it does refer to a symbol,
then it is either external or internal in that package, but not both.
External symbols

   are part of the package's public interface to other packages.
Symbols become external symbols of a given package if they have been
exported from that package.

   A symbol has the same name no matter what package it is present in,
but it might be an external symbol of some packages and an internal
symbol of others.


File: gcl.info,  Node: Package Inheritance,  Next: Accessibility of Symbols in a Package,  Prev: Internal and External Symbols,  Up: Introduction to Packages

11.1.1.4 Package Inheritance
............................

Packages can be built up in layers.  From one point of view, a package
is a single collection of mappings from strings into internal symbols
and external symbols.  However, some of these mappings might be
established within the package itself, while other mappings are
inherited from other packages via use-package.  A symbol is said to be
present in a package if the mapping is in the package itself and is not
inherited from somewhere else.

   There is no way to inherit the internal symbols of another package;
to refer to an internal symbol using the Lisp reader, a package
containing the symbol must be made to be the current package, a package
prefix must be used, or the symbol must be imported into the current
package.


File: gcl.info,  Node: Accessibility of Symbols in a Package,  Next: Locating a Symbol in a Package,  Prev: Package Inheritance,  Up: Introduction to Packages

11.1.1.5 Accessibility of Symbols in a Package
..............................................

A symbol becomes accessible in a package if that is its home package
when it is created, or if it is imported into that package, or by
inheritance via use-package.

   If a symbol is accessible in a package, it can be referred to when
using the Lisp reader without a package prefix when that package is the
current package, regardless of whether it is present or inherited.

   Symbols from one package can be made accessible in another package in
two ways.

-
     Any individual symbol can be added to a package by use of import.
     After the call to import the symbol is present in the importing
     package.  The status of the symbol in the package it came from (if
     any) is unchanged, and the home package for this symbol is
     unchanged.  Once imported, a symbol is present in the importing
     package and can be removed only by calling unintern.

     A symbol is shadowed_3 by another symbol in some package if the
     first symbol would be accessible by inheritance if not for the
     presence of the second symbol.  See shadowing-import.

-
     The second mechanism for making symbols from one package accessible
     in another is provided by use-package.  All of the external symbols
     of the used package are inherited by the using package.  The
     function unuse-package undoes the effects of a previous
     use-package.


File: gcl.info,  Node: Locating a Symbol in a Package,  Next: Prevention of Name Conflicts in Packages,  Prev: Accessibility of Symbols in a Package,  Up: Introduction to Packages

11.1.1.6 Locating a Symbol in a Package
.......................................

When a symbol is to be located in a given package the following occurs:

-
     The external symbols and internal symbols of the package are
     searched for the symbol.
-
     The external symbols of the used packages are searched in some
     unspecified order.  The order does not matter; see the rules for
     handling name conflicts listed below.


File: gcl.info,  Node: Prevention of Name Conflicts in Packages,  Prev: Locating a Symbol in a Package,  Up: Introduction to Packages

11.1.1.7 Prevention of Name Conflicts in Packages
.................................................

Within one package, any particular name can refer to at most one symbol.
A name conflict is said to occur when there would be more than one
candidate symbol.  Any time a name conflict is about to occur, a
correctable error is signaled.

   The following rules apply to name conflicts:

-
     Name conflicts are detected when they become possible, that is,
     when the package structure is altered.  Name conflicts are not
     checked during every name lookup.

-
     If the same symbol is accessible to a package through more than one
     path, there is no name conflict.  A symbol cannot conflict with
     itself.  Name conflicts occur only between distinct symbols with
     the same name (under string=).

-
     Every package has a list of shadowing symbols.  A shadowing symbol
     takes precedence over any other symbol of the same name that would
     otherwise be accessible in the package.  A name conflict involving
     a shadowing symbol is always resolved in favor of the shadowing
     symbol, without signaling an error (except for one exception
     involving import).  See shadow and shadowing-import.

-
     The functions use-package, import, and export check for name
     conflicts.

-
     shadow and shadowing-import never signal a name-conflict error.

-
     unuse-package and unexport do not need to do any name-conflict
     checking.  unintern does name-conflict checking only when a symbol
     being uninterned is a shadowing symbol .

-
     Giving a shadowing symbol to unintern can uncover a name conflict
     that had previously been resolved by the shadowing.

-
     Package functions signal name-conflict errors of type package-error
     before making any change to the package structure.  When multiple
     changes are to be made, it is permissible for the implementation to
     process each change separately.  For example, when export is given
     a list of symbols, aborting from a name conflict caused by the
     second symbol in the list might still export the first symbol in
     the list.  However, a name-conflict error caused by export of a
     single symbol will be signaled before that symbol's accessibility
     in any package is changed.

-
     Continuing from a name-conflict error must offer the user a chance
     to resolve the name conflict in favor of either of the candidates.
     The package structure should be altered to reflect the resolution
     of the name conflict, via shadowing-import, unintern, or unexport.

-
     A name conflict in use-package between a symbol present in the
     using package and an external symbol of the used package is
     resolved in favor of the first symbol by making it a shadowing
     symbol, or in favor of the second symbol by uninterning the first
     symbol from the using package.

-
     A name conflict in export or unintern due to a package's inheriting
     two distinct symbols with the same name (under string=) from two
     other packages can be resolved in favor of either symbol by
     importing it into the using package and making it a shadowing
     symbol , just as with use-package.


File: gcl.info,  Node: Standardized Packages,  Prev: Introduction to Packages,  Up: Package Concepts

11.1.2 Standardized Packages
----------------------------

This section describes the packages that are available in every
conforming implementation.  A summary of the names and nicknames of
those standardized packages is given in Figure 11-2.

  Name              Nicknames  
  COMMON-LISP       CL         
  COMMON-LISP-USER  CL-USER    
  KEYWORD           none       

  Figure 11-2: Standardized Package Names


* Menu:

* The COMMON-LISP Package::
* Constraints on the COMMON-LISP Package for Conforming Implementations::
* Constraints on the COMMON-LISP Package for Conforming Programs::
* Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs::
* The COMMON-LISP-USER Package::
* The KEYWORD Package::
* Interning a Symbol in the KEYWORD Package::
* Notes about The KEYWORD Package::
* Implementation-Defined Packages::


File: gcl.info,  Node: The COMMON-LISP Package,  Next: Constraints on the COMMON-LISP Package for Conforming Implementations,  Prev: Standardized Packages,  Up: Standardized Packages

11.1.2.1 The COMMON-LISP Package
................................

The COMMON-LISP package contains the primitives of the Common Lisp
system as defined by this specification.  Its external symbols include
all of the defined names (except for defined names in the KEYWORD
package) that are present in the Common Lisp system, such as car, cdr,
*package*, etc.  The COMMON-LISP package has the nickname CL.

   The COMMON-LISP package has as external symbols those symbols
enumerated in the figures in *note Symbols in the COMMON-LISP Package::,
and no others.  These external symbols are present in the COMMON-LISP
package but their home package need not be the COMMON-LISP package.

   For example, the symbol HELP cannot be an external symbol of the
COMMON-LISP package because it is not mentioned in *note Symbols in the
COMMON-LISP Package::.  In contrast, the symbol variable must be an
external symbol of the COMMON-LISP package even though it has no
definition because it is listed in that section (to support its use as a
valid second argument to the function documentation).

   The COMMON-LISP package can have additional internal symbols.


File: gcl.info,  Node: Constraints on the COMMON-LISP Package for Conforming Implementations,  Next: Constraints on the COMMON-LISP Package for Conforming Programs,  Prev: The COMMON-LISP Package,  Up: Standardized Packages

11.1.2.2 Constraints on the COMMON-LISP Package for Conforming Implementations
..............................................................................

In a conforming implementation, an external symbol of the COMMON-LISP
package can have a function, macro, or special operator definition, a
global variable definition (or other status as a dynamic variable due to
a special proclamation), or a type definition only if explicitly
permitted in this standard.  For example, fboundp yields false for any
external symbol of the COMMON-LISP package that is not the name of a
standardized function, macro or special operator, and boundp returns
false for any external symbol of the COMMON-LISP package that is not the
name of a standardized global variable.  It also follows that conforming
programs can use external symbols of the COMMON-LISP package as the
names of local lexical variables with confidence that those names have
not been proclaimed special by the implementation unless those symbols
are names of standardized global variables.

   A conforming implementation must not place any property on an
external symbol of the COMMON-LISP package using a property indicator
that is either an external symbol of any standardized package or a
symbol that is otherwise accessible in the COMMON-LISP-USER package.


File: gcl.info,  Node: Constraints on the COMMON-LISP Package for Conforming Programs,  Next: Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs,  Prev: Constraints on the COMMON-LISP Package for Conforming Implementations,  Up: Standardized Packages

11.1.2.3 Constraints on the COMMON-LISP Package for Conforming Programs
.......................................................................

Except where explicitly allowed, the consequences are undefined if any
of the following actions are performed on an external symbol of the
COMMON-LISP package:

1.
     Binding or altering its value (lexically or dynamically). 	(Some
     exceptions are noted below.)

2.
     Defining,

     undefining,

     or binding it as a function. 	(Some exceptions are noted below.)

3.
     Defining,

     undefining,

     or binding it as a macro

     or compiler macro.

     (Some exceptions are noted below.)

4.
     Defining it as a type specifier (via defstruct, defclass, deftype,
     define-condition).

5.
     Defining it as a structure (via defstruct).

6.
     Defining it as a declaration with a declaration proclamation.

7.
     Defining it as a symbol macro.

8.
     Altering its home package.

9.
     Tracing it (via trace).

10.
     Declaring or proclaiming it special (via declare,

     declaim,

     or proclaim).

11.
     Declaring or proclaiming its type or ftype (via declare,

     declaim,

     or proclaim). 	(Some exceptions are noted below.)

12.
     Removing it from the COMMON-LISP package.

13.
     Defining a setf expander for it (via defsetf or
     define-setf-method).

14.
     Defining, undefining, or binding its setf function name.

15.
     Defining it as a method combination type (via
     define-method-combination).

16.
     Using it as the class-name argument to setf of find-class.

17.
     Binding it as a catch tag.

18.
     Binding it as a restart name.

19.
     Defining a method for a standardized generic function which is
     applicable when all of the arguments are direct instances of
     standardized classes.


File: gcl.info,  Node: Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs,  Next: The COMMON-LISP-USER Package,  Prev: Constraints on the COMMON-LISP Package for Conforming Programs,  Up: Standardized Packages

11.1.2.4 Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs
..........................................................................................

If an external symbol of the COMMON-LISP package is not globally defined
as a standardized dynamic variable or constant variable, it is allowed
to lexically bind it and to declare the type of that binding, and it is
allowed to locally establish it as a symbol macro (e.g., with
symbol-macrolet).

   Unless explicitly specified otherwise, if an external symbol of the
COMMON-LISP package is globally defined as a standardized dynamic
variable, it is permitted to bind or assign that dynamic variable
provided that the "Value Type" constraints on the dynamic variable are
maintained, and that the new value of the variable is consistent with
the stated purpose of the variable.

   If an external symbol of the COMMON-LISP package is not defined as a
standardized function, macro, or special operator, it is allowed to
lexically bind it as a function (e.g., with flet), to declare the ftype
of that binding, and (in implementations which provide the ability to do
so) to trace that binding.

   If an external symbol of the COMMON-LISP package is not defined as a
standardized function, macro, or special operator, it is allowed to
lexically bind it as a macro (e.g., with macrolet).

   If an external symbol of the COMMON-LISP package is not defined as a
standardized function, macro, or special operator, it is allowed to
lexically bind its setf function name as a function, and to declare the
ftype of that binding.


File: gcl.info,  Node: The COMMON-LISP-USER Package,  Next: The KEYWORD Package,  Prev: Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs,  Up: Standardized Packages

11.1.2.5 The COMMON-LISP-USER Package
.....................................

The COMMON-LISP-USER package is the current package when a Common Lisp
system starts up.  This package uses the COMMON-LISP package.  The
COMMON-LISP-USER package has the nickname CL-USER.

   The COMMON-LISP-USER package can have additional symbols interned
within it; it can use other implementation-defined packages.


File: gcl.info,  Node: The KEYWORD Package,  Next: Interning a Symbol in the KEYWORD Package,  Prev: The COMMON-LISP-USER Package,  Up: Standardized Packages

11.1.2.6 The KEYWORD Package
............................

The KEYWORD package contains symbols, called keywords_1, that are
typically used as special markers in programs and their associated data
expressions_1.

   Symbol tokens that start with a package marker are parsed by the Lisp
reader as symbols in the KEYWORD package; see *note Symbols as Tokens::.
This makes it notationally convenient to use keywords when communicating
between programs in different packages.  For example, the mechanism for
passing keyword parameters in a call uses keywords_1 to name the
corresponding arguments; see *note Ordinary Lambda Lists::.

   Symbols in the KEYWORD package are, by definition, of type keyword.


File: gcl.info,  Node: Interning a Symbol in the KEYWORD Package,  Next: Notes about The KEYWORD Package,  Prev: The KEYWORD Package,  Up: Standardized Packages

11.1.2.7 Interning a Symbol in the KEYWORD Package
..................................................

The KEYWORD package is treated differently than other packages in that
special actions are taken when a symbol is interned in it.  In
particular, when a symbol is interned in the KEYWORD package, it is
automatically made to be an external symbol and is automatically made to
be a constant variable with itself as a value.


File: gcl.info,  Node: Notes about The KEYWORD Package,  Next: Implementation-Defined Packages,  Prev: Interning a Symbol in the KEYWORD Package,  Up: Standardized Packages

11.1.2.8 Notes about The KEYWORD Package
........................................

It is generally best to confine the use of keywords to situations in
which there are a finitely enumerable set of names to be selected
between.  For example, if there were two states of a light switch, they
might be called :on and :off.

   In situations where the set of names is not finitely enumerable
(i.e., where name conflicts might arise) it is frequently best to use
symbols in some package other than KEYWORD so that conflicts will be
naturally avoided.  For example, it is generally not wise for a program
to use a keyword_1 as a property indicator, since if there were ever
another program that did the same thing, each would clobber the other's
data.


File: gcl.info,  Node: Implementation-Defined Packages,  Prev: Notes about The KEYWORD Package,  Up: Standardized Packages

11.1.2.9 Implementation-Defined Packages
........................................

Other, implementation-defined packages might be present in the initial
Common Lisp environment.

   It is recommended, but not required, that the documentation for a
conforming implementation contain a full list of all package names
initially present in that implementation but not specified in this
specification.  (See also the function list-all-packages.)


File: gcl.info,  Node: Packages Dictionary,  Prev: Package Concepts,  Up: Packages

11.2 Packages Dictionary
========================

* Menu:

* package::
* export::
* find-symbol::
* find-package::
* find-all-symbols::
* import::
* list-all-packages::
* rename-package::
* shadow::
* shadowing-import::
* delete-package::
* make-package::
* with-package-iterator::
* unexport::
* unintern::
* in-package::
* unuse-package::
* use-package::
* defpackage::
* do-symbols::
* intern::
* package-name::
* package-nicknames::
* package-shadowing-symbols::
* package-use-list::
* package-used-by-list::
* packagep::
* *package*::
* package-error::
* package-error-package::


File: gcl.info,  Node: package,  Next: export,  Prev: Packages Dictionary,  Up: Packages Dictionary

11.2.1 package [System Class]
-----------------------------

Class Precedence List::
.......................

package, t

Description::
.............

A package is a namespace that maps symbol names to symbols; see *note
Package Concepts::.

See Also::
..........

*note Package Concepts::, *note Printing Other Objects::, *note Symbols
as Tokens::


File: gcl.info,  Node: export,  Next: find-symbol,  Prev: package,  Up: Packages Dictionary

11.2.2 export [Function]
------------------------

'export' symbols &optional package => t

Arguments and Values::
......................

symbols--a designator for a list of symbols.

   package--a package designator.

   The default is the current package.

Description::
.............

export makes one or more symbols that are accessible in package (whether
directly or by inheritance) be external symbols of that package.

   If any of the symbols is already accessible as an external symbol of
package, export has no effect on that symbol.  If the symbol is present
in package as an internal symbol, it is simply changed to external
status.  If it is accessible as an internal symbol via use-package, it
is first imported into package, then exported.  (The symbol is then
present in the package whether or not package continues to use the
package through which the symbol was originally inherited.)

   export makes each symbol accessible to all the packages that use
package.  All of these packages are checked for name conflicts: (export
s p) does (find-symbol (symbol-name s) q) for each package q in
(package-used-by-list p).  Note that in the usual case of an export
during the initial definition of a package, the result of
package-used-by-list is nil and the name-conflict checking takes
negligible time.  When multiple changes are to be made, for example when
export is given a list of symbols, it is permissible for the
implementation to process each change separately, so that aborting from
a name conflict caused by any but the first symbol in the list does not
unexport the first symbol in the list.  However, aborting from a
name-conflict error caused by export of one of symbols does not leave
that symbol accessible to some packages and inaccessible to others; with
respect to each of symbols processed, export behaves as if it were as an
atomic operation.

   A name conflict in export between one of symbols being exported and a
symbol already present in a package that would inherit the
newly-exported symbol may be resolved in favor of the exported symbol by
uninterning the other one, or in favor of the already-present symbol by
making it a shadowing symbol.

Examples::
..........

      (make-package 'temp :use nil) =>  #<PACKAGE "TEMP">
      (use-package 'temp) =>  T
      (intern "TEMP-SYM" 'temp) =>  TEMP::TEMP-SYM, NIL
      (find-symbol "TEMP-SYM") =>  NIL, NIL
      (export (find-symbol "TEMP-SYM" 'temp) 'temp) =>  T
      (find-symbol "TEMP-SYM") =>  TEMP-SYM, :INHERITED

Side Effects::
..............

The package system is modified.

Affected By::
.............

Accessible symbols.

Exceptional Situations::
........................

If any of the symbols is not accessible at all in package, an error of
type package-error is signaled that is correctable by permitting the
user to interactively specify whether that symbol should be imported.

See Also::
..........

*note import:: , *note unexport:: , *note Package Concepts::


File: gcl.info,  Node: find-symbol,  Next: find-package,  Prev: export,  Up: Packages Dictionary

11.2.3 find-symbol [Function]
-----------------------------

'find-symbol' string &optional package => symbol, status

Arguments and Values::
......................

string--a string.

   package--a package designator.

   The default is the current package.

   symbol--a symbol accessible in the package, or nil.

   status--one of :inherited, :external, :internal, or nil.

Description::
.............

find-symbol locates a symbol whose name is string in a package.  If a
symbol named string is found in package, directly or by inheritance, the
symbol found is returned as the first value; the second value is as
follows:

:internal
     If the symbol is present in package as an internal symbol.

:external
     If the symbol is present in package as an external symbol.

:inherited
     If the symbol is inherited by package through use-package, but is
     not present in package.

   If no such symbol is accessible in package, both values are nil.

Examples::
..........

      (find-symbol "NEVER-BEFORE-USED") =>  NIL, NIL
      (find-symbol "NEVER-BEFORE-USED") =>  NIL, NIL
      (intern "NEVER-BEFORE-USED") =>  NEVER-BEFORE-USED, NIL
      (intern "NEVER-BEFORE-USED") =>  NEVER-BEFORE-USED, :INTERNAL
      (find-symbol "NEVER-BEFORE-USED") =>  NEVER-BEFORE-USED, :INTERNAL
      (find-symbol "never-before-used") =>  NIL, NIL
      (find-symbol "CAR" 'common-lisp-user) =>  CAR, :INHERITED
      (find-symbol "CAR" 'common-lisp) =>  CAR, :EXTERNAL
      (find-symbol "NIL" 'common-lisp-user) =>  NIL, :INHERITED
      (find-symbol "NIL" 'common-lisp) =>  NIL, :EXTERNAL
      (find-symbol "NIL" (prog1 (make-package "JUST-TESTING" :use '())
                                (intern "NIL" "JUST-TESTING")))
     =>  JUST-TESTING::NIL, :INTERNAL
      (export 'just-testing::nil 'just-testing)
      (find-symbol "NIL" 'just-testing) =>  JUST-TESTING:NIL, :EXTERNAL
      (find-symbol "NIL" "KEYWORD")
     =>  NIL, NIL
     OR=> :NIL, :EXTERNAL
      (find-symbol (symbol-name :nil) "KEYWORD") =>  :NIL, :EXTERNAL

Affected By::
.............

intern, import, export, use-package, unintern, unexport, unuse-package

See Also::
..........

*note intern:: , *note find-all-symbols::

Notes::
.......

find-symbol is operationally equivalent to intern, except that it never
creates a new symbol.


File: gcl.info,  Node: find-package,  Next: find-all-symbols,  Prev: find-symbol,  Up: Packages Dictionary

11.2.4 find-package [Function]
------------------------------

'find-package' name => package

Arguments and Values::
......................

name--a string designator or a package object.

   package--a package object or nil.

Description::
.............

If name is a string designator, find-package locates and returns the
package whose name or nickname is name.  This search is case sensitive.
If there is no such package, find-package returns nil.

   If name is a package object, that package object is returned.

Examples::
..........

      (find-package 'common-lisp) =>  #<PACKAGE "COMMON-LISP">
      (find-package "COMMON-LISP-USER") =>  #<PACKAGE "COMMON-LISP-USER">
      (find-package 'not-there) =>  NIL

Affected By::
.............

The set of packages created by the implementation.

   defpackage, delete-package, make-package, rename-package

See Also::
..........

*note make-package::


File: gcl.info,  Node: find-all-symbols,  Next: import,  Prev: find-package,  Up: Packages Dictionary

11.2.5 find-all-symbols [Function]
----------------------------------

'find-all-symbols' string => symbols

Arguments and Values::
......................

string--a string designator.

   symbols--a list of symbols.

Description::
.............

find-all-symbols searches every registered package for symbols that have
a name that is the same (under string=) as string.  A list of all such
symbols is returned.  Whether or how the list is ordered is
implementation-dependent.

Examples::
..........

      (find-all-symbols 'car)
     =>  (CAR)
     OR=> (CAR VEHICLES:CAR)
     OR=> (VEHICLES:CAR CAR)
      (intern "CAR" (make-package 'temp :use nil)) =>  TEMP::CAR, NIL
      (find-all-symbols 'car)
     =>  (TEMP::CAR CAR)
     OR=> (CAR TEMP::CAR)
     OR=> (TEMP::CAR CAR VEHICLES:CAR)
     OR=> (CAR TEMP::CAR VEHICLES:CAR)

See Also::
..........

*note find-symbol::


File: gcl.info,  Node: import,  Next: list-all-packages,  Prev: find-all-symbols,  Up: Packages Dictionary

11.2.6 import [Function]
------------------------

'import' symbols &optional package => t

Arguments and Values::
......................

symbols--a designator for a list of symbols.

   package--a package designator.

   The default is the current package.

Description::
.............

import adds symbol or symbols to the internals of package, checking for
name conflicts with existing symbols either present in package or
accessible to it.  Once the symbols have been imported, they may be
referenced in the importing package without the use of a package prefix
when using the Lisp reader.

   A name conflict in import between the symbol being imported and a
symbol inherited from some other package can be resolved in favor of the
symbol being imported by making it a shadowing symbol, or in favor of
the symbol already accessible by not doing the import.  A name conflict
in import with a symbol already present in the package may be resolved
by uninterning that symbol, or by not doing the import.

   The imported symbol is not automatically exported from the current
package, but if it is already present and external, then the fact that
it is external is not changed.

   If any symbol to be imported has no home package (i.e.,
(symbol-package symbol) => nil), import sets the home package of the
symbol to package.

   If the symbol is already present in the importing package, import has
no effect.

Examples::
..........

      (import 'common-lisp::car (make-package 'temp :use nil)) =>  T
      (find-symbol "CAR" 'temp) =>  CAR, :INTERNAL
      (find-symbol "CDR" 'temp) =>  NIL, NIL

   The form (import 'editor:buffer) takes the external symbol named
buffer in the EDITOR package (this symbol was located when the form was
read by the Lisp reader) and adds it to the current package as an
internal symbol.  The symbol buffer is then present in the current
package.

Side Effects::
..............

The package system is modified.

Affected By::
.............

Current state of the package system.

Exceptional Situations::
........................

import signals a correctable error of type package-error if any of the
symbols to be imported has the same name (under string=) as some
distinct symbol (under eql) already accessible in the package, even if
the conflict is with a shadowing symbol of the package.

See Also::
..........

*note shadow:: , *note export::


File: gcl.info,  Node: list-all-packages,  Next: rename-package,  Prev: import,  Up: Packages Dictionary

11.2.7 list-all-packages [Function]
-----------------------------------

'list-all-packages' <no arguments> => packages

Arguments and Values::
......................

packages--a list of package objects.

Description::
.............

list-all-packages returns a

   fresh

   list of

   all registered packages.

Examples::
..........

      (let ((before (list-all-packages)))
         (make-package 'temp)
         (set-difference (list-all-packages) before)) =>  (#<PACKAGE "TEMP">)

Affected By::
.............

defpackage, delete-package, make-package


File: gcl.info,  Node: rename-package,  Next: shadow,  Prev: list-all-packages,  Up: Packages Dictionary

11.2.8 rename-package [Function]
--------------------------------

'rename-package' package new-name &optional new-nicknames =>
package-object

Arguments and Values::
......................

package--a package designator.

   new-name--a package designator.

   new-nicknames--a list of string designators.  The default is the
empty list.

   package-object--the renamed package object.

Description::
.............

Replaces the name and nicknames of package.  The old name and all of the
old nicknames of package are eliminated and are replaced by new-name and
new-nicknames.

   The consequences are undefined if new-name or any new-nickname
conflicts with any existing package names.

Examples::
..........

      (make-package 'temporary :nicknames '("TEMP")) =>  #<PACKAGE "TEMPORARY">
      (rename-package 'temp 'ephemeral) =>  #<PACKAGE "EPHEMERAL">
      (package-nicknames (find-package 'ephemeral)) =>  ()
      (find-package 'temporary) =>  NIL
      (rename-package 'ephemeral 'temporary '(temp fleeting))
     =>  #<PACKAGE "TEMPORARY">
      (package-nicknames (find-package 'temp)) =>  ("TEMP" "FLEETING")

See Also::
..........

*note make-package::


File: gcl.info,  Node: shadow,  Next: shadowing-import,  Prev: rename-package,  Up: Packages Dictionary

11.2.9 shadow [Function]
------------------------

'shadow' symbol-names &optional package => t

Arguments and Values::
......................

symbol-names--a designator for a list of string designators.

   package--a package designator.

   The default is the current package.

Description::
.............

shadow assures that symbols with names given by symbol-names are present
in the package.

   Specifically, package is searched for symbols with the names supplied
by symbol-names.

   For each such name, if a corresponding symbol is not present in
package (directly, not by inheritance), then a corresponding symbol is
created with that name, and inserted into package as an internal symbol.
The corresponding symbol, whether pre-existing or newly created, is then
added, if not already present, to the shadowing symbols list of package.

Examples::
..........

      (package-shadowing-symbols (make-package 'temp)) =>  NIL
      (find-symbol 'car 'temp) =>  CAR, :INHERITED
      (shadow 'car 'temp) =>  T
      (find-symbol 'car 'temp) =>  TEMP::CAR, :INTERNAL
      (package-shadowing-symbols 'temp) =>  (TEMP::CAR)

      (make-package 'test-1) =>  #<PACKAGE "TEST-1">
      (intern "TEST" (find-package 'test-1)) =>  TEST-1::TEST, NIL
      (shadow 'test-1::test (find-package 'test-1)) =>  T
      (shadow 'TEST (find-package 'test-1)) =>  T
      (assert (not (null (member 'test-1::test (package-shadowing-symbols
                                                 (find-package 'test-1))))))

      (make-package 'test-2) =>  #<PACKAGE "TEST-2">
      (intern "TEST" (find-package 'test-2)) =>  TEST-2::TEST, NIL
      (export 'test-2::test (find-package 'test-2)) =>  T
      (use-package 'test-2 (find-package 'test-1))    ;should not error


Side Effects::
..............

shadow changes the state of the package system in such a way that the
package consistency rules do not hold across the change.

Affected By::
.............

Current state of the package system.

See Also::
..........

*note package-shadowing-symbols:: , *note Package Concepts::

Notes::
.......

If a symbol with a name in symbol-names already exists in package, but
by inheritance, the inherited symbol becomes shadowed_3 by a newly
created internal symbol.


File: gcl.info,  Node: shadowing-import,  Next: delete-package,  Prev: shadow,  Up: Packages Dictionary

11.2.10 shadowing-import [Function]
-----------------------------------

'shadowing-import' symbols &optional package => t

Arguments and Values::
......................

symbols--a designator for a list of symbols.

   package --a package designator.

   The default is the current package.

Description::
.............

shadowing-import is like import, but it does not signal an error even if
the importation of a symbol would shadow some symbol already accessible
in package.

   shadowing-import inserts each of symbols into package as an internal
symbol, regardless of whether another symbol of the same name is
shadowed by this action.  If a different symbol of the same name is
already present in package, that symbol is first uninterned from
package.  The new symbol is added to package's shadowing-symbols list.

   shadowing-import does name-conflict checking to the extent that it
checks whether a distinct existing symbol with the same name is
accessible; if so, it is shadowed by the new symbol, which implies that
it must be uninterned if it was present in package.

Examples::
..........

      (in-package "COMMON-LISP-USER") =>  #<PACKAGE "COMMON-LISP-USER">
      (setq sym (intern "CONFLICT")) =>  CONFLICT
      (intern "CONFLICT" (make-package 'temp)) =>  TEMP::CONFLICT, NIL
      (package-shadowing-symbols 'temp) =>  NIL
      (shadowing-import sym 'temp) =>  T
      (package-shadowing-symbols 'temp) =>  (CONFLICT)

Side Effects::
..............

shadowing-import changes the state of the package system in such a way
that the consistency rules do not hold across the change.

   package's shadowing-symbols list is modified.

Affected By::
.............

Current state of the package system.

See Also::
..........

*note import:: , *note unintern:: , *note package-shadowing-symbols::


File: gcl.info,  Node: delete-package,  Next: make-package,  Prev: shadowing-import,  Up: Packages Dictionary

11.2.11 delete-package [Function]
---------------------------------

'delete-package' package => generalized-boolean

Arguments and Values::
......................

package--a package designator.

   generalized-boolean--a generalized boolean.

Description::
.............

delete-package deletes package from all package system data structures.
If the operation is successful, delete-package returns true, otherwise
nil.  The effect of delete-package is that the name and nicknames of
package cease to be recognized package names.  The package object is
still a package (i.e., packagep is true of it) but package-name returns
nil.  The consequences of deleting the COMMON-LISP package or the
KEYWORD package are undefined.  The consequences of invoking any other
package operation on package once it has been deleted are unspecified.
In particular, the consequences of invoking find-symbol, intern and
other functions that look for a symbol name in a package are unspecified
if they are called with *package* bound to the deleted package or with
the deleted package as an argument.

   If package is a package object that has already been deleted,
delete-package immediately returns nil.

   After this operation completes, the home package of any symbol whose
home package had previously been package is implementation-dependent.
Except for this, symbols accessible in package are not modified in any
other way; symbols whose home package is not package remain unchanged.

Examples::
..........

      (setq *foo-package* (make-package "FOO" :use nil))
      (setq *foo-symbol*  (intern "FOO" *foo-package*))
      (export *foo-symbol* *foo-package*)

      (setq *bar-package* (make-package "BAR" :use '("FOO")))
      (setq *bar-symbol*  (intern "BAR" *bar-package*))
      (export *foo-symbol* *bar-package*)
      (export *bar-symbol* *bar-package*)

      (setq *baz-package* (make-package "BAZ" :use '("BAR")))

      (symbol-package *foo-symbol*) =>  #<PACKAGE "FOO">
      (symbol-package *bar-symbol*) =>  #<PACKAGE "BAR">

      (prin1-to-string *foo-symbol*) =>  "FOO:FOO"
      (prin1-to-string *bar-symbol*) =>  "BAR:BAR"

      (find-symbol "FOO" *bar-package*) =>  FOO:FOO, :EXTERNAL

      (find-symbol "FOO" *baz-package*) =>  FOO:FOO, :INHERITED
      (find-symbol "BAR" *baz-package*) =>  BAR:BAR, :INHERITED

      (packagep *foo-package*) =>  true
      (packagep *bar-package*) =>  true
      (packagep *baz-package*) =>  true

      (package-name *foo-package*) =>  "FOO"
      (package-name *bar-package*) =>  "BAR"
      (package-name *baz-package*) =>  "BAZ"

      (package-use-list *foo-package*) =>  ()
      (package-use-list *bar-package*) =>  (#<PACKAGE "FOO">)
      (package-use-list *baz-package*) =>  (#<PACKAGE "BAR">)

      (package-used-by-list *foo-package*) =>  (#<PACKAGE "BAR">)
      (package-used-by-list *bar-package*) =>  (#<PACKAGE "BAZ">)
      (package-used-by-list *baz-package*) =>  ()

      (delete-package *bar-package*)
      |>  Error: Package BAZ uses package BAR.
      |>  If continued, BAZ will be made to unuse-package BAR,
      |>  and then BAR will be deleted.
      |>  Type :CONTINUE to continue.
      |>  Debug> |>>:CONTINUE<<|
     =>  T

      (symbol-package *foo-symbol*) =>  #<PACKAGE "FOO">
      (symbol-package *bar-symbol*) is unspecified

      (prin1-to-string *foo-symbol*) =>  "FOO:FOO"
      (prin1-to-string *bar-symbol*) is unspecified

      (find-symbol "FOO" *bar-package*) is unspecified

      (find-symbol "FOO" *baz-package*) =>  NIL, NIL
      (find-symbol "BAR" *baz-package*) =>  NIL, NIL

      (packagep *foo-package*) =>  T
      (packagep *bar-package*) =>  T
      (packagep *baz-package*) =>  T

      (package-name *foo-package*) =>  "FOO"
      (package-name *bar-package*) =>  NIL
      (package-name *baz-package*) =>  "BAZ"

      (package-use-list *foo-package*) =>  ()
      (package-use-list *bar-package*) is unspecified
      (package-use-list *baz-package*) =>  ()

      (package-used-by-list *foo-package*) =>  ()
      (package-used-by-list *bar-package*) is unspecified
      (package-used-by-list *baz-package*) =>  ()

Exceptional Situations::
........................

If the package designator is a name that does not currently name a
package, a correctable error of type package-error is signaled.  If
correction is attempted, no deletion action is attempted; instead,
delete-package immediately returns nil.

   If package is used by other packages, a correctable error of type
package-error is signaled.  If correction is attempted, unuse-package is
effectively called to remove any dependencies, causing package's
external symbols to cease being accessible to those packages that use
package.  delete-package then deletes package just as it would have had
there been no packages that used it.

See Also::
..........

*note unuse-package::


File: gcl.info,  Node: make-package,  Next: with-package-iterator,  Prev: delete-package,  Up: Packages Dictionary

11.2.12 make-package [Function]
-------------------------------

'make-package' package-name &key nicknames use => package

Arguments and Values::
......................

package-name--a string designator.

   nicknames--a list of string designators.  The default is the empty
list.

   use-- a list of package designators.

   The default is implementation-defined.

   package--a package.

Description::
.............

Creates a new package with the name package-name.

   Nicknames are additional names which may be used to refer to the new
package.

   use specifies zero or more packages the external symbols of which are
to be inherited by the new package.  See the function use-package.

Examples::
..........

      (make-package 'temporary :nicknames '("TEMP" "temp")) =>  #<PACKAGE "TEMPORARY">
      (make-package "OWNER" :use '("temp")) =>  #<PACKAGE "OWNER">
      (package-used-by-list 'temp) =>  (#<PACKAGE "OWNER">)
      (package-use-list 'owner) =>  (#<PACKAGE "TEMPORARY">)

Affected By::
.............

The existence of other packages in the system.

Exceptional Situations::
........................

The consequences are unspecified if packages denoted by use do not
exist.

   A correctable error is signaled if the package-name or any of the
nicknames is already the name or nickname of an existing package.

See Also::
..........

*note defpackage:: , *note use-package::

Notes::
.......

In situations where the packages to be used contain symbols which would
conflict, it is necessary to first create the package with :use '(),
then to use shadow or shadowing-import to address the conflicts, and
then after that to use use-package once the conflicts have been
addressed.

   When packages are being created as part of the static definition of a
program rather than dynamically by the program, it is generally
considered more stylistically appropriate to use defpackage rather than
make-package.


File: gcl.info,  Node: with-package-iterator,  Next: unexport,  Prev: make-package,  Up: Packages Dictionary

11.2.13 with-package-iterator [Macro]
-------------------------------------

'with-package-iterator' (name package-list-form &rest symbol-types)
{declaration}* {form}*
=> {result}*

Arguments and Values::
......................

name--a symbol.

   package-list-form--a form; evaluated once to produce a package-list.

   package-list--a designator for a list of package designators.

   symbol-type--one of the symbols :internal, :external, or :inherited.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   results--the values of the forms.

Description::
.............

Within the lexical scope of the body forms, the name is defined via
macrolet such that successive invocations of (name) will return the
symbols, one by one, from the packages in package-list.

   It is unspecified whether symbols inherited from multiple packages
are returned more than once.  The order of symbols returned does not
necessarily reflect the order of packages in package-list.  When
package-list has more than one element, it is unspecified whether
duplicate symbols are returned once or more than once.

   Symbol-types controls which symbols that are accessible in a package
are returned as follows:

:internal
     The symbols that are present in the package, but that are not
     exported.

:external
     The symbols that are present in the package and are exported.

:inherited
     The symbols that are exported by used packages and that are not
     shadowed.

   When more than one argument is supplied for symbol-types, a symbol is
returned if its accessibility matches any one of the symbol-types
supplied.  Implementations may extend this syntax by recognizing
additional symbol accessibility types.

   An invocation of (name) returns four values as follows:

1.
     A flag that indicates whether a symbol is returned (true means that
     a symbol is returned).
2.
     A symbol that is accessible in one the indicated packages.
3.
     The accessibility type for that symbol; i.e., one of the symbols
     :internal, :external, or :inherited.
4.
     The package from which the symbol was obtained. 	The package is one
     of the packages present or named in package-list.

   After all symbols have been returned by successive invocations of
(name), then only one value is returned, namely nil.

   The meaning of the second, third, and fourth values is that the
returned symbol is accessible in the returned package in the way
indicated by the second return value as follows:

:internal
     Means present and not exported.

:external
     Means present and exported.

:inherited
     Means not present (thus not shadowed) but inherited from some used
     package.

   It is unspecified what happens if any of the implicit interior state
of an iteration is returned outside the dynamic extent of the
with-package-iterator form such as by returning some closure over the
invocation form.

   Any number of invocations of with-package-iterator can be nested, and
the body of the innermost one can invoke all of the locally established
macros, provided all those macros have distinct names.

Examples::
..........

The following function should return t on any package, and signal an
error if the usage of with-package-iterator does not agree with the
corresponding usage of do-symbols.

      (defun test-package-iterator (package)
        (unless (packagep package)
          (setq package (find-package package)))
        (let ((all-entries '())
              (generated-entries '()))
          (do-symbols (x package)
            (multiple-value-bind (symbol accessibility)
                (find-symbol (symbol-name x) package)
              (push (list symbol accessibility) all-entries)))
          (with-package-iterator (generator-fn package
                                  :internal :external :inherited)
            (loop
              (multiple-value-bind (more? symbol accessibility pkg)
                  (generator-fn)
                (unless more? (return))
                (let ((l (multiple-value-list (find-symbol (symbol-name symbol)
                                                           package))))
                  (unless (equal l (list symbol accessibility))
                    (error "Symbol ~S not found as ~S in package ~A [~S]"
                           symbol accessibility (package-name package) l))
                  (push l generated-entries)))))
          (unless (and (subsetp all-entries generated-entries :test #'equal)
                       (subsetp generated-entries all-entries :test #'equal))
           (error "Generated entries and Do-Symbols entries don't correspond"))
          t))

   The following function prints out every present symbol (possibly more
than once):

      (defun print-all-symbols ()
        (with-package-iterator (next-symbol (list-all-packages)
                                :internal :external)
          (loop
            (multiple-value-bind (more? symbol) (next-symbol)
              (if more?
                 (print symbol)
                 (return))))))

Exceptional Situations::
........................

with-package-iterator signals an error of type program-error if no
symbol-types are supplied or if a symbol-type is not recognized by the
implementation is supplied.

   The consequences are undefined if the local function named name
established by with-package-iterator is called after it has returned
false as its primary value.

See Also::
..........

*note Traversal Rules and Side Effects::


File: gcl.info,  Node: unexport,  Next: unintern,  Prev: with-package-iterator,  Up: Packages Dictionary

11.2.14 unexport [Function]
---------------------------

'unexport' symbols &optional package => t

Arguments and Values::
......................

symbols--a designator for a list of symbols.

   package--a package designator.

   The default is the current package.

Description::
.............

unexport reverts external symbols in package to internal status; it
undoes the effect of export.

   unexport works only on symbols present in package, switching them
back to internal status.  If unexport is given a symbol that is already
accessible as an internal symbol in package, it does nothing.

Examples::
..........

      (in-package "COMMON-LISP-USER") =>  #<PACKAGE "COMMON-LISP-USER">
      (export (intern "CONTRABAND" (make-package 'temp)) 'temp) =>  T
      (find-symbol "CONTRABAND") =>  NIL, NIL
      (use-package 'temp) =>  T
      (find-symbol "CONTRABAND") =>  CONTRABAND, :INHERITED
      (unexport 'contraband 'temp) =>  T
      (find-symbol "CONTRABAND") =>  NIL, NIL

Side Effects::
..............

Package system is modified.

Affected By::
.............

Current state of the package system.

Exceptional Situations::
........................

If unexport is given a symbol not accessible in package at all, an error
of type package-error is signaled.

   The consequences are undefined if package is the KEYWORD package or
the COMMON-LISP package.

See Also::
..........

*note export:: , *note Package Concepts::


File: gcl.info,  Node: unintern,  Next: in-package,  Prev: unexport,  Up: Packages Dictionary

11.2.15 unintern [Function]
---------------------------

'unintern' symbol &optional package => generalized-boolean

Arguments and Values::
......................

symbol--a symbol.

   package--a package designator.

   The default is the current package.

   generalized-boolean--a generalized boolean.

Description::
.............

unintern removes symbol from package.  If symbol is present in package,
it is removed from package and also from package's shadowing symbols
list if it is present there.  If package is the home package for symbol,
symbol is made to have no home package.  Symbol may continue to be
accessible in package by inheritance.

   Use of unintern can result in a symbol that has no recorded home
package, but that in fact is accessible in some package.  Common Lisp
does not check for this pathological case, and such symbols are always
printed preceded by #:.

   unintern returns true if it removes symbol, and nil otherwise.

Examples::
..........

      (in-package "COMMON-LISP-USER") =>  #<PACKAGE "COMMON-LISP-USER">
      (setq temps-unpack (intern "UNPACK" (make-package 'temp))) =>  TEMP::UNPACK
      (unintern temps-unpack 'temp) =>  T
      (find-symbol "UNPACK" 'temp) =>  NIL, NIL
      temps-unpack =>  #:UNPACK

Side Effects::
..............

unintern changes the state of the package system in such a way that the
consistency rules do not hold across the change.

Affected By::
.............

Current state of the package system.

Exceptional Situations::
........................

Giving a shadowing symbol to unintern can uncover a name conflict that
had previously been resolved by the shadowing.  If package A uses
packages B and C, A contains a shadowing symbol x, and B and C each
contain external symbols named x, then removing the shadowing symbol x
from A will reveal a name conflict between b:x and c:x if those two
symbols are distinct.  In this case unintern will signal an error.

See Also::
..........

*note Package Concepts::


File: gcl.info,  Node: in-package,  Next: unuse-package,  Prev: unintern,  Up: Packages Dictionary

11.2.16 in-package [Macro]
--------------------------

'in-package' name => package

Arguments and Values::
......................

name--a string designator; not evaluated.

   package--the package named by name.

Description::
.............

Causes the the package named by name to become the current package--that
is, the value of *package*.  If no such package already exists, an error
of type package-error is signaled.

   Everything in-package does is also performed at compile time if the
call appears as a top level form.

Side Effects::
..............

The variable *package* is assigned.  If the in-package form is a top
level form, this assignment also occurs at compile time.

Exceptional Situations::
........................

An error of type package-error is signaled if the specified package does
not exist.

See Also::
..........

*note package::


File: gcl.info,  Node: unuse-package,  Next: use-package,  Prev: in-package,  Up: Packages Dictionary

11.2.17 unuse-package [Function]
--------------------------------

'unuse-package' packages-to-unuse &optional package => t

Arguments and Values::
......................

packages-to-unuse--a designator for a list of package designators.

   package--a package designator.  The default is the current package.

Description::
.............

unuse-package causes package to cease inheriting all the external
symbols of packages-to-unuse; unuse-package undoes the effects of
use-package.  The packages-to-unuse are removed from the use list of
package.

   Any symbols that have been imported into package continue to be
present in package.

Examples::
..........

      (in-package "COMMON-LISP-USER") =>  #<PACKAGE "COMMON-LISP-USER">
      (export (intern "SHOES" (make-package 'temp)) 'temp) =>  T
      (find-symbol "SHOES") =>  NIL, NIL
      (use-package 'temp) =>  T
      (find-symbol "SHOES") =>  SHOES, :INHERITED
      (find (find-package 'temp) (package-use-list 'common-lisp-user)) =>  #<PACKAGE "TEMP">
      (unuse-package 'temp) =>  T
      (find-symbol "SHOES") =>  NIL, NIL

Side Effects::
..............

The use list of package is modified.

Affected By::
.............

Current state of the package system.

See Also::
..........

*note use-package:: , *note package-use-list::


File: gcl.info,  Node: use-package,  Next: defpackage,  Prev: unuse-package,  Up: Packages Dictionary

11.2.18 use-package [Function]
------------------------------

'use-package' packages-to-use &optional package => t

Arguments and Values::
......................

packages-to-use--a designator for a list of package designators.  The
KEYWORD package may not be supplied.

   package--a package designator.  The KEYWORD package cannot be
supplied.  The default is the current package.

Description::
.............

use-package causes package to inherit all the external symbols of
packages-to-use.  The inherited symbols become accessible as internal
symbols of package.

   Packages-to-use are added to the use list of package if they are not
there already.  All external symbols in packages-to-use become
accessible in package as internal symbols.  use-package does not cause
any new symbols to be present in package but only makes them accessible
by inheritance.

   use-package checks for name conflicts between the newly imported
symbols and those already accessible in package.  A name conflict in
use-package between two external symbols inherited by package from
packages-to-use may be resolved in favor of either symbol by importing
one of them into package and making it a shadowing symbol.

Examples::
..........

      (export (intern "LAND-FILL" (make-package 'trash)) 'trash) =>  T
      (find-symbol "LAND-FILL" (make-package 'temp)) =>  NIL, NIL
      (package-use-list 'temp) =>  (#<PACKAGE "TEMP">)
      (use-package 'trash 'temp) =>  T
      (package-use-list 'temp) =>  (#<PACKAGE "TEMP"> #<PACKAGE "TRASH">)
      (find-symbol "LAND-FILL" 'temp) =>  TRASH:LAND-FILL, :INHERITED

Side Effects::
..............

The use list of package may be modified.

See Also::
..........

*note unuse-package:: , *note package-use-list:: , *note Package
Concepts::

Notes::
.......

It is permissible for a package P_1 to use a package P_2 even if P_2
already uses P_1.  The using of packages is not transitive, so no
problem results from the apparent circularity.


File: gcl.info,  Node: defpackage,  Next: do-symbols,  Prev: use-package,  Up: Packages Dictionary

11.2.19 defpackage [Macro]
--------------------------

'defpackage' defined-package-name [[!option]] => package

   option ::={(:nicknames {nickname}*)}* | 
           (:documentation string) | 
           {(:use {package-name}*)}* | 
           {(:shadow {!symbol-name}*)}* | 
           {(:shadowing-import-from package-name {!symbol-name}*)}* | 
           {(:import-from package-name {!symbol-name}*)}* | 
           {(:export {!symbol-name}*)}* | 
           {(:intern {!symbol-name}*)}* |             (:size integer)

   symbol-name ::=(symbol | string)

Arguments and Values::
......................

defined-package-name--a string designator.

   package-name--a package designator.

   nickname--a string designator.

   symbol-name--a string designator.

   package--the package named package-name.

Description::
.............

defpackage creates a package as specified and returns the package.

   If defined-package-name already refers to an existing package, the
name-to-package mapping for that name is not changed.  If the new
definition is at variance with the current state of that package, the
consequences are undefined; an implementation might choose to modify the
existing package to reflect the new definition.  If defined-package-name
is a symbol, its name is used.

   The standard options are described below.

:nicknames
     The arguments to :nicknames set the package's nicknames to the
     supplied names.

:documentation
     The argument to :documentation specifies a documentation string; it
     is attached as a documentation string to the package.  At most one
     :documentation option can appear in a single defpackage form.

:use
     The arguments to :use set the packages that the package named by
     package-name will inherit from.  If :use is not supplied,

     it defaults to the same implementation-dependent value as the :use
     argument to make-package.

:shadow
     The arguments to :shadow, symbol-names, name symbols that are to be
     created in the package being defined.  These symbols are added to
     the list of shadowing symbols effectively as if by shadow.

:shadowing-import-from
     The symbols named by the argument symbol-names are found (involving
     a lookup as if by find-symbol) in the specified package-name.  The
     resulting symbols are imported into the package being defined, and
     placed on the shadowing symbols list as if by shadowing-import.  In
     no case are symbols created in any package other than the one being
     defined.

:import-from
     The symbols named by the argument symbol-names are found in the
     package named by package-name and they are imported into the
     package being defined.  In no case are symbols created in any
     package other than the one being defined.

:export
     The symbols named by the argument symbol-names are found or created
     in the package being defined and exported.  The :export option
     interacts with the :use option, since inherited symbols can be used
     rather than new ones created.  The :export option interacts with
     the :import-from and :shadowing-import-from options, since imported
     symbols can be used rather than new ones created.  If an argument
     to the :export option is accessible as an (inherited) internal
     symbol via use-package, that the symbol named by symbol-name is
     first imported into the package being defined, and is then exported
     from that package.

:intern
     The symbols named by the argument symbol-names are found or created
     in the package being defined.  The :intern option interacts with
     the :use option, since inherited symbols can be used rather than
     new ones created.

:size
     The argument to the :size option declares the approximate number of
     symbols expected in the package.  This is an efficiency hint only
     and might be ignored by an implementation.

   The order in which the options appear in a defpackage form is
irrelevant.  The order in which they are executed is as follows:

1.
     :shadow and :shadowing-import-from.
2.
     :use.
3.
     :import-from and :intern.
4.
     :export.

   Shadows are established first, since they might be necessary to block
spurious name conflicts when the :use option is processed.  The :use
option is executed next so that :intern and :export options can refer to
normally inherited symbols.  The :export option is executed last so that
it can refer to symbols created by any of the other options; in
particular, shadowing symbols and imported symbols can be made external.

   If a defpackage form appears as a top level form, all of the actions
normally performed by this macro at load time must also be performed at
compile time.

Examples::
..........

      (defpackage "MY-PACKAGE"
        (:nicknames "MYPKG" "MY-PKG")
        (:use "COMMON-LISP")
        (:shadow "CAR" "CDR")
        (:shadowing-import-from "VENDOR-COMMON-LISP"  "CONS")
        (:import-from "VENDOR-COMMON-LISP"  "GC")
        (:export "EQ" "CONS" "FROBOLA")
        )

      (defpackage my-package
        (:nicknames mypkg :MY-PKG)  ; remember Common Lisp conventions for case
        (:use common-lisp)          ; conversion on symbols
        (:shadow CAR :cdr #:cons)
        (:export "CONS")            ; this is the shadowed one.
        )

Affected By::
.............

Existing packages.

Exceptional Situations::
........................

If one of the supplied :nicknames already refers to an existing package,
an error of type package-error is signaled.

   An error of type program-error should be signaled if :size or
:documentation appears more than once.

   Since implementations might allow extended options an error of type
program-error should be signaled if an option is present that is not
actually supported in the host implementation.

   The collection of symbol-name arguments given to the options :shadow,
:intern, :import-from, and :shadowing-import-from must all be disjoint;
additionally, the symbol-name arguments given to :export and :intern
must be disjoint.  Disjoint in this context is defined as no two of the
symbol-names being string= with each other.  If either condition is
violated, an error of type program-error should be signaled.

   For the :shadowing-import-from and :import-from options, a
correctable error of type package-error is signaled if no symbol is
accessible in the package named by package-name for one of the argument
symbol-names.

   Name conflict errors are handled by the underlying calls to
make-package, use-package, import, and export.  See *note Package
Concepts::.

See Also::
..........

*note documentation:: , *note Package Concepts::, *note Compilation::

Notes::
.......

The :intern option is useful if an :import-from or a
:shadowing-import-from option in a subsequent call to defpackage (for
some other package) expects to find these symbols accessible but not
necessarily external.

   It is recommended that the entire package definition is put in a
single place, and that all the package definitions of a program are in a
single file.  This file can be loaded before loading or compiling
anything else that depends on those packages.  Such a file can be read
in the COMMON-LISP-USER package, avoiding any initial state issues.

   defpackage cannot be used to create two "mutually recursive"
packages, such as:

      (defpackage my-package
        (:use common-lisp your-package)    ;requires your-package to exist first
        (:export "MY-FUN"))
      (defpackage your-package
        (:use common-lisp)
        (:import-from my-package "MY-FUN") ;requires my-package to exist first
        (:export "MY-FUN"))

   However, nothing prevents the user from using the package-affecting
functions such as use-package, import, and export to establish such
links after a more standard use of defpackage.

   The macroexpansion of defpackage could usefully canonicalize the
names into strings, so that even if a source file has random symbols in
the defpackage form, the compiled file would only contain strings.

   Frequently additional implementation-dependent options take the form
of a keyword standing by itself as an abbreviation for a list (keyword
T); this syntax should be properly reported as an unrecognized option in
implementations that do not support it.


File: gcl.info,  Node: do-symbols,  Next: intern,  Prev: defpackage,  Up: Packages Dictionary

11.2.20 do-symbols, do-external-symbols, do-all-symbols [Macro]
---------------------------------------------------------------

'do-symbols' (var [package [result-form]]) {declaration}* {tag |
statement}*
=> {result}*

   'do-external-symbols' (var [package [result-form]]) {declaration}*
{tag | statement}*
=> {result}*

   'do-all-symbols' (var [result-form]) {declaration}* {tag |
statement}*
=> {result}*

Arguments and Values::
......................

var--a variable name; not evaluated.

   package--a package designator; evaluated.

   The default in do-symbols and do-external-symbols is the current
package.

   result-form--a form; evaluated as described below.  The default is
nil.

   declaration--a declare expression; not evaluated.

   tag--a go tag; not evaluated.

   statement--a compound form; evaluated as described below.

   results--the values returned by the result-form if a normal return
occurs, or else, if an explicit return occurs, the values that were
transferred.

Description::
.............

do-symbols, do-external-symbols, and do-all-symbols iterate over the
symbols of packages.  For each symbol in the set of packages chosen, the
var is bound to the symbol, and the statements in the body are executed.
When all the symbols have been processed, result-form is evaluated and
returned as the value of the macro.

   do-symbols iterates over the symbols accessible in package.

   Statements may execute more than once for symbols that are inherited
from multiple packages.

   do-all-symbols iterates on every registered package.  do-all-symbols
will not process every symbol whatsoever, because a symbol not
accessible in any registered package will not be processed.
do-all-symbols may cause a symbol that is present in several packages to
be processed more than once.

   do-external-symbols iterates on the external symbols of package.

   When result-form is evaluated, var is bound and has the value nil.

   An implicit block named nil surrounds the entire do-symbols,
do-external-symbols, or do-all-symbols form.

   return or return-from may be used to terminate the iteration
prematurely.

   If execution of the body affects which symbols are contained in the
set of packages over which iteration is occurring, other than to remove
the symbol currently the value of var by using unintern, the
consequences are undefined.

   For each of these macros, the scope of the name binding does not
include any initial value form, but the optional result forms are
included.

   Any tag in the body is treated as with tagbody.

Examples::
..........

      (make-package 'temp :use nil) =>  #<PACKAGE "TEMP">
      (intern "SHY" 'temp) =>  TEMP::SHY, NIL ;SHY will be an internal symbol
                                              ;in the package TEMP
      (export (intern "BOLD" 'temp) 'temp)  =>  T  ;BOLD will be external
      (let ((lst ()))
        (do-symbols (s (find-package 'temp)) (push s lst))
        lst)
     =>  (TEMP::SHY TEMP:BOLD)
     OR=> (TEMP:BOLD TEMP::SHY)
      (let ((lst ()))
        (do-external-symbols (s (find-package 'temp) lst) (push s lst))
        lst)
     =>  (TEMP:BOLD)
      (let ((lst ()))
        (do-all-symbols (s lst)
          (when (eq (find-package 'temp) (symbol-package s)) (push s lst)))
        lst)
     =>  (TEMP::SHY TEMP:BOLD)
     OR=> (TEMP:BOLD TEMP::SHY)

See Also::
..........

*note intern:: , *note export:: ,

   *note Traversal Rules and Side Effects::


File: gcl.info,  Node: intern,  Next: package-name,  Prev: do-symbols,  Up: Packages Dictionary

11.2.21 intern [Function]
-------------------------

'intern' string &optional package => symbol, status

Arguments and Values::
......................

string--a string.

   package--a package designator.

   The default is the current package.

   symbol--a symbol.

   status--one of :inherited, :external, :internal, or nil.

Description::
.............

intern enters a symbol named string into package.  If a symbol whose
name is the same as string is already accessible in package, it is
returned.  If no such symbol is accessible in package, a new symbol with
the given name is created and entered into package as an internal
symbol, or as an external symbol if the package is the KEYWORD package;
package becomes the home package of the created symbol.

   The first value returned by intern, symbol, is the symbol that was
found or created.  The meaning of the secondary value, status, is as
follows:

:internal
     The symbol was found and is present in package as an internal
     symbol.

:external
     The symbol was found and is present as an external symbol.

:inherited
     The symbol was found and is inherited via use-package (which
     implies that the symbol is internal).

nil
     No pre-existing symbol was found, so one was created.

     It is implementation-dependent whether the string that becomes the
     new symbol's name is the given string or a copy of it.  Once a
     string has been given as the string argument to intern in this
     situation where a new symbol is created, the consequences are
     undefined if a subsequent attempt is made to alter that string.

Examples::
..........

      (in-package "COMMON-LISP-USER") =>  #<PACKAGE "COMMON-LISP-USER">
      (intern "Never-Before") =>  |Never-Before|, NIL
      (intern "Never-Before") =>  |Never-Before|, :INTERNAL
      (intern "NEVER-BEFORE" "KEYWORD") =>  :NEVER-BEFORE, NIL
      (intern "NEVER-BEFORE" "KEYWORD") =>  :NEVER-BEFORE, :EXTERNAL

See Also::
..........

*note find-symbol:: , *note read:: , symbol, *note unintern:: , *note
Symbols as Tokens::

Notes::
.......

intern does not need to do any name conflict checking because it never
creates a new symbol if there is already an accessible symbol with the
name given.


File: gcl.info,  Node: package-name,  Next: package-nicknames,  Prev: intern,  Up: Packages Dictionary

11.2.22 package-name [Function]
-------------------------------

'package-name' package => name

Arguments and Values::
......................

package--a package designator.

   name--a string

   or nil.

Description::
.............

package-name returns the string that names package,

   or nil if the package designator is a package object that has no name
(see the function delete-package).

Examples::
..........

      (in-package "COMMON-LISP-USER") =>  #<PACKAGE "COMMON-LISP-USER">
      (package-name *package*) =>  "COMMON-LISP-USER"
      (package-name (symbol-package :test)) =>  "KEYWORD"
      (package-name (find-package 'common-lisp)) =>  "COMMON-LISP"

      (defvar *foo-package* (make-package "FOO"))
      (rename-package "FOO" "FOO0")
      (package-name *foo-package*) =>  "FOO0"

Exceptional Situations::
........................

Should signal an error of type type-error if package is not a package
designator.


File: gcl.info,  Node: package-nicknames,  Next: package-shadowing-symbols,  Prev: package-name,  Up: Packages Dictionary

11.2.23 package-nicknames [Function]
------------------------------------

'package-nicknames' package => nicknames

Arguments and Values::
......................

package--a package designator.

   nicknames--a list of strings.

Description::
.............

Returns the list of nickname strings for package, not including the name
of package.

Examples::
..........

      (package-nicknames (make-package 'temporary
                                        :nicknames '("TEMP" "temp")))
     =>  ("temp" "TEMP")

Exceptional Situations::
........................

Should signal an error of type type-error if package is not a package
designator.


File: gcl.info,  Node: package-shadowing-symbols,  Next: package-use-list,  Prev: package-nicknames,  Up: Packages Dictionary

11.2.24 package-shadowing-symbols [Function]
--------------------------------------------

'package-shadowing-symbols' package => symbols

Arguments and Values::
......................

package--a package designator.

   symbols--a list of symbols.

Description::
.............

Returns a list of symbols that have been declared as shadowing symbols
in package by shadow or shadowing-import (or the equivalent defpackage
options).  All symbols on this list are present in package.

Examples::
..........

      (package-shadowing-symbols (make-package 'temp)) =>  ()
      (shadow 'cdr 'temp) =>  T
      (package-shadowing-symbols 'temp) =>  (TEMP::CDR)
      (intern "PILL" 'temp) =>  TEMP::PILL, NIL
      (shadowing-import 'pill 'temp) =>  T
      (package-shadowing-symbols 'temp) =>  (PILL TEMP::CDR)

Exceptional Situations::
........................

Should signal an error of type type-error if package is not a package
designator.

See Also::
..........

*note shadow:: , *note shadowing-import::

Notes::
.......

Whether the list of symbols is fresh is implementation-dependent.


File: gcl.info,  Node: package-use-list,  Next: package-used-by-list,  Prev: package-shadowing-symbols,  Up: Packages Dictionary

11.2.25 package-use-list [Function]
-----------------------------------

'package-use-list' package => use-list

Arguments and Values::
......................

package--a package designator.

   use-list--a list of package objects.

Description::
.............

Returns a list of other packages used by package.

Examples::
..........

      (package-use-list (make-package 'temp)) =>  (#<PACKAGE "COMMON-LISP">)
      (use-package 'common-lisp-user 'temp) =>  T
      (package-use-list 'temp) =>  (#<PACKAGE "COMMON-LISP"> #<PACKAGE "COMMON-LISP-USER">)

Exceptional Situations::
........................

Should signal an error of type type-error if package is not a package
designator.

See Also::
..........

*note use-package:: , *note unuse-package::


File: gcl.info,  Node: package-used-by-list,  Next: packagep,  Prev: package-use-list,  Up: Packages Dictionary

11.2.26 package-used-by-list [Function]
---------------------------------------

'package-used-by-list' package => used-by-list

Arguments and Values::
......................

package--a package designator.

   used-by-list--a list of package objects.

Description::
.............

package-used-by-list returns a list of other packages that use package.

Examples::
..........

      (package-used-by-list (make-package 'temp)) =>  ()
      (make-package 'trash :use '(temp)) =>  #<PACKAGE "TRASH">
      (package-used-by-list 'temp) =>  (#<PACKAGE "TRASH">)

Exceptional Situations::
........................

Should signal an error of type type-error if package is not a package.

See Also::
..........

*note use-package:: , *note unuse-package::


File: gcl.info,  Node: packagep,  Next: *package*,  Prev: package-used-by-list,  Up: Packages Dictionary

11.2.27 packagep [Function]
---------------------------

'packagep' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type package; otherwise, returns false.

Examples::
..........

      (packagep *package*) =>  true
      (packagep 'common-lisp) =>  false
      (packagep (find-package 'common-lisp)) =>  true

Notes::
.......

      (packagep object) == (typep object 'package)


File: gcl.info,  Node: *package*,  Next: package-error,  Prev: packagep,  Up: Packages Dictionary

11.2.28 *package* [Variable]
----------------------------

Value Type::
............

a package object.

Initial Value::
...............

the COMMON-LISP-USER package.

Description::
.............

Whatever package object is currently the value of *package* is referred
to as the current package.

Examples::
..........

      (in-package "COMMON-LISP-USER") =>  #<PACKAGE "COMMON-LISP-USER">
      *package* =>  #<PACKAGE "COMMON-LISP-USER">
      (make-package "SAMPLE-PACKAGE" :use '("COMMON-LISP"))
     =>  #<PACKAGE "SAMPLE-PACKAGE">
      (list
        (symbol-package
          (let ((*package* (find-package 'sample-package)))
            (setq *some-symbol* (read-from-string "just-testing"))))
        *package*)
     =>  (#<PACKAGE "SAMPLE-PACKAGE"> #<PACKAGE "COMMON-LISP-USER">)
      (list (symbol-package (read-from-string "just-testing"))
            *package*)
     =>  (#<PACKAGE "COMMON-LISP-USER"> #<PACKAGE "COMMON-LISP-USER">)
      (eq 'foo (intern "FOO")) =>  true
      (eq 'foo (let ((*package* (find-package 'sample-package)))
                 (intern "FOO")))
     =>  false

Affected By::
.............

load, compile-file, in-package

See Also::
..........

*note compile-file:: , *note in-package:: , *note load:: , *note
package::


File: gcl.info,  Node: package-error,  Next: package-error-package,  Prev: *package*,  Up: Packages Dictionary

11.2.29 package-error [Condition Type]
--------------------------------------

Class Precedence List::
.......................

package-error, error, serious-condition, condition, t

Description::
.............

The type package-error consists of error conditions related to
operations on packages.  The offending package (or package name) is
initialized by the :package initialization argument to make-condition,
and is accessed by the function package-error-package.

See Also::
..........

*note package-error-package:: , *note Conditions::


File: gcl.info,  Node: package-error-package,  Prev: package-error,  Up: Packages Dictionary

11.2.30 package-error-package [Function]
----------------------------------------

'package-error-package' condition => package

Arguments and Values::
......................

condition--a condition of type package-error.

   package--a package designator.

Description::
.............

Returns a designator for the offending package in the situation
represented by the condition.

Examples::
..........

      (package-error-package
        (make-condition 'package-error
          :package (find-package "COMMON-LISP")))
     =>  #<Package "COMMON-LISP">

See Also::
..........

package-error


File: gcl.info,  Node: Numbers (Numbers),  Next: Characters,  Prev: Packages,  Up: Top

12 Numbers
**********

* Menu:

* Number Concepts::
* Numbers Dictionary::


File: gcl.info,  Node: Number Concepts,  Next: Numbers Dictionary,  Prev: Numbers (Numbers),  Up: Numbers (Numbers)

12.1 Number Concepts
====================

* Menu:

* Numeric Operations::
* Implementation-Dependent Numeric Constants::
* Rational Computations::
* Floating-point Computations::
* Complex Computations::
* Interval Designators::
* Random-State Operations::


File: gcl.info,  Node: Numeric Operations,  Next: Implementation-Dependent Numeric Constants,  Prev: Number Concepts,  Up: Number Concepts

12.1.1 Numeric Operations
-------------------------

Common Lisp provides a large variety of operations related to numbers.
This section provides an overview of those operations by grouping them
into categories that emphasize some of the relationships among them.

   Figure 12-1 shows operators relating to arithmetic operations.

  *  1+         gcd   
  +  1-         incf  
  -  conjugate  lcm   
  /  decf             

  Figure 12-1: Operators relating to Arithmetic.


   Figure 12-2 shows defined names relating to exponential, logarithmic,
and trigonometric operations.

  abs    cos    signum  
  acos   cosh   sin     
  acosh  exp    sinh    
  asin   expt   sqrt    
  asinh  isqrt  tan     
  atan   log    tanh    
  atanh  phase          
  cis    pi             

  Figure 12-2: Defined names relating to Exponentials, Logarithms, and Trigonometry.


   Figure 12-3 shows operators relating to numeric comparison and
predication.

  /=  >=      oddp   
  <   evenp   plusp  
  <=  max     zerop  
  =   min            
  >   minusp         

  Figure 12-3: Operators for numeric comparison and predication.


   Figure 12-4 shows defined names relating to numeric type manipulation
and coercion.

  ceiling          float-radix           rational     
  complex          float-sign            rationalize  
  decode-float     floor                 realpart     
  denominator      fround                rem          
  fceiling         ftruncate             round        
  ffloor           imagpart              scale-float  
  float            integer-decode-float  truncate     
  float-digits     mod                                
  float-precision  numerator                          

  Figure 12-4: Defined names relating to numeric type manipulation and coercion.


* Menu:

* Associativity and Commutativity in Numeric Operations::
* Examples of Associativity and Commutativity in Numeric Operations::
* Contagion in Numeric Operations::
* Viewing Integers as Bits and Bytes::
* Logical Operations on Integers::
* Byte Operations on Integers::


File: gcl.info,  Node: Associativity and Commutativity in Numeric Operations,  Next: Examples of Associativity and Commutativity in Numeric Operations,  Prev: Numeric Operations,  Up: Numeric Operations

12.1.1.1 Associativity and Commutativity in Numeric Operations
..............................................................

For functions that are mathematically associative (and possibly
commutative), a conforming implementation may process the arguments in
any manner consistent with associative (and possibly commutative)
rearrangement.  This does not affect the order in which the argument
forms are evaluated; for a discussion of evaluation order, see *note
Function Forms::.  What is unspecified is only the order in which the
parameter values are processed.  This implies that implementations may
differ in which automatic coercions are applied; see *note Contagion in
Numeric Operations::.

   A conforming program can control the order of processing explicitly
by separating the operations into separate (possibly nested) function
forms, or by writing explicit calls to functions that perform coercions.


File: gcl.info,  Node: Examples of Associativity and Commutativity in Numeric Operations,  Next: Contagion in Numeric Operations,  Prev: Associativity and Commutativity in Numeric Operations,  Up: Numeric Operations

12.1.1.2 Examples of Associativity and Commutativity in Numeric Operations
..........................................................................

Consider the following expression, in which we assume that 1.0 and
1.0e-15 both denote single floats:

      (+ 1/3 2/3 1.0d0 1.0 1.0e-15)

   One conforming implementation might process the arguments from left
to right, first adding 1/3 and 2/3 to get 1, then converting that to a
double float for combination with 1.0d0, then successively converting
and adding 1.0 and 1.0e-15.

   Another conforming implementation might process the arguments from
right to left, first performing a single float addition of 1.0 and
1.0e-15 (perhaps losing accuracy in the process), then converting the
sum to a double float and adding 1.0d0, then converting 2/3 to a double
float and adding it, and then converting 1/3 and adding that.

   A third conforming implementation might first scan all the arguments,
process all the rationals first to keep that part of the computation
exact, then find an argument of the largest floating-point format among
all the arguments and add that, and then add in all other arguments,
converting each in turn (all in a perhaps misguided attempt to make the
computation as accurate as possible).

   In any case, all three strategies are legitimate.

   A conforming program could control the order by writing, for example,

      (+ (+ 1/3 2/3) (+ 1.0d0 1.0e-15) 1.0)


File: gcl.info,  Node: Contagion in Numeric Operations,  Next: Viewing Integers as Bits and Bytes,  Prev: Examples of Associativity and Commutativity in Numeric Operations,  Up: Numeric Operations

12.1.1.3 Contagion in Numeric Operations
........................................

For information about the contagion rules for implicit coercions of
arguments in numeric operations, see *note Rule of Float Precision
Contagion::, *note Rule of Float and Rational Contagion::, and *note
Rule of Complex Contagion::.


File: gcl.info,  Node: Viewing Integers as Bits and Bytes,  Next: Logical Operations on Integers,  Prev: Contagion in Numeric Operations,  Up: Numeric Operations

12.1.1.4 Viewing Integers as Bits and Bytes
...........................................


File: gcl.info,  Node: Logical Operations on Integers,  Next: Byte Operations on Integers,  Prev: Viewing Integers as Bits and Bytes,  Up: Numeric Operations

12.1.1.5 Logical Operations on Integers
.......................................

Logical operations require integers as arguments; an error of type
type-error should be signaled if an argument is supplied that is not an
integer.  Integer arguments to logical operations are treated as if they
were represented in two's-complement notation.

   Figure 12-5 shows defined names relating to logical operations on
numbers.

  ash          boole-ior       logbitp   
  boole        boole-nand      logcount  
  boole-1      boole-nor       logeqv    
  boole-2      boole-orc1      logior    
  boole-and    boole-orc2      lognand   
  boole-andc1  boole-set       lognor    
  boole-andc2  boole-xor       lognot    
  boole-c1     integer-length  logorc1   
  boole-c2     logand          logorc2   
  boole-clr    logandc1        logtest   
  boole-eqv    logandc2        logxor    

  Figure 12-5: Defined names relating to logical operations on numbers.



File: gcl.info,  Node: Byte Operations on Integers,  Prev: Logical Operations on Integers,  Up: Numeric Operations

12.1.1.6 Byte Operations on Integers
....................................

The byte-manipulation functions use objects called byte specifiers to
designate the size and position of a specific byte within an integer.
The representation of a byte specifier is implementation-dependent; it
might or might not be a number.  The function byte will construct a byte
specifier, which various other byte-manipulation functions will accept.

   Figure 12-6 shows defined names relating to manipulating bytes of
numbers.

  byte           deposit-field  ldb-test    
  byte-position  dpb            mask-field  
  byte-size      ldb                        

  Figure 12-6: Defined names relating to byte manipulation.



File: gcl.info,  Node: Implementation-Dependent Numeric Constants,  Next: Rational Computations,  Prev: Numeric Operations,  Up: Number Concepts

12.1.2 Implementation-Dependent Numeric Constants
-------------------------------------------------

Figure 12-7 shows defined names relating to implementation-dependent
details about numbers.

  double-float-epsilon           most-negative-fixnum           
  double-float-negative-epsilon  most-negative-long-float       
  least-negative-double-float    most-negative-short-float      
  least-negative-long-float      most-negative-single-float     
  least-negative-short-float     most-positive-double-float     
  least-negative-single-float    most-positive-fixnum           
  least-positive-double-float    most-positive-long-float       
  least-positive-long-float      most-positive-short-float      
  least-positive-short-float     most-positive-single-float     
  least-positive-single-float    short-float-epsilon            
  long-float-epsilon             short-float-negative-epsilon   
  long-float-negative-epsilon    single-float-epsilon           
  most-negative-double-float     single-float-negative-epsilon  

  Figure 12-7: Defined names relating to implementation-dependent details about numbers.



File: gcl.info,  Node: Rational Computations,  Next: Floating-point Computations,  Prev: Implementation-Dependent Numeric Constants,  Up: Number Concepts

12.1.3 Rational Computations
----------------------------

The rules in this section apply to rational computations.

* Menu:

* Rule of Unbounded Rational Precision::
* Rule of Canonical Representation for Rationals::
* Rule of Float Substitutability::


File: gcl.info,  Node: Rule of Unbounded Rational Precision,  Next: Rule of Canonical Representation for Rationals,  Prev: Rational Computations,  Up: Rational Computations

12.1.3.1 Rule of Unbounded Rational Precision
.............................................

Rational computations cannot overflow in the usual sense (though there
may not be enough storage to represent a result), since integers and
ratios may in principle be of any magnitude.


File: gcl.info,  Node: Rule of Canonical Representation for Rationals,  Next: Rule of Float Substitutability,  Prev: Rule of Unbounded Rational Precision,  Up: Rational Computations

12.1.3.2 Rule of Canonical Representation for Rationals
.......................................................

If any computation produces a result that is a mathematical ratio of two
integers such that the denominator evenly divides the numerator, then
the result is converted to the equivalent integer.

   If the denominator does not evenly divide the numerator, the
canonical representation of a rational number is as the ratio that
numerator and that denominator, where the greatest common divisor of the
numerator and denominator is one, and where the denominator is positive
and greater than one.

   When used as input (in the default syntax), the notation -0 always
denotes the integer 0.  A conforming implementation must not have a
representation of "minus zero" for integers that is distinct from its
representation of zero for integers.  However, such a distinction is
possible for floats; see the type float.


File: gcl.info,  Node: Rule of Float Substitutability,  Prev: Rule of Canonical Representation for Rationals,  Up: Rational Computations

12.1.3.3 Rule of Float Substitutability
.......................................

When the arguments to an irrational mathematical function

   [Reviewer Note by Barmar: There should be a table of these
functions.]  are all rational and the true mathematical result is also
(mathematically) rational, then unless otherwise noted an implementation
is free to return either an accurate rational result or a single float
approximation.  If the arguments are all rational but the result cannot
be expressed as a rational number, then a single float approximation is
always returned.

   If the arguments to a mathematical function are all of type (or
rational (complex rational)) and the true mathematical result is
(mathematically) a complex number with rational real and imaginary
parts, then unless otherwise noted an implementation is free to return
either an accurate result of type (or rational (complex rational)) or a
single float (permissible only if the imaginary part of the true
mathematical result is zero) or (complex single-float).  If the
arguments are all of type (or rational (complex rational)) but the
result cannot be expressed as a rational or complex rational, then the
returned value will be of type single-float (permissible only if the
imaginary part of the true mathematical result is zero) or (complex
single-float).

  Function  Sample Results                                   
  abs       (abs #c(3 4)) =>  5 or 5.0                       
  acos      (acos 1) =>  0 or 0.0                            
  acosh     (acosh 1) =>  0 or 0.0                           
  asin      (asin 0) =>  0 or 0.0                            
  asinh     (asinh 0) =>  0 or 0.0                           
  atan      (atan 0) =>  0 or 0.0                            
  atanh     (atanh 0) =>  0 or 0.0                           
  cis       (cis 0) =>  #c(1 0) or #c(1.0 0.0)               
  cos       (cos 0) =>  1 or 1.0                             
  cosh      (cosh 0) =>  1 or 1.0                            
  exp       (exp 0) =>  1 or 1.0                             
  expt      (expt 8 1/3) =>  2 or 2.0                        
  log       (log 1) =>  0 or 0.0                             
            (log 8 2) =>  3 or 3.0                           
  phase     (phase 7) =>  0 or 0.0                           
  signum    (signum #c(3 4)) =>  #c(3/5 4/5) or #c(0.6 0.8)  
  sin       (sin 0) =>  0 or 0.0                             
  sinh      (sinh 0) =>  0 or 0.0                            
  sqrt      (sqrt 4) =>  2 or 2.0                            
            (sqrt 9/16) =>  3/4 or 0.75                      
  tan       (tan 0) =>  0 or 0.0                             
  tanh      (tanh 0) =>  0 or 0.0                            

  Figure 12-8: Functions Affected by Rule of Float Substitutability



File: gcl.info,  Node: Floating-point Computations,  Next: Complex Computations,  Prev: Rational Computations,  Up: Number Concepts

12.1.4 Floating-point Computations
----------------------------------

The following rules apply to floating point computations.

* Menu:

* Rule of Float and Rational Contagion::
* Examples of Rule of Float and Rational Contagion::
* Rule of Float Approximation::
* Rule of Float Underflow and Overflow::
* Rule of Float Precision Contagion::


File: gcl.info,  Node: Rule of Float and Rational Contagion,  Next: Examples of Rule of Float and Rational Contagion,  Prev: Floating-point Computations,  Up: Floating-point Computations

12.1.4.1 Rule of Float and Rational Contagion
.............................................

When rationals and floats are combined by a numerical function, the
rational is first converted to a float of the same format.  For
functions such as + that take more than two arguments, it is permitted
that part of the operation be carried out exactly using rationals and
the rest be done using floating-point arithmetic.

   When rationals and floats are compared by a numerical function, the
function rational is effectively called to convert the float to a
rational and then an exact comparison is performed.  In the case of
complex numbers, the real and imaginary parts are effectively handled
individually.


File: gcl.info,  Node: Examples of Rule of Float and Rational Contagion,  Next: Rule of Float Approximation,  Prev: Rule of Float and Rational Contagion,  Up: Floating-point Computations

12.1.4.2 Examples of Rule of Float and Rational Contagion
.........................................................

      ;;;; Combining rationals with floats.
      ;;; This example assumes an implementation in which
      ;;; (float-radix 0.5) is 2 (as in IEEE) or 16 (as in IBM/360),
      ;;; or else some other implementation in which 1/2 has an exact
      ;;;  representation in floating point.
      (+ 1/2 0.5) =>  1.0
      (- 1/2 0.5d0) =>  0.0d0
      (+ 0.5 -0.5 1/2) =>  0.5

      ;;;; Comparing rationals with floats.
      ;;; This example assumes an implementation in which the default float
      ;;; format is IEEE single-float, IEEE double-float, or some other format
      ;;; in which 5/7 is rounded upwards by FLOAT.
      (< 5/7 (float 5/7)) =>  true
      (< 5/7 (rational (float 5/7))) =>  true
      (< (float 5/7) (float 5/7)) =>  false


File: gcl.info,  Node: Rule of Float Approximation,  Next: Rule of Float Underflow and Overflow,  Prev: Examples of Rule of Float and Rational Contagion,  Up: Floating-point Computations

12.1.4.3 Rule of Float Approximation
....................................

Computations with floats are only approximate, although they are
described as if the results were mathematically accurate.  Two
mathematically identical expressions may be computationally different
because of errors inherent in the floating-point approximation process.
The precision of a float is not necessarily correlated with the accuracy
of that number.  For instance, 3.142857142857142857 is a more precise
approximation to \pi than 3.14159, but the latter is more accurate.  The
precision refers to the number of bits retained in the representation.
When an operation combines a short float with a long float, the result
will be a long float.  Common Lisp functions assume that the accuracy of
arguments to them does not exceed their precision.  Therefore when two
small floats are combined, the result is a small float.  Common Lisp
functions never convert automatically from a larger size to a smaller
one.


File: gcl.info,  Node: Rule of Float Underflow and Overflow,  Next: Rule of Float Precision Contagion,  Prev: Rule of Float Approximation,  Up: Floating-point Computations

12.1.4.4 Rule of Float Underflow and Overflow
.............................................

An error of type floating-point-overflow or floating-point-underflow
should be signaled if a floating-point computation causes exponent
overflow or underflow, respectively.


File: gcl.info,  Node: Rule of Float Precision Contagion,  Prev: Rule of Float Underflow and Overflow,  Up: Floating-point Computations

12.1.4.5 Rule of Float Precision Contagion
..........................................

The result of a numerical function is a float of the largest format
among all the floating-point arguments to the function.


File: gcl.info,  Node: Complex Computations,  Next: Interval Designators,  Prev: Floating-point Computations,  Up: Number Concepts

12.1.5 Complex Computations
---------------------------

The following rules apply to complex computations:

* Menu:

* Rule of Complex Substitutability::
* Rule of Complex Contagion::
* Rule of Canonical Representation for Complex Rationals::
* Examples of Rule of Canonical Representation for Complex Rationals::
* Principal Values and Branch Cuts::


File: gcl.info,  Node: Rule of Complex Substitutability,  Next: Rule of Complex Contagion,  Prev: Complex Computations,  Up: Complex Computations

12.1.5.1 Rule of Complex Substitutability
.........................................

Except during the execution of irrational and transcendental functions,
no numerical function ever yields a complex unless one or more of its
arguments is a complex.


File: gcl.info,  Node: Rule of Complex Contagion,  Next: Rule of Canonical Representation for Complex Rationals,  Prev: Rule of Complex Substitutability,  Up: Complex Computations

12.1.5.2 Rule of Complex Contagion
..................................

When a

   real

   and a complex are both part of a computation, the

   real

   is first converted to a complex by providing an imaginary part of 0.


File: gcl.info,  Node: Rule of Canonical Representation for Complex Rationals,  Next: Examples of Rule of Canonical Representation for Complex Rationals,  Prev: Rule of Complex Contagion,  Up: Complex Computations

12.1.5.3 Rule of Canonical Representation for Complex Rationals
...............................................................

If the result of any computation would be a complex number whose real
part is of type rational and whose imaginary part is zero, the result is
converted to the rational which is the real part.  This rule does not
apply to complex numbers whose parts are floats.  For example, #C(5 0)
and 5 are not different objects in Common Lisp (they are always the same
under eql); #C(5.0 0.0) and 5.0 are always different objects in Common
Lisp (they are never the same under eql, although they are the same
under equalp and =).


File: gcl.info,  Node: Examples of Rule of Canonical Representation for Complex Rationals,  Next: Principal Values and Branch Cuts,  Prev: Rule of Canonical Representation for Complex Rationals,  Up: Complex Computations

12.1.5.4 Examples of Rule of Canonical Representation for Complex Rationals
...........................................................................

      #c(1.0 1.0) =>  #C(1.0 1.0)
      #c(0.0 0.0) =>  #C(0.0 0.0)
      #c(1.0 1) =>  #C(1.0 1.0)
      #c(0.0 0) =>  #C(0.0 0.0)
      #c(1 1) =>  #C(1 1)
      #c(0 0) =>  0
      (typep #c(1 1) '(complex (eql 1))) =>  true
      (typep #c(0 0) '(complex (eql 0))) =>  false


File: gcl.info,  Node: Principal Values and Branch Cuts,  Prev: Examples of Rule of Canonical Representation for Complex Rationals,  Up: Complex Computations

12.1.5.5 Principal Values and Branch Cuts
.........................................

Many of the irrational and transcendental functions are multiply defined
in the complex domain; for example, there are in general an infinite
number of complex values for the logarithm function.  In each such case,
a principal value must be chosen for the function to return.  In
general, such values cannot be chosen so as to make the range
continuous; lines in the domain called branch cuts must be defined,
which in turn define the discontinuities in the range.  Common Lisp
defines the branch cuts, principal values, and boundary conditions for
the complex functions following "Principal Values and Branch Cuts in
Complex APL." The branch cut rules that apply to each function are
located with the description of that function.

   Figure 12-9 lists the identities that are obeyed throughout the
applicable portion of the complex domain, even on the branch cuts:

  sin i z = i sinh z  sinh i z = i sin z        arctan i z = i arctanh z  
  cos i z = cosh z    cosh i z = cos z          arcsinh i z = i arcsin z  
  tan i z = i tanh z  arcsin i z = i arcsinh z  arctanh i z = i arctan z  

         Figure 12-9: Trigonometric Identities for Complex Domain        


   The quadrant numbers referred to in the discussions of branch cuts
are as illustrated in Figure 12-10.

                                Imaginary Axis
     	                         |
     	        		 |
     	        	II       |        I
     	        	         |
     	        	         |
     	        	         |
     	       ______________________________________ Real Axis
     	        	         |
     	        	         |
     	        	         |
     	               III       |     	   IV
     	        		 |
     	        		 |
     	        		 |
     	        		 |


     Figure 12-9: Quadrant Numbering for Branch Cuts


File: gcl.info,  Node: Interval Designators,  Next: Random-State Operations,  Prev: Complex Computations,  Up: Number Concepts

12.1.6 Interval Designators
---------------------------

The compound type specifier form of the numeric type specifiers in
Figure 12-10 permit the user to specify an interval on the real number
line which describe a subtype of the type which would be described by
the corresponding atomic type specifier.  A subtype of some type T is
specified using an ordered pair of objects called interval designators
for type T.

   The first of the two interval designators for type T can be any of
the following:

a number N of type T
     This denotes a lower inclusive bound of N. That is, elements of the
     subtype of T will be greater than or equal to N.

a singleton list whose element is
     a number M of type T This denotes a lower exclusive bound of M.
     That is, elements of the subtype of T will be greater than M.

the symbol *
     This denotes the absence of a lower bound on the interval.

   The second of the two interval designators for type T can be any of
the following:

a number N of type T
     This denotes an upper inclusive bound of N. That is, elements of
     the subtype of T will be less than or equal to N.

a singleton list whose element is
     a number M of type T This denotes an upper exclusive bound of M.
     That is, elements of the subtype of T will be less than M.

the symbol *
     This denotes the absence of an upper bound on the interval.


File: gcl.info,  Node: Random-State Operations,  Prev: Interval Designators,  Up: Number Concepts

12.1.7 Random-State Operations
------------------------------

Figure 12-10 lists some defined names that are applicable to random
states.

  *random-state*     random            
  make-random-state  random-state-p    

  Figure 12-10: Random-state defined names



File: gcl.info,  Node: Numbers Dictionary,  Prev: Number Concepts,  Up: Numbers (Numbers)

12.2 Numbers Dictionary
=======================

* Menu:

* number::
* complex (System Class)::
* real::
* float (System Class)::
* short-float::
* rational (System Class)::
* ratio::
* integer::
* signed-byte::
* unsigned-byte::
* mod (System Class)::
* bit (System Class)::
* fixnum::
* bignum::
* =::
* max::
* minusp::
* zerop::
* floor::
* sin::
* asin::
* pi::
* sinh::
* *::
* +::
* -::
* /::
* 1+::
* abs::
* evenp::
* exp::
* gcd::
* incf::
* lcm::
* log::
* mod (Function)::
* signum::
* sqrt::
* random-state::
* make-random-state::
* random::
* random-state-p::
* *random-state*::
* numberp::
* cis::
* complex::
* complexp::
* conjugate::
* phase::
* realpart::
* upgraded-complex-part-type::
* realp::
* numerator::
* rational (Function)::
* rationalp::
* ash::
* integer-length::
* integerp::
* parse-integer::
* boole::
* boole-1::
* logand::
* logbitp::
* logcount::
* logtest::
* byte::
* deposit-field::
* dpb::
* ldb::
* ldb-test::
* mask-field::
* most-positive-fixnum::
* decode-float::
* float::
* floatp::
* most-positive-short-float::
* short-float-epsilon::
* arithmetic-error::
* arithmetic-error-operands::
* division-by-zero::
* floating-point-invalid-operation::
* floating-point-inexact::
* floating-point-overflow::
* floating-point-underflow::


File: gcl.info,  Node: number,  Next: complex (System Class),  Prev: Numbers Dictionary,  Up: Numbers Dictionary

12.2.1 number [System Class]
----------------------------

Class Precedence List::
.......................

number, t

Description::
.............

The type number contains objects which represent mathematical numbers.

   The types real and complex are disjoint subtypes of number.

   The function = tests for numerical equality.  The function eql, when
its arguments are both numbers, tests that they have both the same type
and numerical value.  Two numbers that are the same under eql or = are
not necessarily the same under eq.

Notes::
.......

Common Lisp differs from mathematics on some naming issues.  In
mathematics, the set of real numbers is traditionally described as a
subset of the complex numbers, but in Common Lisp, the type real and the
type complex are disjoint.  The Common Lisp type which includes all
mathematical complex numbers is called number.  The reasons for these
differences include historical precedent, compatibility with most other
popular computer languages, and various issues of time and space
efficiency.


File: gcl.info,  Node: complex (System Class),  Next: real,  Prev: number,  Up: Numbers Dictionary

12.2.2 complex [System Class]
-----------------------------

Class Precedence List::
.......................

complex, number, t

Description::
.............

The type complex includes all mathematical complex numbers other than
those included in the type rational.  Complexes are expressed in
Cartesian form with a real part and an imaginary part, each of which is
a real.  The real part and imaginary part are either both rational or
both of the same float type.  The imaginary part can be a float zero,
but can never be a rational zero, for such a number is always
represented by Common Lisp as a rational rather than a complex.

Compound Type Specifier Kind::
..............................

Specializing.

Compound Type Specifier Syntax::
................................

('complex'{[typespec | *]})

Compound Type Specifier Arguments::
...................................

typespec--a type specifier that denotes a subtype of type real.

Compound Type Specifier Description::
.....................................

[Editorial Note by KMP: If you ask me, this definition is a complete
mess.  Looking at issue
ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING does not help me
figure it out, either.  Anyone got any suggestions?]

   Every element of this type is a complex whose real part and imaginary
part are each of type

   (upgraded-complex-part-type typespec).

   This type encompasses those complexes that can result by giving
numbers of type typespec to complex.

   (complex type-specifier) refers to all complexes that can result from
giving numbers of type type-specifier to the function complex, plus all
other complexes of the same specialized representation.

See Also::
..........

*note Rule of Canonical Representation for Complex Rationals::, *note
Constructing Numbers from Tokens::, *note Printing Complexes::

Notes::
.......

The input syntax for a complex with real part r and imaginary part i is
#C(r i).  For further details, see *note Standard Macro Characters::.

   For every float, n, there is a complex which represents the same
mathematical number and which can be obtained by (COERCE n 'COMPLEX).


File: gcl.info,  Node: real,  Next: float (System Class),  Prev: complex (System Class),  Up: Numbers Dictionary

12.2.3 real [System Class]
--------------------------

Class Precedence List::
.......................

real, number, t

Description::
.............

The type real includes all numbers that represent mathematical real
numbers, though there are mathematical real numbers (e.g., irrational
numbers) that do not have an exact representation in Common Lisp.  Only
reals can be ordered using the <, >, <=, and >= functions.

   The types rational and float are disjoint subtypes of type real.

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('real'{[lower-limit [upper-limit]]})

Compound Type Specifier Arguments::
...................................

lower-limit, upper-limit--interval designators for type real.  The
defaults for each of lower-limit and upper-limit is the symbol *.

Compound Type Specifier Description::
.....................................

This denotes the reals on the interval described by lower-limit and
upper-limit.


File: gcl.info,  Node: float (System Class),  Next: short-float,  Prev: real,  Up: Numbers Dictionary

12.2.4 float [System Class]
---------------------------

Class Precedence List::
.......................

float,

   real,

   number, t

Description::
.............

A float is a mathematical rational (but not a Common Lisp rational) of
the form s\cdot f\cdot b^e-p, where s is +1 or -1, the sign; b is an
integer greater than~1, the base or radix of the representation; p is a
positive integer, the precision (in base-b digits) of the float; f is a
positive integer between b^p-1 and b^p-1 (inclusive), the significand;
and e is an integer, the exponent.  The value of p and the range of~e
depends on the implementation and on the type of float within that
implementation.  In addition, there is a floating-point zero; depending
on the implementation, there can also be a "minus zero".  If there is no
minus zero, then 0.0 and~-0.0 are both interpreted as simply a
floating-point zero.  (= 0.0 -0.0) is always true.  If there is a minus
zero, (eql -0.0 0.0) is false, otherwise it is true.

   [Reviewer Note by Barmar: What about IEEE NaNs and infinities?]

   [Reviewer Note by RWK: In the following, what is the "ordering"?
precision?  range? 	Can there be additional subtypes of float or does
"others" in the list of four?]

   The types short-float, single-float, double-float, and long-float are
subtypes of type float.  Any two of them must be either disjoint types
or the same type; if the same type, then any other types between them in
the above ordering must also be the same type.  For example, if the type
single-float and the type long-float are the same type, then the type
double-float must be the same type also.

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('float'{[lower-limit [upper-limit]]})

Compound Type Specifier Arguments::
...................................

lower-limit, upper-limit--interval designators for type float.  The
defaults for each of lower-limit and upper-limit is the symbol *.

Compound Type Specifier Description::
.....................................

This denotes the floats on the interval described by lower-limit and
upper-limit.

See Also::
..........

Figure~2-9, *note Constructing Numbers from Tokens::, *note Printing
Floats::

Notes::
.......

Note that all mathematical integers are representable not only as Common
Lisp reals, but also as complex floats.  For example, possible
representations of the mathematical number 1 include the integer 1, the
float 1.0, or the complex #C(1.0 0.0).


File: gcl.info,  Node: short-float,  Next: rational (System Class),  Prev: float (System Class),  Up: Numbers Dictionary

12.2.5 short-float, single-float, double-float, long-float [Type]
-----------------------------------------------------------------

Supertypes::
............

short-float: short-float, float,

   real,

   number, t

   single-float: single-float, float,

   real,

   number, t

   double-float: double-float, float,

   real,

   number, t

   long-float: long-float, float,

   real,

   number, t

Description::
.............

For the four defined subtypes of type float, it is true that
intermediate between the type short-float and the type long-float are
the type single-float and the type double-float.  The precise definition
of these categories is implementation-defined.  The precision (measured
in "bits", computed as p\log_2b) and the exponent size (also measured in
"bits," computed as \log_2(n+1), where n is the maximum exponent value)
is recommended to be at least as great as the values in Figure 12-11.
Each of the defined subtypes of type float might or might not have a
minus zero.

  Format  Minimum Precision  Minimum Exponent Size  
  __________________________________________________
  Short   13 bits            5 bits                 
  Single  24 bits            8 bits                 
  Double  50 bits            8 bits                 
  Long    50 bits            8 bits                 

  Figure 12-11: Recommended Minimum Floating-Point Precision and Exponent Size


   There can be fewer than four internal representations for floats.  If
there are fewer distinct representations, the following rules apply:

-
     If there is only one, it is the type single-float.  In this
     representation, an object is simultaneously of types single-float,
     double-float, short-float, and long-float.
-
     Two internal representations can be arranged in either of the
     following ways:

     *
          Two types are provided: single-float and short-float.  An
          object is simultaneously of types single-float, double-float,
          and long-float.
     *
          Two types are provided: single-float and double-float.  An
          object is simultaneously of types single-float and
          short-float, or double-float and long-float.

-
     Three internal representations can be arranged in either of the
     following ways:

     *
          Three types are provided: short-float, single-float, and
          double-float.  An object can simultaneously be of type
          double-float and long-float.
     *
          Three types are provided: single-float, double-float, and
          long-float.  An object can simultaneously be of types
          single-float and short-float.

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('short-float'{[short-lower-limit [short-upper-limit]]})
('single-float'{[single-lower-limit [single-upper-limit]]})
('double-float'{[double-lower-limit [double-upper-limit]]})
('long-float'{[long-lower-limit [long-upper-limit]]})

Compound Type Specifier Arguments::
...................................

short-lower-limit, short-upper-limit--interval designators for type
short-float.  The defaults for each of lower-limit and upper-limit is
the symbol *.

   single-lower-limit, single-upper-limit--interval designators for type
single-float.  The defaults for each of lower-limit and upper-limit is
the symbol *.

   double-lower-limit, double-upper-limit--interval designators for type
double-float.  The defaults for each of lower-limit and upper-limit is
the symbol *.

   long-lower-limit, long-upper-limit--interval designators for type
long-float.  The defaults for each of lower-limit and upper-limit is the
symbol *.

Compound Type Specifier Description::
.....................................

Each of these denotes the set of floats of the indicated type that are
on the interval specified by the interval designators.


File: gcl.info,  Node: rational (System Class),  Next: ratio,  Prev: short-float,  Up: Numbers Dictionary

12.2.6 rational [System Class]
------------------------------

Class Precedence List::
.......................

rational,

   real,

   number, t

Description::
.............

The canonical representation of a rational is as an integer if its value
is integral, and otherwise as a ratio.

   The types integer and ratio are disjoint subtypes of type rational.

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('rational'{[lower-limit [upper-limit]]})

Compound Type Specifier Arguments::
...................................

lower-limit, upper-limit--interval designators for type rational.  The
defaults for each of lower-limit and upper-limit is the symbol *.

Compound Type Specifier Description::
.....................................

This denotes the rationals on the interval described by lower-limit and
upper-limit.


File: gcl.info,  Node: ratio,  Next: integer,  Prev: rational (System Class),  Up: Numbers Dictionary

12.2.7 ratio [System Class]
---------------------------

Class Precedence List::
.......................

ratio, rational,

   real,

   number, t

Description::
.............

A ratio is a number representing the mathematical ratio of two non-zero
integers, the numerator and denominator, whose greatest common divisor
is one, and of which the denominator is positive and greater than one.

See Also::
..........

Figure~2-9, *note Constructing Numbers from Tokens::, *note Printing
Ratios::


File: gcl.info,  Node: integer,  Next: signed-byte,  Prev: ratio,  Up: Numbers Dictionary

12.2.8 integer [System Class]
-----------------------------

Class Precedence List::
.......................

integer, rational,

   real,

   number, t

Description::
.............

An integer is a mathematical integer.  There is no limit on the
magnitude of an integer.

   The types fixnum and bignum form an exhaustive partition of type
integer.

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('integer'{[lower-limit [upper-limit]]})

Compound Type Specifier Arguments::
...................................

lower-limit, upper-limit--interval designators for type integer.  The
defaults for each of lower-limit and upper-limit is the symbol *.

Compound Type Specifier Description::
.....................................

This denotes the integers on the interval described by lower-limit and
upper-limit.

See Also::
..........

Figure~2-9, *note Constructing Numbers from Tokens::, *note Printing
Integers::

Notes::
.......

The type (integer lower upper), where lower and upper are
most-negative-fixnum and most-positive-fixnum, respectively, is also
called fixnum.

   The type (integer 0 1) is also called bit.  The type (integer 0 *) is
also called unsigned-byte.


File: gcl.info,  Node: signed-byte,  Next: unsigned-byte,  Prev: integer,  Up: Numbers Dictionary

12.2.9 signed-byte [Type]
-------------------------

Supertypes::
............

signed-byte, integer, rational,

   real,

   number, t

Description::
.............

The atomic type specifier signed-byte denotes the same type as is
denoted by the type specifier integer; however, the list forms of these
two type specifiers have different semantics.

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('signed-byte'{[s | *]})

Compound Type Specifier Arguments::
...................................

s--a positive integer.

Compound Type Specifier Description::
.....................................

This denotes the set of integers that can be represented in
two's-complement form in a byte of s bits.  This is equivalent to
(integer -2^s-1 2^s-1-1).  The type signed-byte or the type (signed-byte
*) is the same as the type integer.


File: gcl.info,  Node: unsigned-byte,  Next: mod (System Class),  Prev: signed-byte,  Up: Numbers Dictionary

12.2.10 unsigned-byte [Type]
----------------------------

Supertypes::
............

unsigned-byte, signed-byte, integer, rational,

   real,

   number, t

Description::
.............

The atomic type specifier unsigned-byte denotes the same type as is
denoted by the type specifier (integer 0 *).

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('unsigned-byte'{[s | *]})

Compound Type Specifier Arguments::
...................................

s--a positive integer.

Compound Type Specifier Description::
.....................................

This denotes the set of non-negative integers that can be represented in
a byte of size s (bits).  This is equivalent to (mod m) for m=2^s, or to
(integer 0 n) for n=2^s-1.  The type unsigned-byte or the type
(unsigned-byte *) is the same as the type (integer 0 *), the set of
non-negative integers.

Notes::
.......

The type (unsigned-byte 1) is also called bit.


File: gcl.info,  Node: mod (System Class),  Next: bit (System Class),  Prev: unsigned-byte,  Up: Numbers Dictionary

12.2.11 mod [Type Specifier]
----------------------------

Compound Type Specifier Kind::
..............................

Abbreviating.

Compound Type Specifier Syntax::
................................

('mod'{n})

Compound Type Specifier Arguments::
...................................

n--a positive integer.

Compound Type Specifier Description::
.....................................

This denotes the set of non-negative integers less than n.  This is
equivalent to (integer 0 (n)) or to (integer 0 m), where m=n-1.

   The argument is required, and cannot be *.

   The symbol mod is not valid as a type specifier.


File: gcl.info,  Node: bit (System Class),  Next: fixnum,  Prev: mod (System Class),  Up: Numbers Dictionary

12.2.12 bit [Type]
------------------

Supertypes::
............

bit, unsigned-byte, signed-byte, integer, rational,

   real,

   number, t

Description::
.............

The type bit is equivalent to the type (integer 0 1) and (unsigned-byte
1).


File: gcl.info,  Node: fixnum,  Next: bignum,  Prev: bit (System Class),  Up: Numbers Dictionary

12.2.13 fixnum [Type]
---------------------

Supertypes::
............

fixnum, integer, rational,

   real,

   number, t

Description::
.............

A fixnum is an integer whose value is between most-negative-fixnum and
most-positive-fixnum inclusive.  Exactly which integers are fixnums is
implementation-defined.

   The type fixnum is required to be a supertype of (signed-byte 16).


File: gcl.info,  Node: bignum,  Next: =,  Prev: fixnum,  Up: Numbers Dictionary

12.2.14 bignum [Type]
---------------------

Supertypes::
............

bignum, integer, rational,

   real,

   number, t

Description::
.............

The type bignum is defined to be exactly (and integer (not fixnum)).


File: gcl.info,  Node: =,  Next: max,  Prev: bignum,  Up: Numbers Dictionary

12.2.15 =, /=, <, >, <=, >= [Function]
--------------------------------------

'=' &rest numbers^+ => generalized-boolean

   '/=' &rest numbers^+ => generalized-boolean

   '<' &rest numbers^+ => generalized-boolean

   '>' &rest numbers^+ => generalized-boolean

   '<=' &rest numbers^+ => generalized-boolean

   '>=' &rest numbers^+ => generalized-boolean

Arguments and Values::
......................

number--for <, >, <=, >=: a real; for =, /=: a number.

   generalized-boolean--a generalized boolean.

Description::
.............

=, /=, <, >, <=, and >= perform arithmetic comparisons on their
arguments as follows:

=
     The value of = is true if all numbers are the same in value;
     otherwise it is false.  Two complexes are considered equal by = if
     their real and imaginary parts are equal according to =.

/=
     The value of /= is true if no two numbers are the same in value;
     otherwise it is false.

<
     The value of < is true if the numbers are in monotonically
     increasing order; otherwise it is false.

>
     The value of > is true if the numbers are in monotonically
     decreasing order; otherwise it is false.

<=
     The value of <= is true if the numbers are in monotonically
     nondecreasing order; otherwise it is false.

>=
     The value of >= is true if the numbers are in monotonically
     nonincreasing order; otherwise it is false.

   =, /=, <, >, <=, and >= perform necessary type conversions.

Examples::
..........

The uses of these functions are illustrated in Figure 12-12.

  (= 3 3) is true.              (/= 3 3) is false.             
  (= 3 5) is false.             (/= 3 5) is true.              
  (= 3 3 3 3) is true.          (/= 3 3 3 3) is false.         
  (= 3 3 5 3) is false.         (/= 3 3 5 3) is false.         
  (= 3 6 5 2) is false.         (/= 3 6 5 2) is true.          
  (= 3 2 3) is false.           (/= 3 2 3) is false.           
  (< 3 5) is true.              (<= 3 5) is true.              
  (< 3 -5) is false.            (<= 3 -5) is false.            
  (< 3 3) is false.             (<= 3 3) is true.              
  (< 0 3 4 6 7) is true.        (<= 0 3 4 6 7) is true.        
  (< 0 3 4 4 6) is false.       (<= 0 3 4 4 6) is true.        
  (> 4 3) is true.              (>= 4 3) is true.              
  (> 4 3 2 1 0) is true.        (>= 4 3 2 1 0) is true.        
  (> 4 3 3 2 0) is false.       (>= 4 3 3 2 0) is true.        
  (> 4 3 1 2 0) is false.       (>= 4 3 1 2 0) is false.       
  (= 3) is true.                (/= 3) is true.                
  (< 3) is true.                (<= 3) is true.                
  (= 3.0 #c(3.0 0.0)) is true.  (/= 3.0 #c(3.0 1.0)) is true.  
  (= 3 3.0) is true.            (= 3.0s0 3.0d0) is true.       
  (= 0.0 -0.0) is true.         (= 5/2 2.5) is true.           
  (> 0.0 -0.0) is false.        (= 0 -0.0) is true.            
  (<= 0 x 9) is true if x is between 0 and 9, inclusive
  (< 0.0 x 1.0) is true if x is between 0.0 and 1.0, exclusive
  (< -1 j (length v)) is true if j is a valid array index for a vector v

         Figure 12-12: Uses of /=, =, <, >, <=, and >=        


Exceptional Situations::
........................

Might signal type-error if some argument is not a real.  Might signal
arithmetic-error if otherwise unable to fulfill its contract.

Notes::
.......

= differs from eql in that (= 0.0 -0.0) is always true, because =
compares the mathematical values of its operands, whereas eql compares
the representational values, so to speak.


File: gcl.info,  Node: max,  Next: minusp,  Prev: =,  Up: Numbers Dictionary

12.2.16 max, min [Function]
---------------------------

'max' &rest reals^+ => max-real

   'min' &rest reals^+ => min-real

Arguments and Values::
......................

real--a real.

   max-real, min-real--a real.

Description::
.............

max returns the real that is greatest (closest to positive infinity).
min returns the real that is least (closest to negative infinity).

   For max, the implementation has the choice of returning the largest
argument as is or applying the rules of floating-point contagion, taking
all the arguments into consideration for contagion purposes.  Also, if
one or more of the arguments are =, then any one of them may be chosen
as the value to return.  For example, if the reals are a mixture of
rationals and floats, and the largest argument is a rational, then the
implementation is free to produce either that rational or its float
approximation; if the largest argument is a float of a smaller format
than the largest format of any float argument, then the implementation
is free to return the argument in its given format or expanded to the
larger format.  Similar remarks apply to min (replacing "largest
argument" by "smallest argument").

Examples::
..........

      (max 3) =>  3
      (min 3) =>  3
      (max 6 12) =>  12
      (min 6 12) =>  6
      (max -6 -12) =>  -6
      (min -6 -12) =>  -12
      (max 1 3 2 -7) =>  3
      (min 1 3 2 -7) =>  -7
      (max -2 3 0 7) =>  7
      (min -2 3 0 7) =>  -2
      (max 5.0 2) =>  5.0
      (min 5.0 2)
     =>  2
     OR=> 2.0
      (max 3.0 7 1)
     =>  7
     OR=> 7.0
      (min 3.0 7 1)
     =>  1
     OR=> 1.0
      (max 1.0s0 7.0d0) =>  7.0d0
      (min 1.0s0 7.0d0)
     =>  1.0s0
     OR=> 1.0d0
      (max 3 1 1.0s0 1.0d0)
     =>  3
     OR=> 3.0d0
      (min 3 1 1.0s0 1.0d0)
     =>  1
     OR=> 1.0s0
     OR=> 1.0d0

Exceptional Situations::
........................

Should signal an error of type type-error if any number is not a real.


File: gcl.info,  Node: minusp,  Next: zerop,  Prev: max,  Up: Numbers Dictionary

12.2.17 minusp, plusp [Function]
--------------------------------

'minusp' real => generalized-boolean

   'plusp' real => generalized-boolean

Arguments and Values::
......................

real--a real.

   generalized-boolean--a generalized boolean.

Description::
.............

minusp returns true if real is less than zero; otherwise, returns false.

   plusp returns true if real is greater than zero; otherwise, returns
false.

   Regardless of whether an implementation provides distinct
representations for positive and negative float zeros, (minusp -0.0)
always returns false.

Examples::
..........

      (minusp -1) =>  true
      (plusp 0) =>  false
      (plusp least-positive-single-float) =>  true

Exceptional Situations::
........................

Should signal an error of type type-error if real is not a real.


File: gcl.info,  Node: zerop,  Next: floor,  Prev: minusp,  Up: Numbers Dictionary

12.2.18 zerop [Function]
------------------------

'zerop' number => generalized-boolean

Pronunciation::
...............

pronounced 'z\=e (, )r\=o(, )p\=e

Arguments and Values::
......................

number--a number.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if number is zero (integer, float, or complex); otherwise,
returns false.

   Regardless of whether an implementation provides distinct
representations for positive and negative floating-point zeros, (zerop
-0.0) always returns true.

Examples::
..........

      (zerop 0) =>  true
      (zerop 1) =>  false
      (zerop -0.0) =>  true
      (zerop 0/100) =>  true
      (zerop #c(0 0.0)) =>  true

Exceptional Situations::
........................

Should signal an error of type type-error if number is not a number.

Notes::
.......

      (zerop number) == (= number 0)


File: gcl.info,  Node: floor,  Next: sin,  Prev: zerop,  Up: Numbers Dictionary

12.2.19 floor, ffloor, ceiling, fceiling,
-----------------------------------------

truncate, ftruncate, round, fround
----------------------------------

                                                             [Function]

   'floor' number &optional divisor => quotient, remainder

   'ffloor' number &optional divisor => quotient, remainder

   'ceiling' number &optional divisor => quotient, remainder

   'fceiling' number &optional divisor => quotient, remainder

   'truncate' number &optional divisor => quotient, remainder

   'ftruncate' number &optional divisor => quotient, remainder

   'round' number &optional divisor => quotient, remainder

   'fround' number &optional divisor => quotient, remainder

Arguments and Values::
......................

number--a real.

   divisor--a non-zero real.  The default is the integer 1.

   quotient--for floor, ceiling, truncate, and round: an integer; for
ffloor, fceiling, ftruncate, and fround: a float.

   remainder--a real.

Description::
.............

These functions divide number by divisor, returning a quotient and
remainder, such that

   quotient\cdot divisor+remainder=number

   The quotient always represents a mathematical integer.  When more
than one mathematical integer might be possible (i.e., when the
remainder is not zero), the kind of rounding or truncation depends on
the operator:

floor, ffloor
     floor and ffloor produce a quotient that has been truncated toward
     negative infinity; that is, the quotient represents the largest
     mathematical integer that is not larger than the mathematical
     quotient.

ceiling, fceiling
     ceiling and fceiling produce a quotient that has been truncated
     toward positive infinity; that is, the quotient represents the
     smallest mathematical integer that is not smaller than the
     mathematical result.

truncate, ftruncate
     truncate and ftruncate produce a quotient that has been truncated
     towards zero; that is, the quotient represents the mathematical
     integer of the same sign as the mathematical quotient, and that has
     the greatest integral magnitude not greater than that of the
     mathematical quotient.

round, fround
     round and fround produce a quotient that has been rounded to the
     nearest mathematical integer; if the mathematical quotient is
     exactly halfway between two integers, (that is, it has the form
     integer+1\over2), then the quotient has been rounded to the even
     (divisible by two) integer.

   All of these functions perform type conversion operations on numbers.

   The remainder is an integer if both x and y are integers, is a
rational if both x and y are rationals, and is a float if either x or y
is a float.

   ffloor, fceiling, ftruncate, and fround handle arguments of different
types in the following way: If number is a float, and divisor is not a
float of longer format, then the first result is a float of the same
type as number.  Otherwise, the first result is of the type determined
by contagion rules; see *note Contagion in Numeric Operations::.

Examples::
..........

      (floor 3/2) =>  1, 1/2
      (ceiling 3 2) =>  2, -1
      (ffloor 3 2) =>  1.0, 1
      (ffloor -4.7) =>  -5.0, 0.3
      (ffloor 3.5d0) =>  3.0d0, 0.5d0
      (fceiling 3/2) =>  2.0, -1/2
      (truncate 1) =>  1, 0
      (truncate .5) =>  0, 0.5
      (round .5) =>  0, 0.5
      (ftruncate -7 2) =>  -3.0, -1
      (fround -7 2) =>  -4.0, 1
      (dolist (n '(2.6 2.5 2.4 0.7 0.3 -0.3 -0.7 -2.4 -2.5 -2.6))
        (format t "~&~4,1@F ~2,' D ~2,' D ~2,' D ~2,' D"
                n (floor n) (ceiling n) (truncate n) (round n)))
      |>  +2.6  2  3  2  3
      |>  +2.5  2  3  2  2
      |>  +2.4  2  3  2  2
      |>  +0.7  0  1  0  1
      |>  +0.3  0  1  0  0
      |>  -0.3 -1  0  0  0
      |>  -0.7 -1  0  0 -1
      |>  -2.4 -3 -2 -2 -2
      |>  -2.5 -3 -2 -2 -2
      |>  -2.6 -3 -2 -2 -3
     =>  NIL

Notes::
.......

When only number is given, the two results are exact; the mathematical
sum of the two results is always equal to the mathematical value of
number.

   (function number divisor) and (function (/ number divisor)) (where
function is any of one of floor, ceiling, ffloor, fceiling, truncate,
round, ftruncate, and fround) return the same first value, but they
return different remainders as the second value.  For example:

      (floor 5 2) =>  2, 1
      (floor (/ 5 2)) =>  2, 1/2

   If an effect is desired that is similar to round, but that always
rounds up or down (rather than toward the nearest even integer) if the
mathematical quotient is exactly halfway between two integers, the
programmer should consider a construction such as (floor (+ x 1/2)) or
(ceiling (- x 1/2)).


File: gcl.info,  Node: sin,  Next: asin,  Prev: floor,  Up: Numbers Dictionary

12.2.20 sin, cos, tan [Function]
--------------------------------

'sin' radians => number

   'cos' radians => number

   'tan' radians => number

Arguments and Values::
......................

radians--a number given in radians.

   number--a number.

Description::
.............

sin, cos, and tan return the sine, cosine, and tangent, respectively, of
radians.

Examples::
..........

      (sin 0) =>  0.0
      (cos 0.7853982) =>  0.707107
      (tan #c(0 1)) =>  #C(0.0 0.761594)

Exceptional Situations::
........................

Should signal an error of type type-error if radians is not a number.
Might signal arithmetic-error.

See Also::
..........

*note asin:: , acos, atan, *note Rule of Float Substitutability::


File: gcl.info,  Node: asin,  Next: pi,  Prev: sin,  Up: Numbers Dictionary

12.2.21 asin, acos, atan [Function]
-----------------------------------

'asin' number => radians

   'acos' number => radians

   'atan' number1 &optional number2 => radians

Arguments and Values::
......................

number--a number.

   number1--a number if number2 is not supplied, or a real if number2 is
supplied.

   number2--a real.

   radians--a number (of radians).

Description::
.............

asin, acos, and atan compute the arc sine, arc cosine, and arc tangent
respectively.

   The arc sine, arc cosine, and arc tangent (with only number1
supplied) functions can be defined mathematically for number or number1
specified as x as in Figure 12-13.

  Function     Definition                            
  Arc sine      -i log  (ix+ \sqrt1-x^2 )          
  Arc cosine    (\pi/2) - arcsin  x                  
  Arc tangent   -i log  ((1+ix) \sqrt1/(1+x^2) )   

  Figure 12-13: Mathematical definition of arc sine, arc cosine, and arc tangent


   These formulae are mathematically correct, assuming completely
accurate computation.  They are not necessarily the simplest ones for
real-valued computations.

   If both number1 and number2 are supplied for atan, the result is the
arc tangent of number1/number2.  The value of atan is always between
-\pi (exclusive) and~\pi (inclusive)

   when minus zero is not supported.  The range of the two-argument arc
tangent when minus zero is supported includes -\pi.

   For a

   real

   number1, the result is

   a real

   and lies between -\pi/2 and~\pi/2 (both exclusive).  number1 can be a
complex if number2 is not supplied.  If both are supplied, number2 can
be zero provided number1 is not zero.

   [Reviewer Note by Barmar: Should add "However, if the implementation
distinguishes positive and negative zero, both may be signed zeros, and
limits are used to define the result."]

   The following definition for arc sine determines the range and branch
cuts:

                arcsin z = -i log (iz+\sqrt1-z^2\Bigr)

   The branch cut for the arc sine function is in two pieces: one along
the negative real axis to the left of~-1 (inclusive), continuous with
quadrant II, and one along the positive real axis to the right of~1
(inclusive), continuous with quadrant IV. The range is that strip of the
complex plane containing numbers whose real part is between -\pi/2
and~\pi/2.  A number with real part equal to -\pi/2 is in the range if
and only if its imaginary part is non-negative; a number with real part
equal to \pi/2 is in the range if and only if its imaginary part is
non-positive.

   The following definition for arc cosine determines the range and
branch cuts:

                    arccos z = \pi\over2 - arcsin z

   or, which are equivalent,

                arccos z = -i log (z+i \sqrt1-z^2\Bigr)

        arccos z = 2 log (\sqrt(1+z)/2 + i \sqrt(1-z)/2)\overi

   The branch cut for the arc cosine function is in two pieces: one
along the negative real axis to the left of~-1 (inclusive), continuous
with quadrant II, and one along the positive real axis to the right of~1
(inclusive), continuous with quadrant IV. This is the same branch cut as
for arc sine.  The range is that strip of the complex plane containing
numbers whose real part is between 0 and~\pi.  A number with real part
equal to 0 is in the range if and only if its imaginary part is
non-negative; a number with real part equal to \pi is in the range if
and only if its imaginary part is non-positive.

   The following definition for (one-argument) arc tangent determines
the range and branch cuts:

               arctan z = log (1+iz) - log (1-iz)\over2i

   Beware of simplifying this formula; "obvious" simplifications are
likely to alter the branch cuts or the values on the branch cuts
incorrectly.  The branch cut for the arc tangent function is in two
pieces: one along the positive imaginary axis above i (exclusive),
continuous with quadrant II, and one along the negative imaginary axis
below -i (exclusive), continuous with quadrant IV. The points i and~-i
are excluded from the domain.  The range is that strip of the complex
plane containing numbers whose real part is between -\pi/2 and~\pi/2.  A
number with real part equal to -\pi/2 is in the range if and only if its
imaginary part is strictly positive; a number with real part equal to
\pi/2 is in the range if and only if its imaginary part is strictly
negative.  Thus the range of arc tangent is identical to that of arc
sine with the points -\pi/2 and~\pi/2 excluded.

   For atan, the signs of number1 (indicated as x) and number2
(indicated as y) are used to derive quadrant information.  Figure 12-14
details various special cases.

   The asterisk (*) indicates that the entry in the figure applies to
implementations that support minus zero.

   to 1pcy Condition  x Condition  Cartesian locus  Range of result          
   to 1pc y = 0        x > 0       Positive x-axis   0                       
   to 1pc* y = +0      x > 0       Positive x-axis  +0                       
   to 1pc* y = -0      x > 0       Positive x-axis  -0                       
   to 1pc y > 0        x > 0       Quadrant I       0 < result < \pi/2      
   to 1pc y > 0        x = 0       Positive y-axis  \pi/2                    
   to 1pc y > 0        x < 0       Quadrant II      \pi/2 < result < \pi    
   to 1pc y = 0        x < 0       Negative x-axis   \pi                     
   to 1pc* y = +0      x < 0       Negative x-axis  +\pi                     
   to 1pc* y = -0      x < 0       Negative x-axis  -\pi                     
   to 1pc y < 0        x < 0       Quadrant III     -\pi < result < -\pi/2  
   to 1pc y < 0        x = 0       Negative y-axis  -\pi/2                   
   to 1pc y < 0        x > 0       Quadrant IV      -\pi/2 < result < 0     
   to 1pc y = 0        x = 0       Origin           undefined consequences   
   to 1pc* y = +0      x = +0      Origin           +0                       
   to 1pc* y = -0      x = +0      Origin           -0                       
   to 1pc* y = +0      x = -0      Origin           +\pi                     
   to 1pc* y = -0      x = -0      Origin           -\pi                     

               Figure 12-14: Quadrant information for arc tangent             


Examples::
..........

      (asin 0) =>  0.0
      (acos #c(0 1))  =>  #C(1.5707963267948966 -0.8813735870195432)
      (/ (atan 1 (sqrt 3)) 6)  =>  0.087266
      (atan #c(0 2)) =>  #C(-1.5707964 0.54930615)

Exceptional Situations::
........................

acos and asin should signal an error of type type-error if number is not
a number.  atan should signal type-error if one argument is supplied and
that argument is not a number, or if two arguments are supplied and both
of those arguments are not reals.

   acos, asin, and atan might signal arithmetic-error.

See Also::
..........

*note log:: , *note sqrt:: , *note Rule of Float Substitutability::

Notes::
.......

The result of either asin or acos can be a complex even if number is not
a complex; this occurs when the absolute value of number is greater than
one.


File: gcl.info,  Node: pi,  Next: sinh,  Prev: asin,  Up: Numbers Dictionary

12.2.22 pi [Constant Variable]
------------------------------

Value::
.......

an implementation-dependent long float.

Description::
.............

The best long float approximation to the mathematical constant \pi.

Examples::
..........

      ;; In each of the following computations, the precision depends
      ;; on the implementation.  Also, if `long float' is treated by
      ;; the implementation as equivalent to some other float format
      ;; (e.g., `double float') the exponent marker might be the marker
      ;; for that equivalent (e.g., `D' instead of `L').
      pi =>  3.141592653589793L0
      (cos pi) =>  -1.0L0

      (defun sin-of-degrees (degrees)
        (let ((x (if (floatp degrees) degrees (float degrees pi))))
          (sin (* x (/ (float pi x) 180)))))

Notes::
.......

An approximation to \pi in some other precision can be obtained by
writing (float pi x), where x is a float of the desired precision, or by
writing (coerce pi type), where type is the desired type, such as
short-float.


File: gcl.info,  Node: sinh,  Next: *,  Prev: pi,  Up: Numbers Dictionary

12.2.23 sinh, cosh, tanh, asinh, acosh, atanh [Function]
--------------------------------------------------------

'sinh' number => result

   'cosh' number => result

   'tanh' number => result

   'asinh' number => result

   'acosh' number => result

   'atanh' number => result

Arguments and Values::
......................

number--a number.

   result--a number.

Description::
.............

These functions compute the hyperbolic sine, cosine, tangent, arc sine,
arc cosine, and arc tangent functions, which are mathematically defined
for an argument x as given in Figure 12-15.

  Function                Definition                                  
  Hyperbolic sine          (e^x-e^-x)/2                             
  Hyperbolic cosine        (e^x+e^-x)/2                             
  Hyperbolic tangent       (e^x-e^-x)/(e^x+e^-x)                  
  Hyperbolic arc sine      log  (x+\sqrt1+x^2)                      
  Hyperbolic arc cosine    2 log  (\sqrt(x+1)/2 + \sqrt(x-1)/2)   
  Hyperbolic arc tangent   (log  (1+x) - log (1-x))/2                 

    Figure 12-15: Mathematical definitions for hyperbolic functions  


   The following definition for the inverse hyperbolic cosine determines
the range and branch cuts:

         arccosh z = 2 log (\sqrt(z+1)/2 + \sqrt(z-1)/2\Bigr).

   The branch cut for the inverse hyperbolic cosine function lies along
the real axis to the left of~1 (inclusive), extending indefinitely along
the negative real axis, continuous with quadrant II and (between 0
and~1) with quadrant I. The range is that half-strip of the complex
plane containing numbers whose real part is non-negative and whose
imaginary part is between -\pi (exclusive) and~\pi (inclusive).  A
number with real part zero is in the range if its imaginary part is
between zero (inclusive) and~\pi (inclusive).

   The following definition for the inverse hyperbolic sine determines
the range and branch cuts:

                 arcsinh z = log (z+\sqrt1+z^2\Bigr).

   The branch cut for the inverse hyperbolic sine function is in two
pieces: one along the positive imaginary axis above i (inclusive),
continuous with quadrant I, and one along the negative imaginary axis
below -i (inclusive), continuous with quadrant III. The range is that
strip of the complex plane containing numbers whose imaginary part is
between -\pi/2 and~\pi/2.  A number with imaginary part equal to -\pi/2
is in the range if and only if its real part is non-positive; a number
with imaginary part equal to \pi/2 is in the range if and only if its
imaginary part is non-negative.

   The following definition for the inverse hyperbolic tangent
determines the range and branch cuts:

               arctanh z = log (1+z) - log (1-z)\over2.

   Note that:

                       i arctan z = arctanh iz.

   The branch cut for the inverse hyperbolic tangent function is in two
pieces: one along the negative real axis to the left of -1 (inclusive),
continuous with quadrant III, and one along the positive real axis to
the right of~1 (inclusive), continuous with quadrant I. The points -1
and~1 are excluded from the domain.  The range is that strip of the
complex plane containing numbers whose imaginary part is between -\pi/2
and \pi/2.  A number with imaginary part equal to -\pi/2 is in the range
if and only if its real part is strictly negative; a number with
imaginary part equal to \pi/2 is in the range if and only if its
imaginary part is strictly positive.  Thus the range of the inverse
hyperbolic tangent function is identical to that of the inverse
hyperbolic sine function with the points -\pi i/2 and~\pi i/2 excluded.

Examples::
..........

      (sinh 0) =>  0.0
      (cosh (complex 0 -1)) =>  #C(0.540302 -0.0)

Exceptional Situations::
........................

Should signal an error of type type-error if number is not a number.
Might signal arithmetic-error.

See Also::
..........

*note log:: , *note sqrt:: , *note Rule of Float Substitutability::

Notes::
.......

The result of acosh may be a complex even if number is not a complex;
this occurs when number is less than one.  Also, the result of atanh may
be a complex even if number is not a complex; this occurs when the
absolute value of number is greater than one.

   The branch cut formulae are mathematically correct, assuming
completely accurate computation.  Implementors should consult a good
text on numerical analysis.  The formulae given above are not
necessarily the simplest ones for real-valued computations; they are
chosen to define the branch cuts in desirable ways for the complex case.


File: gcl.info,  Node: *,  Next: +,  Prev: sinh,  Up: Numbers Dictionary

12.2.24 * [Function]
--------------------

'*' &rest numbers => product

Arguments and Values::
......................

number--a number.

   product--a number.

Description::
.............

Returns the product of numbers, performing any necessary type
conversions in the process.  If no numbers are supplied, 1 is returned.

Examples::
..........

      (*) =>  1
      (* 3 5) =>  15
      (* 1.0 #c(22 33) 55/98) =>  #C(12.346938775510203 18.520408163265305)

Exceptional Situations::
........................

Might signal type-error if some argument is not a number.  Might signal
arithmetic-error.

See Also::
..........

*note Numeric Operations::, *note Rational Computations::, *note
Floating-point Computations::, *note Complex Computations::


File: gcl.info,  Node: +,  Next: -,  Prev: *,  Up: Numbers Dictionary

12.2.25 + [Function]
--------------------

'+' &rest numbers => sum

Arguments and Values::
......................

number--a number.

   sum--a number.

Description::
.............

Returns the sum of numbers, performing any necessary type conversions in
the process.  If no numbers are supplied, 0 is returned.

Examples::
..........

      (+) =>  0
      (+ 1) =>  1
      (+ 31/100 69/100) =>  1
      (+ 1/5 0.8) =>  1.0

Exceptional Situations::
........................

Might signal type-error if some argument is not a number.  Might signal
arithmetic-error.

See Also::
..........

*note Numeric Operations::, *note Rational Computations::, *note
Floating-point Computations::, *note Complex Computations::


File: gcl.info,  Node: -,  Next: /,  Prev: +,  Up: Numbers Dictionary

12.2.26 - [Function]
--------------------

'-' number => negation

   '-' minuend &rest subtrahends^+ => difference

Arguments and Values::
......................

number, minuend, subtrahend--a number.

   negation, difference--a number.

Description::
.............

The function - performs arithmetic subtraction and negation.

   If only one number is supplied, the negation of that number is
returned.

   If more than one argument is given, it subtracts all of the
subtrahends from the minuend and returns the result.

   The function - performs necessary type conversions.

Examples::
..........

      (- 55.55) =>  -55.55
      (- #c(3 -5)) =>  #C(-3 5)
      (- 0) =>  0
      (eql (- 0.0) -0.0) =>  true
      (- #c(100 45) #c(0 45)) =>  100
      (- 10 1 2 3 4) =>  0

Exceptional Situations::
........................

Might signal type-error if some argument is not a number.  Might signal
arithmetic-error.

See Also::
..........

*note Numeric Operations::, *note Rational Computations::, *note
Floating-point Computations::, *note Complex Computations::


File: gcl.info,  Node: /,  Next: 1+,  Prev: -,  Up: Numbers Dictionary

12.2.27 / [Function]
--------------------

'/' number => reciprocal

   '/' numerator &rest denominators^+ => quotient

Arguments and Values::
......................

number, denominator--a non-zero number.

   numerator, quotient, reciprocal--a number.

Description::
.............

The function / performs division or reciprocation.

   If no denominators are supplied, the function / returns the
reciprocal of number.

   If at least one denominator is supplied, the function / divides the
numerator by all of the denominators and returns the resulting quotient.

   If each argument is either an integer or a ratio, and the result is
not an integer, then it is a ratio.

   The function / performs necessary type conversions.

   If any argument is a float then the rules of floating-point contagion
apply; see *note Floating-point Computations::.

Examples::
..........

      (/ 12 4) =>  3
      (/ 13 4) =>  13/4
      (/ -8) =>  -1/8
      (/ 3 4 5) =>  3/20
      (/ 0.5) =>  2.0
      (/ 20 5) =>  4
      (/ 5 20) =>  1/4
      (/ 60 -2 3 5.0) =>  -2.0
      (/ 2 #c(2 2)) =>  #C(1/2 -1/2)

Exceptional Situations::
........................

The consequences are unspecified if any argument other than the first is
zero.  If there is only one argument, the consequences are unspecified
if it is zero.

   Might signal type-error if some argument is not a number.  Might
signal division-by-zero if division by zero is attempted.  Might signal
arithmetic-error.

See Also::
..........

*note floor:: , ceiling, truncate, round


File: gcl.info,  Node: 1+,  Next: abs,  Prev: /,  Up: Numbers Dictionary

12.2.28 1+, 1- [Function]
-------------------------

'1' + => number successor '1' - => number predecessor

Arguments and Values::
......................

number--a number.

   successor, predecessor--a number.

Description::
.............

1+ returns a number that is one more than its argument number.  1-
returns a number that is one less than its argument number.

Examples::
..........

      (1+ 99) =>  100
      (1- 100) =>  99
      (1+ (complex 0.0)) =>  #C(1.0 0.0)
      (1- 5/3) =>  2/3

Exceptional Situations::
........................

Might signal type-error if its argument is not a number.  Might signal
arithmetic-error.

See Also::
..........

*note incf:: , decf

Notes::
.......

      (1+ number) == (+ number 1)
      (1- number) == (- number 1)

   Implementors are encouraged to make the performance of both the
previous expressions be the same.


File: gcl.info,  Node: abs,  Next: evenp,  Prev: 1+,  Up: Numbers Dictionary

12.2.29 abs [Function]
----------------------

'abs' number => absolute-value

Arguments and Values::
......................

number--a number.

   absolute-value--a non-negative real.

Description::
.............

abs returns the absolute value of number.

   If number is

   a real,

   the result is of the same type as number.

   If number is a complex, the result is a positive

   real

   with the same magnitude as number.  The result can be a float

   [Reviewer Note by Barmar: Single-float.]  even if number's components
are rationals and an exact rational result would have been possible.
Thus the result of (abs #c(3 4)) can be either 5 or 5.0, depending on
the implementation.

Examples::
..........

      (abs 0) =>  0
      (abs 12/13) =>  12/13
      (abs -1.09) =>  1.09
      (abs #c(5.0 -5.0)) =>  7.071068
      (abs #c(5 5)) =>  7.071068
      (abs #c(3/5 4/5)) =>  1 or approximately 1.0
      (eql (abs -0.0) -0.0) =>  true

See Also::
..........

*note Rule of Float Substitutability::

Notes::
.......

If number is a complex, the result is equivalent to the following:

   (sqrt (+ (expt (realpart number) 2) (expt (imagpart number) 2)))

   An implementation should not use this formula directly for all
complexes but should handle very large or very small components
specially to avoid intermediate overflow or underflow.


File: gcl.info,  Node: evenp,  Next: exp,  Prev: abs,  Up: Numbers Dictionary

12.2.30 evenp, oddp [Function]
------------------------------

'evenp' integer => generalized-boolean

   'oddp' integer => generalized-boolean

Arguments and Values::
......................

integer--an integer.

   generalized-boolean--a generalized boolean.

Description::
.............

evenp returns true if integer is even (divisible by two); otherwise,
returns false.

   oddp returns true if integer is odd (not divisible by two);
otherwise, returns false.

Examples::
..........

      (evenp 0) =>  true
      (oddp 10000000000000000000000) =>  false
      (oddp -1) =>  true

Exceptional Situations::
........................

Should signal an error of type type-error if integer is not an integer.

Notes::
.......

      (evenp integer) == (not (oddp integer))
      (oddp integer)  == (not (evenp integer))


File: gcl.info,  Node: exp,  Next: gcd,  Prev: evenp,  Up: Numbers Dictionary

12.2.31 exp, expt [Function]
----------------------------

'exp' number => result

   'expt' base-number power-number => result

Arguments and Values::
......................

number--a number.

   base-number--a number.

   power-number--a number.

   result--a number.

Description::
.............

exp and expt perform exponentiation.

   exp returns e raised to the power number, where e is the base of the
natural logarithms.  exp has no branch cut.

   expt returns base-number raised to the power power-number.  If the
base-number is a rational and power-number is an integer, the
calculation is exact and the result will be of type rational; otherwise
a floating-point approximation might result.

   For expt of a complex rational to an integer power, the calculation
must be exact and the result is of type (or rational (complex
rational)).

   The result of expt can be a complex, even when neither argument is a
complex, if base-number is negative and power-number is not an integer.
The result is always the principal complex value.  For example, (expt -8
1/3) is not permitted to return -2, even though -2 is one of the cube
roots of -8.  The principal cube root is a complex approximately equal
to #C(1.0 1.73205), not -2.

   expt is defined as b^x = e^x log b\/.  This defines the principal
values precisely.  The range of expt is the entire complex plane.
Regarded as a function of x, with b fixed, there is no branch cut.
Regarded as a function of b, with x fixed, there is in general a branch
cut along the negative real axis, continuous with quadrant II. The
domain excludes the origin.  By definition, 0^0=1.  If b=0 and the real
part of x is strictly positive, then b^x=0.  For all other values of x,
0^x is an error.

   When power-number is an integer 0, then the result is always the
value one in the type of base-number, even if the base-number is zero
(of any type).  That is:

      (expt x 0) == (coerce 1 (type-of x))

   If power-number is a zero of any other type, then the result is also
the value one, in the type of the arguments after the application of the
contagion rules in *note Contagion in Numeric Operations::, with one
exception: the consequences are undefined if base-number is zero when
power-number is zero and not of type integer.

Examples::
..........

      (exp 0) =>  1.0
      (exp 1) =>  2.718282
      (exp (log 5)) =>  5.0
      (expt 2 8) =>  256
      (expt 4 .5) =>  2.0
      (expt #c(0 1) 2) =>  -1
      (expt #c(2 2) 3) =>  #C(-16 16)
      (expt #c(2 2) 4) =>  -64

See Also::
..........

*note log:: , *note Rule of Float Substitutability::

Notes::
.......

Implementations of expt are permitted to use different algorithms for
the cases of a power-number of type rational and a power-number of type
float.

   Note that by the following logic, (sqrt (expt x 3)) is not equivalent
to (expt x 3/2).

      (setq x (exp (/ (* 2 pi #c(0 1)) 3)))         ;exp(2.pi.i/3)
      (expt x 3) =>  1 ;except for round-off error
      (sqrt (expt x 3)) =>  1 ;except for round-off error
      (expt x 3/2) =>  -1 ;except for round-off error


File: gcl.info,  Node: gcd,  Next: incf,  Prev: exp,  Up: Numbers Dictionary

12.2.32 gcd [Function]
----------------------

'gcd' &rest integers => greatest-common-denominator

Arguments and Values::
......................

integer--an integer.

   greatest-common-denominator--a non-negative integer.

Description::
.............

Returns the greatest common divisor of integers.  If only one integer is
supplied, its absolute value is returned.  If no integers are given, gcd
returns 0, which is an identity for this operation.

Examples::
..........

      (gcd) =>  0
      (gcd 60 42) =>  6
      (gcd 3333 -33 101) =>  1
      (gcd 3333 -33 1002001) =>  11
      (gcd 91 -49) =>  7
      (gcd 63 -42 35) =>  7
      (gcd 5) =>  5
      (gcd -4) =>  4

Exceptional Situations::
........................

Should signal an error of type type-error if any integer is not an
integer.

See Also::
..........

*note lcm::

Notes::
.......

For three or more arguments,

      (gcd b c ... z) == (gcd (gcd a b) c ... z)


File: gcl.info,  Node: incf,  Next: lcm,  Prev: gcd,  Up: Numbers Dictionary

12.2.33 incf, decf [Macro]
--------------------------

'incf' place [delta-form] => new-value

   'decf' place [delta-form] => new-value

Arguments and Values::
......................

place--a place.

   delta-form--a form; evaluated to produce a delta.  The default is 1.

   delta--a number.

   new-value--a number.

Description::
.............

incf and decf are used for incrementing and decrementing the value of
place, respectively.

   The delta is added to (in the case of incf) or subtracted from (in
the case of decf) the number in place and the result is stored in place.

   Any necessary type conversions are performed automatically.

   For information about the evaluation of subforms of places, see *note
Evaluation of Subforms to Places::.

Examples::
..........

      (setq n 0)
      (incf n) =>  1
      n =>  1
      (decf n 3) =>  -2
      n =>  -2
      (decf n -5) =>  3
      (decf n) =>  2
      (incf n 0.5) =>  2.5
      (decf n) =>  1.5
      n =>  1.5

Side Effects::
..............

Place is modified.

See Also::
..........

+, *note -:: , 1+, 1-, *note setf::


File: gcl.info,  Node: lcm,  Next: log,  Prev: incf,  Up: Numbers Dictionary

12.2.34 lcm [Function]
----------------------

'lcm' &rest integers => least-common-multiple

Arguments and Values::
......................

integer--an integer.

   least-common-multiple--a non-negative integer.

Description::
.............

lcm returns the least common multiple of the integers.

   If no integer is supplied, the integer 1 is returned.

   If only one integer is supplied, the absolute value of that integer
is returned.

   For two arguments that are not both zero,

      (lcm a b) == (/ (abs (* a b)) (gcd a b))

   If one or both arguments are zero,

      (lcm a 0) == (lcm 0 a) == 0

   For three or more arguments,

      (lcm a b c ... z) == (lcm (lcm a b) c ... z)

Examples::
..........

      (lcm 10) =>  10
      (lcm 25 30) =>  150
      (lcm -24 18 10) =>  360
      (lcm 14 35) =>  70
      (lcm 0 5) =>  0
      (lcm 1 2 3 4 5 6) =>  60

Exceptional Situations::
........................

Should signal type-error if any argument is not an integer.

See Also::
..........

*note gcd::


File: gcl.info,  Node: log,  Next: mod (Function),  Prev: lcm,  Up: Numbers Dictionary

12.2.35 log [Function]
----------------------

'log' number &optional base => logarithm

Arguments and Values::
......................

number--a non-zero number.

   base--a number.

   logarithm--a number.

Description::
.............

log returns the logarithm of number in base base.  If base is not
supplied its value is e, the base of the natural logarithms.

   log may return a complex when given a

   real

   negative number.

      (log -1.0) == (complex 0.0 (float pi 0.0))

   If base is zero, log returns zero.

   The result of (log 8 2) may be either 3 or 3.0, depending on the
implementation.  An implementation can use floating-point calculations
even if an exact integer result is possible.

   The branch cut for the logarithm function of one argument (natural
logarithm) lies along the negative real axis, continuous with quadrant
II. The domain excludes the origin.

   The mathematical definition of a complex logarithm is as follows,
whether or not minus zero is supported by the implementation:

     (log x) == (complex (log (abs x)) (phase x))

   Therefore the range of the one-argument logarithm function is that
strip of the complex plane containing numbers with imaginary parts
between

   -\pi (exclusive) and~\pi (inclusive) if minus zero is not supported,
or -\pi (inclusive) and~\pi (inclusive) if minus zero is supported.

   The two-argument logarithm function is defined as

      (log base number)
      == (/ (log number) (log base))

   This defines the principal values precisely.  The range of the
two-argument logarithm function is the entire complex plane.

Examples::
..........

      (log 100 10)
     =>  2.0
     =>  2
      (log 100.0 10) =>  2.0
      (log #c(0 1) #c(0 -1))
     =>  #C(-1.0 0.0)
     OR=> #C(-1 0)
      (log 8.0 2) =>  3.0

      (log #c(-16 16) #c(2 2)) =>  3 or approximately #c(3.0 0.0)
                                    or approximately 3.0 (unlikely)

Affected By::
.............

The implementation.

See Also::
..........

*note exp:: , expt, *note Rule of Float Substitutability::


File: gcl.info,  Node: mod (Function),  Next: signum,  Prev: log,  Up: Numbers Dictionary

12.2.36 mod, rem [Function]
---------------------------

'mod' number divisor => modulus

   'rem' number divisor => remainder

Arguments and Values::
......................

number--a real.

   divisor--a real.

   modulus, remainder--a real.

Description::
.............

mod and rem are generalizations of the modulus and remainder functions
respectively.

   mod performs the operation floor on number and divisor and returns
the remainder of the floor operation.

   rem performs the operation truncate on number and divisor and returns
the remainder of the truncate operation.

   mod and rem are the modulus and remainder functions when number and
divisor are integers.

Examples::
..........

      (rem -1 5) =>  -1
      (mod -1 5) =>  4
      (mod 13 4) =>  1
      (rem 13 4) =>  1
      (mod -13 4) =>  3
      (rem -13 4) =>  -1
      (mod 13 -4) =>  -3
      (rem 13 -4) =>  1
      (mod -13 -4) =>  -1
      (rem -13 -4) =>  -1
      (mod 13.4 1) =>  0.4
      (rem 13.4 1) =>  0.4
      (mod -13.4 1) =>  0.6
      (rem -13.4 1) =>  -0.4

See Also::
..........

*note floor:: , truncate

Notes::
.......

The result of mod is either zero or a

   real

   with the same sign as divisor.


File: gcl.info,  Node: signum,  Next: sqrt,  Prev: mod (Function),  Up: Numbers Dictionary

12.2.37 signum [Function]
-------------------------

'signum' number => signed-prototype

Arguments and Values::
......................

number--a number.

   signed-prototype--a number.

Description::
.............

signum determines a numerical value that indicates whether number is
negative, zero, or positive.

   For a rational, signum returns one of -1, 0, or 1 according to
whether number is negative, zero, or positive.  For a float, the result
is a float of the same format whose value is minus one, zero, or one.
For a complex number z, (signum z) is a complex number of the same phase
but with unit magnitude, unless z is a complex zero, in which case the
result is z.

   For rational arguments, signum is a rational function, but it may be
irrational for complex arguments.

   If number is a float, the result is a float.  If number is a
rational, the result is a rational.  If number is a complex float, the
result is a complex float.  If number is a complex rational, the result
is a complex, but it is implementation-dependent whether that result is
a complex rational or a complex float.

Examples::
..........

      (signum 0) =>  0
      (signum 99) =>  1
      (signum 4/5) =>  1
      (signum -99/100) =>  -1
      (signum 0.0) =>  0.0
      (signum #c(0 33)) =>  #C(0.0 1.0)
      (signum #c(7.5 10.0)) =>  #C(0.6 0.8)
      (signum #c(0.0 -14.7)) =>  #C(0.0 -1.0)
      (eql (signum -0.0) -0.0) =>  true

See Also::
..........

*note Rule of Float Substitutability::

Notes::
.......

      (signum x) == (if (zerop x) x (/ x (abs x)))


File: gcl.info,  Node: sqrt,  Next: random-state,  Prev: signum,  Up: Numbers Dictionary

12.2.38 sqrt, isqrt [Function]
------------------------------

'sqrt' number => root

   'isqrt' natural => natural-root

Arguments and Values::
......................

number, root--a number.

   natural, natural-root--a non-negative integer.

Description::
.............

sqrt and isqrt compute square roots.

   sqrt returns the principal square root of number.  If the number is
not a complex but is negative, then the result is a complex.

   isqrt returns the greatest integer less than or equal to the exact
positive square root of natural.

   If number is a positive rational, it is implementation-dependent
whether root is a rational or a float.  If number is a negative
rational, it is implementation-dependent whether root is a complex
rational or a complex float.

   The mathematical definition of complex square root (whether or not
minus zero is supported) follows:

   (sqrt x) = (exp (/ (log x) 2))

   The branch cut for square root lies along the negative real axis,
continuous with quadrant II. The range consists of the right half-plane,
including the non-negative imaginary axis and excluding the negative
imaginary axis.

Examples::
..........

      (sqrt 9.0) =>  3.0
      (sqrt -9.0) =>  #C(0.0 3.0)
      (isqrt 9) =>  3
      (sqrt 12) =>  3.4641016
      (isqrt 12) =>  3
      (isqrt 300) =>  17
      (isqrt 325) =>  18
      (sqrt 25)
     =>  5
     OR=> 5.0
      (isqrt 25) =>  5
      (sqrt -1) =>  #C(0.0 1.0)
      (sqrt #c(0 2)) =>  #C(1.0 1.0)

Exceptional Situations::
........................

The function sqrt should signal type-error if its argument is not a
number.

   The function isqrt should signal type-error if its argument is not a
non-negative integer.

   The functions sqrt and isqrt might signal arithmetic-error.

See Also::
..........

*note exp:: , *note log:: , *note Rule of Float Substitutability::

Notes::
.......

      (isqrt x) == (values (floor (sqrt x)))

   but it is potentially more efficient.


File: gcl.info,  Node: random-state,  Next: make-random-state,  Prev: sqrt,  Up: Numbers Dictionary

12.2.39 random-state [System Class]
-----------------------------------

Class Precedence List::
.......................

random-state, t

Description::
.............

A random state object contains state information used by the
pseudo-random number generator.  The nature of a random state object is
implementation-dependent.  It can be printed out and successfully read
back in by the same implementation, but might not function correctly as
a random state in another implementation.

   Implementations are required to provide a read syntax for objects of
type random-state, but the specific nature of that syntax is
implementation-dependent.

See Also::
..........

*note random-state:: , *note random:: , *note Printing Random States::


File: gcl.info,  Node: make-random-state,  Next: random,  Prev: random-state,  Up: Numbers Dictionary

12.2.40 make-random-state [Function]
------------------------------------

'make-random-state' &optional state => new-state

Arguments and Values::
......................

state--a random state, or nil, or t.  The default is nil.

   new-state--a random state object.

Description::
.............

Creates a fresh object of type random-state suitable for use as the
value of *random-state*.

   If state is a random state object, the new-state is a copy_5 of that
object.  If state is nil, the new-state is a copy_5 of the current
random state.  If state is t, the new-state is a fresh random state
object that has been randomly initialized by some means.

Examples::
..........

      (let* ((rs1 (make-random-state nil))
             (rs2 (make-random-state t))
             (rs3 (make-random-state rs2))
             (rs4 nil))
        (list (loop for i from 1 to 10
                    collect (random 100)
                    when (= i 5)
                     do (setq rs4 (make-random-state)))
              (loop for i from 1 to 10 collect (random 100 rs1))
              (loop for i from 1 to 10 collect (random 100 rs2))
              (loop for i from 1 to 10 collect (random 100 rs3))
              (loop for i from 1 to 10 collect (random 100 rs4))))
     =>  ((29 25 72 57 55 68 24 35 54 65)
         (29 25 72 57 55 68 24 35 54 65)
         (93 85 53 99 58 62 2 23 23 59)
         (93 85 53 99 58 62 2 23 23 59)
         (68 24 35 54 65 54 55 50 59 49))

Exceptional Situations::
........................

Should signal an error of type type-error if state is not a random
state, or nil, or t.

See Also::
..........

*note random:: , *note random-state::

Notes::
.......

One important use of make-random-state is to allow the same series of
pseudo-random numbers to be generated many times within a single
program.


File: gcl.info,  Node: random,  Next: random-state-p,  Prev: make-random-state,  Up: Numbers Dictionary

12.2.41 random [Function]
-------------------------

'random' limit &optional random-state => random-number

Arguments and Values::
......................

limit--a positive integer, or a positive float.

   random-state--a random state.  The default is the current random
state.

   random-number--a non-negative number less than limit and of the same
type as limit.

Description::
.............

Returns a pseudo-random number that is a non-negative number less than
limit and of the same type as limit.

   The random-state, which is modified by this function, encodes the
internal state maintained by the random number generator.

   An approximately uniform choice distribution is used.  If limit is an
integer, each of the possible results occurs with (approximate)
probability 1/limit.

Examples::
..........

      (<= 0 (random 1000) 1000) =>  true
      (let ((state1 (make-random-state))
            (state2 (make-random-state)))
        (= (random 1000 state1) (random 1000 state2))) =>  true

Side Effects::
..............

The random-state is modified.

Exceptional Situations::
........................

Should signal an error of type type-error if limit is not a positive
integer or a positive real.

See Also::
..........

*note make-random-state:: , *note random-state::

Notes::
.......

See Common Lisp: The Language for information about generating random
numbers.


File: gcl.info,  Node: random-state-p,  Next: *random-state*,  Prev: random,  Up: Numbers Dictionary

12.2.42 random-state-p [Function]
---------------------------------

'random-state-p' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type random-state; otherwise, returns
false.

Examples::
..........

      (random-state-p *random-state*) =>  true
      (random-state-p (make-random-state)) =>  true
      (random-state-p 'test-function) =>  false

See Also::
..........

*note make-random-state:: , *note random-state::

Notes::
.......

      (random-state-p object) == (typep object 'random-state)


File: gcl.info,  Node: *random-state*,  Next: numberp,  Prev: random-state-p,  Up: Numbers Dictionary

12.2.43 *random-state* [Variable]
---------------------------------

Value Type::
............

a random state.

Initial Value::
...............

implementation-dependent.

Description::
.............

The current random state, which is used, for example, by the function
random when a random state is not explicitly supplied.

Examples::
..........

      (random-state-p *random-state*) =>  true
      (setq snap-shot (make-random-state))
      ;; The series from any given point is random,
      ;; but if you backtrack to that point, you get the same series.
      (list (loop for i from 1 to 10 collect (random))
            (let ((*random-state* snap-shot))
              (loop for i from 1 to 10 collect (random)))
            (loop for i from 1 to 10 collect (random))
            (let ((*random-state* snap-shot))
              (loop for i from 1 to 10 collect (random))))
     =>  ((19 16 44 19 96 15 76 96 13 61)
         (19 16 44 19 96 15 76 96 13 61)
         (16 67 0 43 70 79 58 5 63 50)
         (16 67 0 43 70 79 58 5 63 50))

Affected By::
.............

The implementation.

   random.

See Also::
..........

*note make-random-state:: , *note random:: , random-state

Notes::
.......

Binding *random-state* to a different random state object correctly
saves and restores the old random state object.


File: gcl.info,  Node: numberp,  Next: cis,  Prev: *random-state*,  Up: Numbers Dictionary

12.2.44 numberp [Function]
--------------------------

'numberp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type number; otherwise, returns false.

Examples::
..........

      (numberp 12) =>  true
      (numberp (expt 2 130)) =>  true
      (numberp #c(5/3 7.2)) =>  true
      (numberp nil) =>  false
      (numberp (cons 1 2)) =>  false

Notes::
.......

      (numberp object) == (typep object 'number)


File: gcl.info,  Node: cis,  Next: complex,  Prev: numberp,  Up: Numbers Dictionary

12.2.45 cis [Function]
----------------------

'cis' radians => number

Arguments and Values::
......................

radians--a real.

   number--a complex.

Description::
.............

cis returns the value of~e^i\cdot radians, which is a complex in which
the real part is equal to the cosine of radians, and the imaginary part
is equal to the sine of radians.

Examples::
..........

      (cis 0) =>  #C(1.0 0.0)

See Also::
..........

*note Rule of Float Substitutability::


File: gcl.info,  Node: complex,  Next: complexp,  Prev: cis,  Up: Numbers Dictionary

12.2.46 complex [Function]
--------------------------

'complex' realpart &optional imagpart => complex

Arguments and Values::
......................

realpart--a real.

   imagpart--a real.

   complex--a rational or a complex.

Description::
.............

complex returns a number whose real part is realpart and whose imaginary
part is imagpart.

   If realpart is a rational and imagpart is the rational number zero,
the result of complex is realpart, a rational.  Otherwise, the result is
a complex.

   If either realpart or imagpart is a float, the non-float is converted
to a float before the complex is created.  If imagpart is not supplied,
the imaginary part is a zero of the same type as realpart; i.e., (coerce
0 (type-of realpart)) is effectively used.

   Type upgrading implies a movement upwards in the type hierarchy
lattice.  In the case of complexes, the type-specifier

   [Reviewer Note by Barmar: What type specifier?]  must be a subtype of
(upgraded-complex-part-type type-specifier).  If type-specifier1 is a
subtype of type-specifier2, then (upgraded-complex-element-type
'type-specifier1) must also be a subtype of
(upgraded-complex-element-type 'type-specifier2).  Two disjoint types
can be upgraded into the same thing.

Examples::
..........

      (complex 0) =>  0
      (complex 0.0) =>  #C(0.0 0.0)
      (complex 1 1/2) =>  #C(1 1/2)
      (complex 1 .99) =>  #C(1.0 0.99)
      (complex 3/2 0.0) =>  #C(1.5 0.0)

See Also::
..........

*note realpart:: , imagpart

Notes::
.......

      #c(a b) == #.(complex a b)


File: gcl.info,  Node: complexp,  Next: conjugate,  Prev: complex,  Up: Numbers Dictionary

12.2.47 complexp [Function]
---------------------------

'complexp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type complex; otherwise, returns false.

Examples::
..........

      (complexp 1.2d2) =>  false
      (complexp #c(5/3 7.2)) =>  true


See Also::
..........

*note complex:: (function and type), *note typep::

Notes::
.......

      (complexp object) == (typep object 'complex)


File: gcl.info,  Node: conjugate,  Next: phase,  Prev: complexp,  Up: Numbers Dictionary

12.2.48 conjugate [Function]
----------------------------

'conjugate' number => conjugate

Arguments and Values::
......................

number--a number.

   conjugate--a number.

Description::
.............

Returns the complex conjugate of number.  The conjugate of a

   real

   number is itself.

Examples::
..........

      (conjugate #c(0 -1)) =>  #C(0 1)
      (conjugate #c(1 1)) =>  #C(1 -1)
      (conjugate 1.5) =>  1.5
      (conjugate #C(3/5 4/5)) =>  #C(3/5 -4/5)
      (conjugate #C(0.0D0 -1.0D0)) =>  #C(0.0D0 1.0D0)
      (conjugate 3.7) =>  3.7

Notes::
.......

For a complex number z,

      (conjugate z) == (complex (realpart z) (- (imagpart z)))


File: gcl.info,  Node: phase,  Next: realpart,  Prev: conjugate,  Up: Numbers Dictionary

12.2.49 phase [Function]
------------------------

'phase' number => phase

Arguments and Values::
......................

number--a number.

   phase--a number.

Description::
.............

phase returns the phase of number (the angle part of its polar
representation) in radians, in the range

   -\pi (exclusive) if minus zero is not supported, or -\pi (inclusive)
if minus zero is supported,

   to \pi (inclusive).  The phase of a positive

   real

   number is zero; that of a negative

   real

   number is \pi.  The phase of zero is defined to be zero.

   If number is a complex float, the result is a float of the same type
as the components of number.  If number is a float, the result is a
float of the same type.  If number is a rational or a complex rational,
the result is a single float.

   The branch cut for phase lies along the negative real axis,
continuous with quadrant II. The range consists of that portion of the
real axis between -\pi (exclusive) and~\pi (inclusive).

   The mathematical definition of phase is as follows:

   (phase x) = (atan (imagpart x) (realpart x))

Examples::
..........

      (phase 1) =>  0.0s0
      (phase 0) =>  0.0s0
      (phase (cis 30)) =>  -1.4159266
      (phase #c(0 1)) =>  1.5707964

Exceptional Situations::
........................

Should signal type-error if its argument is not a number.  Might signal
arithmetic-error.

See Also::
..........

*note Rule of Float Substitutability::


File: gcl.info,  Node: realpart,  Next: upgraded-complex-part-type,  Prev: phase,  Up: Numbers Dictionary

12.2.50 realpart, imagpart [Function]
-------------------------------------

'realpart' number => real

   'imagpart' number => real

Arguments and Values::
......................

number--a number.

   real--a real.

Description::
.............

realpart and imagpart return the real and imaginary parts of number
respectively.  If number is

   real,

   then realpart returns number and imagpart returns (* 0 number), which
has the effect that the imaginary part of a rational is 0 and that of a
float is a floating-point zero of the same format.

Examples::
..........

      (realpart #c(23 41)) =>  23
      (imagpart #c(23 41.0)) =>  41.0
      (realpart #c(23 41.0)) =>  23.0
      (imagpart 23.0) =>  0.0

Exceptional Situations::
........................

Should signal an error of type type-error if number is not a number.

See Also::
..........

*note complex::


File: gcl.info,  Node: upgraded-complex-part-type,  Next: realp,  Prev: realpart,  Up: Numbers Dictionary

12.2.51 upgraded-complex-part-type [Function]
---------------------------------------------

'upgraded-complex-part-type' typespec &optional environment =>
upgraded-typespec

Arguments and Values::
......................

typespec--a type specifier.

   environment--an environment object.  The default is nil, denoting the
null lexical environment and the and current global environment.

   upgraded-typespec--a type specifier.

Description::
.............

upgraded-complex-part-type returns the part type of the most specialized
complex number representation that can hold parts of type typespec.

   The typespec is a subtype of (and possibly type equivalent to) the
upgraded-typespec.

   The purpose of upgraded-complex-part-type is to reveal how an
implementation does its upgrading.

See Also::
..........

*note complex:: (function and type)

Notes::
.......


File: gcl.info,  Node: realp,  Next: numerator,  Prev: upgraded-complex-part-type,  Up: Numbers Dictionary

12.2.52 realp [Function]
------------------------

'realp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type real; otherwise, returns false.

Examples::
..........

      (realp 12) =>  true
      (realp #c(5/3 7.2)) =>  false
      (realp nil) =>  false
      (realp (cons 1 2)) =>  false

Notes::
.......

      (realp object) == (typep object 'real)


File: gcl.info,  Node: numerator,  Next: rational (Function),  Prev: realp,  Up: Numbers Dictionary

12.2.53 numerator, denominator [Function]
-----------------------------------------

'numerator' rational => numerator

   'denominator' rational => denominator

Arguments and Values::
......................

rational--a rational.

   numerator--an integer.

   denominator--a positive integer.

Description::
.............

numerator and denominator reduce rational to canonical form and compute
the numerator or denominator of that number.

   numerator and denominator return the numerator or denominator of the
canonical form of rational.

   If rational is an integer, numerator returns rational and denominator
returns 1.

Examples::
..........

      (numerator 1/2) =>  1
      (denominator 12/36) =>  3
      (numerator -1) =>  -1
      (denominator (/ -33)) =>  33
      (numerator (/ 8 -6)) =>  -4
      (denominator (/ 8 -6)) =>  3

See Also::
..........

*note /::

Notes::
.......

      (gcd (numerator x) (denominator x)) =>  1


File: gcl.info,  Node: rational (Function),  Next: rationalp,  Prev: numerator,  Up: Numbers Dictionary

12.2.54 rational, rationalize [Function]
----------------------------------------

'rational' number => rational

   'rationalize' number => rational

Arguments and Values::
......................

number--a real.

   rational--a rational.

Description::
.............

rational and rationalize convert

   reals

   to rationals.

   If number is already rational, it is returned.

   If number is a float, rational returns a rational that is
mathematically equal in value to the float.  rationalize returns a
rational that approximates the float to the accuracy of the underlying
floating-point representation.

   rational assumes that the float is completely accurate.

   rationalize assumes that the float is accurate only to the precision
of the floating-point representation.

Examples::
..........

      (rational 0) =>  0
      (rationalize -11/100) =>  -11/100
      (rational .1) =>  13421773/134217728 ;implementation-dependent
      (rationalize .1) =>  1/10

Affected By::
.............

The implementation.

Exceptional Situations::
........................

Should signal an error of type type-error if number is not a real.
Might signal arithmetic-error.

Notes::
.......

It is always the case that

      (float (rational x) x) == x

   and

      (float (rationalize x) x) == x

   That is, rationalizing a float by either method and then converting
it back to a float of the same format produces the original number.


File: gcl.info,  Node: rationalp,  Next: ash,  Prev: rational (Function),  Up: Numbers Dictionary

12.2.55 rationalp [Function]
----------------------------

'rationalp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type rational; otherwise, returns false.

Examples::
..........

      (rationalp 12) =>  true
      (rationalp 6/5) =>  true
      (rationalp 1.212) =>  false

See Also::
..........

*note rational (Function)::

Notes::
.......

      (rationalp object) == (typep object 'rational)


File: gcl.info,  Node: ash,  Next: integer-length,  Prev: rationalp,  Up: Numbers Dictionary

12.2.56 ash [Function]
----------------------

'ash' integer count => shifted-integer

Arguments and Values::
......................

integer--an integer.

   count--an integer.

   shifted-integer--an integer.

Description::
.............

ash performs the arithmetic shift operation on the binary representation
of integer, which is treated as if it were binary.

   ash shifts integer arithmetically left by count bit positions if
count is positive, or right count bit positions if count is negative.
The shifted value of the same sign as integer is returned.

   Mathematically speaking, ash performs the computation
floor(integer\cdot 2^count).  Logically, ash moves all of the bits in
integer to the left, adding zero-bits at the right, or moves them to the
right, discarding bits.

   ash is defined to behave as if integer were represented in two's
complement form, regardless of how integers are represented internally.

Examples::
..........

      (ash 16 1) =>  32
      (ash 16 0) =>  16
      (ash 16 -1) =>  8
      (ash -100000000000000000000000000000000 -100) =>  -79

Exceptional Situations::
........................

Should signal an error of type type-error if integer is not an integer.
Should signal an error of type type-error if count is not an integer.
Might signal arithmetic-error.

Notes::
.......

      (logbitp j (ash n k))
      == (and (>= j k) (logbitp (- j k) n))


File: gcl.info,  Node: integer-length,  Next: integerp,  Prev: ash,  Up: Numbers Dictionary

12.2.57 integer-length [Function]
---------------------------------

'integer-length' integer => number-of-bits

Arguments and Values::
......................

integer--an integer.

   number-of-bits--a non-negative integer.

Description::
.............

Returns the number of bits needed to represent integer in binary
two's-complement format.

Examples::
..........

      (integer-length 0) =>  0
      (integer-length 1) =>  1
      (integer-length 3) =>  2
      (integer-length 4) =>  3
      (integer-length 7) =>  3
      (integer-length -1) =>  0
      (integer-length -4) =>  2
      (integer-length -7) =>  3
      (integer-length -8) =>  3
      (integer-length (expt 2 9)) =>  10
      (integer-length (1- (expt 2 9))) =>  9
      (integer-length (- (expt 2 9))) =>  9
      (integer-length (- (1+ (expt 2 9)))) =>  10

Exceptional Situations::
........................

Should signal an error of type type-error if integer is not an integer.

Notes::
.......

This function could have been defined by:

     (defun integer-length (integer)
       (ceiling (log (if (minusp integer)
                         (- integer)
                         (1+ integer))
                     2)))

   If integer is non-negative, then its value can be represented in
unsigned binary form in a field whose width in bits is no smaller than
(integer-length integer).  Regardless of the sign of integer, its value
can be represented in signed binary two's-complement form in a field
whose width in bits is no smaller than (+ (integer-length integer) 1).


File: gcl.info,  Node: integerp,  Next: parse-integer,  Prev: integer-length,  Up: Numbers Dictionary

12.2.58 integerp [Function]
---------------------------

'integerp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type integer; otherwise, returns false.

Examples::
..........

      (integerp 1) =>  true
      (integerp (expt 2 130)) =>  true
      (integerp 6/5) =>  false
      (integerp nil) =>  false


Notes::
.......

      (integerp object) == (typep object 'integer)


File: gcl.info,  Node: parse-integer,  Next: boole,  Prev: integerp,  Up: Numbers Dictionary

12.2.59 parse-integer [Function]
--------------------------------

'parse-integer' string &key start end radix junk-allowed => integer, pos

Arguments and Values::
......................

string--a string.

   start, end--bounding index designators of string.  The defaults for
start and end are 0 and nil, respectively.

   radix--a radix.  The default is 10.

   junk-allowed--a generalized boolean.  The default is false.

   integer--an integer or false.

   pos--a bounding index of string.

Description::
.............

parse-integer parses an integer in the specified radix from the
substring of string delimited by start and end.

   parse-integer expects an optional sign (+ or -) followed by a a
non-empty sequence of digits to be interpreted in the specified radix.
Optional leading and trailing whitespace_1 is ignored.

   parse-integer does not recognize the syntactic radix-specifier
prefixes #O, #B, #X, and #nR, nor does it recognize a trailing decimal
point.

   If junk-allowed is false, an error of type parse-error is signaled if
substring does not consist entirely of the representation of a signed
integer, possibly surrounded on either side by whitespace_1 characters.

   The first value returned is either the integer that was parsed, or
else nil if no syntactically correct integer was seen but junk-allowed
was true.

   The second value is either the index into the string of the delimiter
that terminated the parse, or the upper bounding index of the substring
if the parse terminated at the end of the substring (as is always the
case if junk-allowed is false).

Examples::
..........

      (parse-integer "123") =>  123, 3
      (parse-integer "123" :start 1 :radix 5) =>  13, 3
      (parse-integer "no-integer" :junk-allowed t) =>  NIL, 0

Exceptional Situations::
........................

If junk-allowed is false, an error is signaled if substring does not
consist entirely of the representation of an integer, possibly
surrounded on either side by whitespace_1 characters.


File: gcl.info,  Node: boole,  Next: boole-1,  Prev: parse-integer,  Up: Numbers Dictionary

12.2.60 boole [Function]
------------------------

'boole' op integer-1 integer-2 => result-integer

Arguments and Values::
......................

Op--a bit-wise logical operation specifier.

   integer-1--an integer.

   integer-2--an integer.

   result-integer--an integer.

Description::
.............

boole performs bit-wise logical operations on integer-1 and integer-2,
which are treated as if they were binary and in two's complement
representation.

   The operation to be performed and the return value are determined by
op.

   boole returns the values specified for any op in Figure 12-16.

  Op           Result                                      
  boole-1      integer-1                                   
  boole-2      integer-2                                   
  boole-andc1  and complement of integer-1 with integer-2  
  boole-andc2  and integer-1 with complement of integer-2  
  boole-and    and                                         
  boole-c1     complement of integer-1                     
  boole-c2     complement of integer-2                     
  boole-clr    always 0 (all zero bits)                    
  boole-eqv    equivalence (exclusive nor)                 
  boole-ior    inclusive or                                
  boole-nand   not-and                                     
  boole-nor    not-or                                      
  boole-orc1   or complement of integer-1 with integer-2   
  boole-orc2   or integer-1 with complement of integer-2   
  boole-set    always -1 (all one bits)                    
  boole-xor    exclusive or                                

         Figure 12-16: Bit-Wise Logical Operations        


Examples::
..........

      (boole boole-ior 1 16) =>  17
      (boole boole-and -2 5) =>  4
      (boole boole-eqv 17 15) =>  -31

     ;;; These examples illustrate the result of applying BOOLE and each
     ;;; of the possible values of OP to each possible combination of bits.
      (progn
        (format t "~&Results of (BOOLE <op> #b0011 #b0101) ...~
                ~
        (dolist (symbol '(boole-1     boole-2    boole-and  boole-andc1
                          boole-andc2 boole-c1   boole-c2   boole-clr
                          boole-eqv   boole-ior  boole-nand boole-nor
                          boole-orc1  boole-orc2 boole-set  boole-xor))
          (let ((result (boole (symbol-value symbol) #b0011 #b0101)))
            (format t "~& ~A~13T~3,' D~23T~:*~5,' B~31T ...~4,'0B~
                    symbol result (logand result #b1111)))))
      |>  Results of (BOOLE <op> #b0011 #b0101) ...
      |>  ---Op-------Decimal-----Binary----Bits---
      |>   BOOLE-1       3          11    ...0011
      |>   BOOLE-2       5         101    ...0101
      |>   BOOLE-AND     1           1    ...0001
      |>   BOOLE-ANDC1   4         100    ...0100
      |>   BOOLE-ANDC2   2          10    ...0010
      |>   BOOLE-C1     -4        -100    ...1100
      |>   BOOLE-C2     -6        -110    ...1010
      |>   BOOLE-CLR     0           0    ...0000
      |>   BOOLE-EQV    -7        -111    ...1001
      |>   BOOLE-IOR     7         111    ...0111
      |>   BOOLE-NAND   -2         -10    ...1110
      |>   BOOLE-NOR    -8       -1000    ...1000
      |>   BOOLE-ORC1   -3         -11    ...1101
      |>   BOOLE-ORC2   -5        -101    ...1011
      |>   BOOLE-SET    -1          -1    ...1111
      |>   BOOLE-XOR     6         110    ...0110
     =>  NIL

Exceptional Situations::
........................

Should signal type-error if its first argument is not a bit-wise logical
operation specifier or if any subsequent argument is not an integer.

See Also::
..........

*note logand::

Notes::
.......

In general,

      (boole boole-and x y) == (logand x y)

   Programmers who would prefer to use numeric indices rather than
bit-wise logical operation specifiers can get an equivalent effect by a
technique such as the following:

     ;; The order of the values in this `table' are such that
     ;; (logand (boole (elt boole-n-vector n) #b0101 #b0011) #b1111) => n
      (defconstant boole-n-vector
         (vector boole-clr   boole-and  boole-andc1 boole-2
                 boole-andc2 boole-1    boole-xor   boole-ior
                 boole-nor   boole-eqv  boole-c1    boole-orc1
                 boole-c2    boole-orc2 boole-nand  boole-set))
     =>  BOOLE-N-VECTOR
      (proclaim '(inline boole-n))
     =>  implementation-dependent
      (defun boole-n (n integer &rest more-integers)
        (apply #'boole (elt boole-n-vector n) integer more-integers))
     =>  BOOLE-N
      (boole-n #b0111 5 3) =>  7
      (boole-n #b0001 5 3) =>  1
      (boole-n #b1101 5 3) =>  -3
      (loop for n from #b0000 to #b1111 collect (boole-n n 5 3))
     =>  (0 1 2 3 4 5 6 7 -8 -7 -6 -5 -4 -3 -2 -1)

