sort and stable-sort destructively sort sequences
according to the order determined by the predicate function.
If sequence is a vector,
the result is a vector
that has the same actual array element type as sequence.
If sequence is a list,
the result is a list.
sort determines the relationship between two elements
by giving keys extracted from the elements to the predicate.
The first argument to the predicate function is the part of one element
of sequence extracted by the key function
(if supplied); the second
argument is the part of another element
of sequence extracted by the key function
(if supplied).
Predicate should return true 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 the predicate should return false.
The argument to the key function is the sequence element.
The return value of the key function
becomes an argument to predicate.
If key is not supplied or nil, the sequence element itself is used.
There is no guarantee on the number of times the key will be called.
If the key and predicate always return,
then the sorting operation will always terminate,
producing a sequence containing the same elements as sequence
(that is, the result is a permutation of sequence).
This is guaranteed even if the 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 consistently returns meaningful keys,
and the predicate does reflect some total ordering criterion on those keys,
then the elements of the sorted-sequence
will be properly sorted according to that ordering.
The sorting operation performed by sort is not guaranteed stable.
Elements considered equal by the predicate might or might not
stay in their original order. The 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.
stable-sort guarantees stability.
The sorting operation can be destructive in all cases. In the case of a
vector
argument, this is accomplished by permuting the elements in place.
In the case of a list, the list is
destructively reordered in the same manner as for
nreverse.