make-sorting-description Function

Summary

Makes a sorting description suitable for use in a sorted-object.

Package

capi

Signature

make-sorting-description &key type key sort reverse-sort sort-function object-sort-caller => sorting-description

Arguments

Values

Description

The function make-sorting-description makes a sorting description object that can be used as one of the sort-descriptions in a sorted-object such as a list-panel.

type is a name that should be unique (compared by cl:equalp) amongst the sort-descriptions of a sorted-object.

key is a function that is passed to sort-function as its :key argument. The default value of key is cl:identity.

sort is a predicate function that is passed to sort-function to compare pairs of items.

reverse-sort is a predicate function that is passed to sort-function for reverse sorting.

Unless object-sort-caller is supplied, sort-function is the function that is called to actually do the sorting. Its signature is:

sort-function items predicate &key key

The default value of sort-function is cl:sort.

When object-sort-caller is supplied, then it is called instead of calling sort-function, and is responsible for the sorting. The signature of the caller is:

object-sort-caller sorted-object items sort-function sort-predicate key => sorted-items

where sorted-object is the sorted-object itself, items is the list of items to sort, and sort-function, sort-predicate and key are taken from the description. sort-predicate is either sort or reverse-sort as appropriate. The caller needs to return a sorted list of the items.

The caller can do the default behavior by:

funcall sort-function item sort :key key

Notes

1. The purpose of using object-sort-caller is to allow access to the sorted-object to decide how to do the sorting. When using object-sort-caller, sort-function, sort, reverse-sort and key are used solely as arguments to it, hence in this case you can supply arbitrary values which the caller interprets.
2. The sorting can be destructive.

Examples

(setq lp 
      (capi:contain 
       (make-instance 
        'capi:list-panel 
        :items '("Apple" 
                 "Orange" 
                 "Mangosteen" 
                 "Pineapple")
        :visible-min-height '(:character 5)
        :sort-descriptions 
        (list (capi:make-sorting-description 
               :type :length
               :sort 
               #'(lambda (x y) 
                   (> (length x) (length y)))
               :reverse-sort 
               #'(lambda (x y) 
                   (< (length x) (length y))))
              (capi:make-sorting-description 
               :type :alphabetic
               :sort 'string-greaterp
               :reverse-sort 'string-lessp)))))
 
(capi:sorted-object-sort-by lp :length)
 
(capi:sorted-object-sort-by lp :alphabetic)

See also

sort-object-items-by
sorted-object
sorted-object-sort-by