zl:1 - FTP

493 sort
For a table of related items: See the section "Predicates That Operate on
Sequences" in Symbolics Common Lisp: Language Concepts.
sort sequence predicate &key key Function
sort destructively modifies sequence by sorting it according to an order
determined by predicate. predicate should take two arguments and return a
non-nil value if and only if the first argument is strictly less than the
second (in some appropriate sense). If the first argument is greater than
or equal to the second (in the appropriate sense), then predicate should
return nil.
The sort function determines the relationship between two elements by
giving keys extracted from the elements to predicate. The :key argument,
when applied to an element, should return the key for that element. It
defaults to the identity function, thereby making the element itself the key.
sequence can be either a list or a vector (one-dimensional array). Note that
nil is considered to be a sequence, of length zero.
The :key function should not have any side effects. A useful example of a
:key function would be a component selector function for a defstruct structure,
used in sorting a sequence of structures.
If the :key and predicate functions always return, then the sorting operation
will always terminate, producing a sequence containing the same elements
as the original sequence (that is, the result is a permutation of
sequence). This is guaranteed even if predicate does not really consistently
represent a total order (in which case the elements will be scrambled in
some unpredictable way, but no element will be lost). If the :key function
consistently returns meaningful keys, and the predicate does reflect some
total ordering criterion on those keys, then the elements of the result sequence
will be properly sorted according to that ordering.
For example:
(sort #(1 3 2 4 3 5) #'» => #(5 4 3 3 2 1)
•
(sort '«up 2) (down 1) (west 4) (south 3)) #'< :key #'cadr)
=> «DOWN 1) (UP 2) (SOUTH 3) (WEST 4))
The sorting operation performed by sort is not guaranteed stable. Elements
considered equal by predicate mayor may not be stay in their
original order. predicate is assumed to consider two elements x and y to be
equal if (funcall predicate x y) and (funcall predicate y x) are both false.
The function stable-sort guarantees stability, but may be slower than sort
in some situations.
The sorting operation is destructive, so in the cases where the argument
should not be destroyed, you must sort a copy of the argument. When the