defconstant

defconstant Macro

Syntax:

defconstant name initial-value [documentation] → name

Arguments and Values:

name—a symbol; not evaluated.

initial-value—a form; evaluated.

documentation—a string; not evaluated.

Description:

defconstant causes the global variable named by name to be given a value that is the result of evaluating initial-value.

A constant defined by defconstant can be redefined with defconstant. However, the consequences are undefined if an attempt is made to assign a value to the symbol using another operator, or to assign it to a different value using a subsequent defconstant.

If documentation is supplied, it is attached to name as a documentation string of kind variable.

defconstant normally appears as a top level form, but it is meaningful for it to appear as a non-top-level form. However, the compile-time side effects described below only take place when defconstant appears as a top level form.

The consequences are undefined if there are any bindings of the variable named by name at the time defconstant is executed or if the value is not eql to the value of initial-value.

The consequences are undefined when constant symbols are rebound as either lexical or dynamic variables. In other words, a reference to a symbol declared with defconstant always refers to its global value.

The side effects of the execution of defconstant must be equivalent to at least the side effects of the execution of the following code:

(setf (symbol-value ’name) initial-value)

(setf (documentation ’name ’variable) ’documentation)

If a defconstant form appears as a top level form, the compiler must recognize that name names a constant variable. An implementation may choose to evaluate the value-form at compile time, load time, or both. Therefore, users must ensure that the initial-value can be evaluated at compile time (regardless of whether or not references to name appear in the file) and that it always evaluates to the same value.

Data and Control

Examples:

(defconstant this-is-a-constant ’never-changing "for a test") → THIS-IS-A-CONSTANT this-is-a-constant → NEVER-CHANGING 
(documentation ’this-is-a-constant ’variable) → "for a test" 
(constantp ’this-is-a-constant) → true 

See Also:

declaim, defparameter, defvar, documentation, proclaim, Section 3.1.2.1.1.3 (Constant Variables), Section 3.2 (Compilation)

Expanded Reference: defconstant

Defining a constant

defconstant defines a named constant whose value cannot be changed by assignment or binding.

(defconstant +golden-ratio+ (/ (1+ (sqrt 5.0d0)) 2))
=> +GOLDEN-RATIO+

+golden-ratio+
=> 1.618033988749895d0

Constants are recognized by constantp

You can check whether a symbol names a constant variable with constantp.

(defconstant +max-size+ 1024)
=> +MAX-SIZE+

(constantp '+max-size+)
=> T

Using a documentation string

A documentation string can be attached to the constant.

(defconstant +avogadro+ 6.022d23
  "Avogadro's number: the number of particles per mole.")
=> +AVOGADRO+

(documentation '+avogadro+ 'variable)
=> "Avogadro's number: the number of particles per mole."

Constants in expressions

Constants can be used anywhere a value is expected and are particularly useful for configuration values that should never change at runtime.

(defconstant +days-per-week+ 7)
=> +DAYS-PER-WEEK+

(defun weeks-to-days (weeks)
  (* weeks +days-per-week+))
=> WEEKS-TO-DAYS

(weeks-to-days 4)
=> 28

Built-in constants

Common Lisp provides several built-in constants defined as if by defconstant.

pi
=> 3.141592653589793d0

most-positive-fixnum
=> 4611686018427387903

t
=> T

nil
=> NIL