Skip to main content

copy-symbol

copy-symbol Function

Syntax:

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 copy2 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:

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.

Expanded Reference: copy-symbol​

Basic copy without properties​

By default (or with nil as the second argument), copy-symbol creates an uninterned symbol with the same name but no value, function definition, or property list.

(let* ((original 'my-sym)
       (copy (copy-symbol original)))
  (values (symbol-name copy)
          (symbol-package copy)
          (eq original copy)))
=> "MY-SYM"
=> NIL
=> NIL

Copy without properties leaves symbol unbound​

(setf (symbol-value 'source) 42)
(let ((copy (copy-symbol 'source nil)))
  (values (boundp 'source)
          (boundp copy)))
=> T
=> NIL

Copy with properties​

When the second argument is true, the new symbol gets a copy of the original's value, function definition, and property list.

(setf (symbol-value 'original) 100)
(setf (get 'original 'color) 'red)

(let ((copy (copy-symbol 'original t)))
  (values (symbol-value copy)
          (get copy 'color)
          (eq copy 'original)))
=> 100
=> RED
=> NIL

Property lists are independent copies​

Modifying the copy's property list does not affect the original.

(setf (get 'proto 'x) 1)
(setf (get 'proto 'y) 2)

(let ((clone (copy-symbol 'proto t)))
  (setf (get clone 'x) 999)
  (values (get 'proto 'x)
          (get clone 'x)))
=> 1
=> 999

The copy is always uninterned​

Regardless of whether the original is interned, the copy is always a fresh, uninterned symbol.

(let ((copy (copy-symbol :some-keyword t)))
  (values (symbol-name copy)
          (symbol-package copy)
          (keywordp copy)))
=> "SOME-KEYWORD"
=> NIL
=> NIL

Each copy is a distinct object​

Multiple copies of the same symbol are distinct from each other.

(let ((a (copy-symbol 'foo))
      (b (copy-symbol 'foo)))
  (values (string= (symbol-name a) (symbol-name b))
          (eq a b)))
=> T
=> NIL