remprop

remprop Function

Syntax:

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 ₂ of symbol a property₁ with a property indicator identical to indicator. If there are multiple properties₁ 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:

remf, 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.

Expanded Reference: remprop

Basic property removal

remprop removes a property from a symbol's property list and returns a generalized boolean indicating whether the property was found.

(let ((sym (make-symbol "DEMO")))
  (setf (get sym 'color) 'red)
  (setf (get sym 'size) 10)
  (let ((before (get sym 'color)))
    (remprop sym 'color)
    (values before (get sym 'color))))
=> RED
=> NIL

Removing a non-existent property

If the property does not exist, remprop returns nil (false) and makes no changes.

(let ((sym (make-symbol "TEST")))
  (setf (get sym 'a) 1)
  (values (remprop sym 'b)
          (symbol-plist sym)))
=> NIL
=> (A 1)

Removing properties one by one

remprop only removes the first matching property. Successive calls can be used to clean up a property list.

(let ((sym (make-symbol "CLEANUP")))
  (setf (get sym 'x) 1)
  (setf (get sym 'y) 2)
  (setf (get sym 'z) 3)
  (remprop sym 'y)
  (symbol-plist sym))
;; => (Z 3 X 1)  (order may vary, Y removed)

Distinguishing nil value from absent property

Setting a property to nil is different from removing it. remprop truly removes the entry.

(let ((sym (make-symbol "NIL-TEST")))
  (setf (get sym 'flag) nil)
  (values (get sym 'flag)
          (get sym 'flag :missing)
          (progn (remprop sym 'flag)
                 (get sym 'flag :missing))))
=> NIL
=> NIL
=> :MISSING

Practical cleanup of all properties

You can remove all properties from a symbol by iterating over its property list.

(let ((sym (make-symbol "FULL")))
  (setf (get sym 'a) 1)
  (setf (get sym 'b) 2)
  (setf (get sym 'c) 3)
  (loop for (key nil) on (symbol-plist sym) by #'cddr
        do (remprop sym key))
  (symbol-plist sym))
=> NIL