Writing a destructive macro or function like incf?

Question

I need an `incf` function which does some bounds checking during the increment: ``` val := val + delta if val >= 1.0 then return 1.0 else return val ``` I can write this using `incf`: ``` (defun incf-bounded(val delta) (incf val delta) (if (>= val 1.0) 1.0 val)) ``` In such case I need to use this like `(setf x (incf-bounded x delta))`. But how do I write one which I can use like `(incf-bounded x delta)`, i.e., where `x` will be modified?

Accepted Answer

This is a good use case for `define-modify-macro` (which has also been described in what is to append as push is to cons, in Lisp?, but the present case is simpler). First, write your bounded sum as a function. This is pretty straightforward; it takes `val` and `delta` and returns `1.0` if their sum is greater than `1.0`, and their sum otherwise. Based on the pseudo code and Lisp code you posted, this could be:

```
(defun sum-bounded (val delta)
  (if (>= (+ val delta) 1.0)
      1.0
      (+ val delta)))
```

Actually, for just computing this value, you can use:

```
(defun sum-bounded (val delta)
  (min 1.0 (+ val delta)))
```

Now you use `define-modify-macro` to define a macro `incf-bounded`:

```
(define-modify-macro incf-bounded (delta) sum-bounded)
```

The macro takes a place as its first argument and delta as a second. It safely retrieves the value from the place, computes `sum-bounded` with that value and delta, and then stores the result back into the place. “Safely” here means that it avoids possible problems with multiple evaluation, as Lars Brinkhoff's wisely warns against. Then you just use it:

```
(let ((x .5))
  (incf-bounded x .3)
  (print x)                             ; prints 0.8
  (incf-bounded x .3)
  (print x))                            ; prints 1.0 (not 1.1)
```

For more complicated cases where the place that would be modified isn't naturally the first argument to the macro that you want, you'd need to write your own macro and use `get-setf-expansion`, but this is explained in more detail in

- what is to append as push is to cons, in Lisp?

Code all together for easy copy & paste

```
(defun sum-bounded (val delta)
  "Returns the lesser of 1.0 or the sum of val and delta."
  (min 1.0 (+ val delta)))

(define-modify-macro incf-bounded (delta) sum-bounded
  "(incf-bounded place delta) computes the sum of the value of the
place and delta, and assigns the lesser of 1.0 and the sum of the value
and delta to place.")

(defun demo ()
  (let ((x .5))
    (incf-bounded x .3)
    (print x)                           ; prints 0.8
    (incf-bounded x .3)
    (print x)))                         ; prints 1.0 (not 1.1)
```

Writing a destructive macro or function like incf?

Solution

Problem

Related problems