I’ve seen this idiom a few times when working with a binary stream:

(let ((elements-read (read-sequence buffer stream)))
  ...)

While the return value is the number of elements read in that situation, it’s a useful coincidence in a common case. The actual return value of read-sequence is:

the index of the first element of sequence that was not updated

Therefore, treating the return value as the number of elements read is completely wrong if you use the start option to read-sequence.

For example, if stream has one or more elements available to read:

(read-sequence buffer stream :start 42 :end 43)
=> 43

The actual number of elements read is 1, not 43.

Sometimes I want to create a directory pathname relative to some existing file pathname. For example, when I want to refer to files that are in the same directory as the currently loading file, I might work relative to *load-truename*.

I used to do it like this:

(make-pathname :directory (pathname-directory *load-truename*))

This worked fine for me, but after getting bug reports from Windows users, I’ve changed it to this:

(make-pathname :defaults *load-truename*
               :type nil
               :name nil
               :version nil)

That way all the properties of *load-truename* are carried over, except the name and type.

edit Added :version nil per Fare’s comment.

Imagine your project has a special variable whose value is a stream to which some output is directed, e.g. my-project:*log-output*. You can change where the output goes by setting the value of the special variable, but by default, output should go to *standard-output*.

The naive way to do this is a direct reference:

(defvar *log-output* *standard-output*)

However, this can run into trouble if *standard-output* is bound to something unexpected when that form is evaluated. For example, if file loading output is temporarily suppressed by binding *standard-output* to (make-broadcast-stream), output to *log-output* is then also discarded.

One way to work around it is with make-synonym-stream:

(defvar *log-output* (make-synonym-stream '*standard-output*))

With that setup, any output sent to *log-output* is sent to the stream that is the dynamic value of the symbol '*standard-output*. And since the dynamic value is looked up for each output, the output to *log-output* will go to *standard-output* even if *standard-output* is assigned some other stream value later on.

Occasionally it is convenient for a handler to decide whether to deal with a condition after it already has control.

Sometimes I see that idiom written with a `handler-case` that resignals the condition if it decides it can’t take care of it. The downside of that approach is that `handler-case` only resignals the condition after unwinding the stack and removing any restarts that were in place.

`handler-bind` avoids those downsides. When a `handler-bind` handler does not transfer control it is said to “decline to handle” the condition. The condition will then percolate up to surrounding handlers or the debugger with the stack and restarts still in tact, as if the handler had never been entered.

(defun baz ()
  (handler-bind ((error (lambda (c)
                          (when (i-got-this-p c)
                            (return-from baz (quux))))))
    (foo)))

Here’s a quick way to add an item to a sorted list:

(merge 'list (list item) sorted-list test)

Via Bernhard Pfahringer on comp.lang.lisp, 1998.

Among the 4 Lisp’s equality operators equalp may be the least used, but it has some really cool features:

• it matches strings ignoring case (this is well-known, I suppose)
• it also matches structs
• it also matches vectors and arrays
• and it matches hash-tables

The last 3 are really useful, because unlike strings and other primitive types, there’s no specialized equality predicates for built-in structural types, so equalp fills this role.

(contributed by @vseloved)

format has four directives for formatting integers with different radixes:

• ~B formats as binary: (format nil "~B" 42) => "101010"
• ~O formats as octal: (format nil "~O" 42) => "52"
• ~X formats as hexadecimal: (format nil "~X" 666) => "29A"
• ~R formats with an arbitrary radix between 2 and 36: (format nil "~36R" 18321) => "E4X"

Each directive takes padding and pad-character options (as well as other options). I define these functions in my init files to quickly dump out hex and bit views of integers:

(defun :hex (value &optional (size 4))
  (format t "~v,'0X" size value))

(defun :bits (value &optional (size 8))
  (format t "~v,'0B" size value))
  
* (:bits 42)
00101010

* (:hex 666)
029A

The lower-level write function accepts a :base argument that specifies a radix to use when printing integers. The default value is taken from *print-base*. For example, (write-to-string 65535 :base 16) => "FFFF". Since write underlies how other standard functions produce output, binding *print-base* will affect pretty much everything.

Novices sometimes ask how to get a convert an integer to a list of bits, often for the purpose of iterating over the bits somehow. Common Lisp has a rich set of functions for directly accessing the bits of an integer, so constructing an intermediate list of bits is rarely necessary.

Here are a few examples of accessing the bits of an integer.

With integer-length and logbitp to test the bit at a particular index:

(defun list-of-bits (integer)
  (loop for index below (integer-length integer)
        collect (if (logbitp index integer) 1 0)))

With ash to shift the integer to the right and logand to test the least-significant bit:

(defun list-of-bits (integer)
  (loop repeat (integer-length integer)
        for i = integer then (ash i -1)
        collect (logand i 1)))

With ash to shift a one-bit mask to the left and logtest to test the mask bit against the integer:

(defun list-of-bits (integer)
  (loop repeat (integer-length integer)
        for mask = 1 then (ash mask 1)
        collect (if (logtest mask integer) 1 0)))

With byte to construct a byte specifier and ldb to extract a field from the integer:

(defun list-of-bits (integer)
  (loop for position below (integer-length integer)
        collect (ldb (byte 1 position) integer)))

update Unfortunately, all these examples are buggy - they collect bits in the wrong order. I used loop/collect to avoid having to reverse the results, but didn’t think it through properly. Here are some updated definitions with dotimes that give the results in the intended order:

(defun list-of-bits (integer)
  (let ((bits '()))
    (dotimes (index (integer-length integer) bits)
      (push (if (logbitp index integer) 1 0) bits))))

(defun list-of-bits (integer)
  (let ((i integer)
        (bits '()))
    (dotimes (j (integer-length integer) bits)
      (push (logand i 1) bits)
      (setf i (ash i -1)))))

(defun list-of-bits (integer)
  (let ((mask 1)
        (bits '()))
    (dotimes (i (integer-length integer) bits)
      (push (if (logtest mask integer) 1 0) bits)
      (setf mask (ash mask 1)))))

(defun list-of-bits (integer)
  (let ((bits '()))
    (dotimes (position (integer-length integer) bits)
      (push (ldb (byte 1 position) integer) bits))))

deftype can be used to create user-defined types that expand into built-in types. For example:

(deftype octet-vector (length)
  `(simple-array (unsigned-byte 8) (,length)))

Given this deftype, in a type context, (octet-vector 32) expands into (simple-array (unsigned-byte 8) (32)), or a one-dimensional octet array of length 32.

Lambda lists for deftype are very similar to lambda lists for defmacro, with an important difference: where optional arguments to defmacro with no initialization form default to nil, the default value in deftype is the symbol *. The deftype above could be rewritten to take advantage of this:

(deftype octet-vector (&optional length)
  `(simple-array (unsigned-byte 8) (,length)))

Now, in a type context, a plain octet-vector expands into (simple-array (unsigned-byte 8) (*)), or a one-dimensional octet array of indeterminate length, and (octet-vector 32) expands into (simple-array (unsigned-byte 8) (32)).

For more information, see section 3.4.8, Deftype Lambda Lists.