Skip to main content

incf, decf

incf, decf Macro

Syntax:

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 Section 5.1.1.1 (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:

+, -, 1+, 1-, setf

Expanded Reference: incf, decf​

Basic increment and decrement​

incf adds a delta (default 1) to a place and stores the result back. decf subtracts.

(let ((n 0))
  (incf n)
  n)
=> 1

(let ((n 10))
  (decf n)
  n)
=> 9

Specifying a delta​

Both incf and decf accept an optional delta form that specifies the amount to add or subtract.

(let ((n 0))
  (incf n 10)
  n)
=> 10

(let ((n 100))
  (decf n 30)
  n)
=> 70

Return value​

incf and decf return the new value of the place.

(let ((n 5))
  (incf n 3))
=> 8

(let ((n 5))
  (decf n 3))
=> 2

Working with different numeric types​

Type conversions happen automatically. The delta can be any number type.

(let ((n 0))
  (incf n 0.5)
  n)
=> 0.5

(let ((n 10))
  (decf n 1/3)
  n)
=> 29/3

Incrementing elements of sequences​

incf and decf work with any valid place, including array elements and structure slots.

(let ((arr (vector 10 20 30)))
  (incf (aref arr 1) 5)
  arr)
=> #(10 25 30)

(let ((lst (list 1 2 3)))
  (decf (second lst) 10)
  lst)
=> (1 -8 3)

Decrementing with a negative delta​

Using a negative delta with decf effectively adds to the value.

(let ((n 0))
  (decf n -5)
  n)
=> 5