sole-element

Purpose
Return the first element of a list containing, at most, one element.

Package   :gbbopen-tools

Module   :gbbopen-tools

Arguments and values

Returns
The sole element of list or nil.

Errors
List contains more than one element.

Description
If list is a cons, sole-element returns the car of that cons. If list is nil, sole-element returns nil. If list is a cons and the cdr of that cons is not nil, a continuable error is signaled. If you continue from the error, the first element is returned.

This function is preferable to car when you expect a list of, at most, one element. For example, this function is often used on the results of calling find-instances or filter-instances when only a single unit instance is expected in the result list.

Examples

  > (sole-element '(a))
  a
  > (sole-element nil)
  nil
  > (sole-element '(a b))
  Error: The list (a b) contains more than 1 element.
         If continued - Ignore the remaining elements.
  >>

Note
This function is compiled in-line for top performance.

sole-element