Node:Sorting,
Next:Copying,
Previous:Object Properties,
Up:Utility Functions
24.3 Sorting
Sorting is very important in computer programs. Therefore, Guile comes
with several sorting procedures builtin. As always, procedures with
names ending in !
are sideeffecting, that means that they may
modify their parameters in order to produce their results.
The first group of procedures can be used to merge two lists (which must
be already sorted on their own) and produce sorted lists containing
all elements of the input lists.
merge alist blist less

Scheme Procedure 
scm_merge (alist, blist, less)

C Function 
Merge two already sorted lists into one.
Given two lists alist and blist, such that
(sorted? alist less?) and (sorted? blist less?) ,
return a new list in which the elements of alist and
blist have been stably interleaved so that
(sorted? (merge alist blist less?) less?) .
Note: this does _not_ accept vectors.

merge! alist blist less

Scheme Procedure 
scm_merge_x (alist, blist, less)

C Function 
Takes two lists alist and blist such that
(sorted? alist less?) and (sorted? blist less?) and
returns a new list in which the elements of alist and
blist have been stably interleaved so that
(sorted? (merge alist blist less?) less?) .
This is the destructive variant of merge
Note: this does _not_ accept vectors.

The following procedures can operate on sequences which are either
vectors or list. According to the given arguments, they return sorted
vectors or lists, respectively. The first of the following procedures
determines whether a sequence is already sorted, the other sort a given
sequence. The variants with names starting with stable
are
special in that they maintain a special property of the input sequences:
If two or more elements are the same according to the comparison
predicate, they are left in the same order as they appeared in the
input.
sorted? items less

Scheme Procedure 
scm_sorted_p (items, less)

C Function 
Return #t iff items is a list or a vector such that
for all 1 <= i <= m, the predicate less returns true when
applied to all elements i  1 and i

sort items less

Scheme Procedure 
scm_sort (items, less)

C Function 
Sort the sequence items, which may be a list or a
vector. less is used for comparing the sequence
elements. This is not a stable sort.

sort! items less

Scheme Procedure 
scm_sort_x (items, less)

C Function 
Sort the sequence items, which may be a list or a
vector. less is used for comparing the sequence
elements. The sorting is destructive, that means that the
input sequence is modified to produce the sorted result.
This is not a stable sort.

stablesort items less

Scheme Procedure 
scm_stable_sort (items, less)

C Function 
Sort the sequence items, which may be a list or a
vector. less is used for comparing the sequence elements.
This is a stable sort.

stablesort! items less

Scheme Procedure 
scm_stable_sort_x (items, less)

C Function 
Sort the sequence items, which may be a list or a
vector. less is used for comparing the sequence elements.
The sorting is destructive, that means that the input sequence
is modified to produce the sorted result.
This is a stable sort.

The procedures in the last group only accept lists or vectors as input,
as their names indicate.
sortlist items less

Scheme Procedure 
scm_sort_list (items, less)

C Function 
Sort the list items, using less for comparing the
list elements. This is a stable sort.

sortlist! items less

Scheme Procedure 
scm_sort_list_x (items, less)

C Function 
Sort the list items, using less for comparing the
list elements. The sorting is destructive, that means that the
input list is modified to produce the sorted result.
This is a stable sort.

restrictedvectorsort! vec less startpos endpos

Scheme Procedure 
scm_restricted_vector_sort_x (vec, less, startpos, endpos)

C Function 
Sort the vector vec, using less for comparing
the vector elements. startpos and endpos delimit
the range of the vector which gets sorted. The return value
is not specified.
