Next: Simple adjustable-size strings, Previous: Portable runtime environment inquiry, Up: Library modules - SRFIs [Contents][Index]

`srfi-114`

- Comparators- Module:
**srfi-114** -
This module is provided for the compatibility of code using srfi-114. The new code should use srfi-128, which is fully built-in.

The following procedures are built-in. See Basic comparators, for
the detailed documentation. Those are also exported from `srfi-114`

for the compatibility.

- Predicates
`comparator?`

,- Standard comparators
`boolean-comparator`

,`char-comparator`

,`char-ci-comparator`

,`string-comparator`

,`string-ci-comparator`

,`symbol-comparator`

,`exact-integer-comparator`

,`integer-comparator`

,`rational-comparator`

,`real-comparator`

,`complex-comparator`

,`number-comparator`

,`pair-comparator`

,`list-comparator`

,`vector-comparator`

,`bytevector-comparator`

,`uvector-comparator`

- The default comparator
`default-comparator`

- Wrapped equality predicates
`eq-comparator`

,`eqv-comparator`

,`equal-comparator`

- Accessors
`comparator-equality-predicate`

,`comparator-comparison-procedure`

,`comparator-hash-function`

- Primitive applicators
`comparator-test-type`

,`comparator-check-type`

,`comparator-compare`

,`comparator-hash`

- Comparison predicates
`=?`

,`<?`

,`<=?`

,`>?`

,`>=?`

- Function:
**make-comparator***type-test equal compare hash :optional name* [SRFI-114+] {

`srfi-114`} This is SRFI-114 style comparator constructor. The optional`name`argument is Gauche’s extension.This is the same as built-in

`make-comparator/compare`

. See Basic comparators, for the details.Do not confuse this with built-in (SRFI-128)

`make-comparator`

; if you`(use srfi-114)`

, this one shadows the built-in one.Note that a comparator works for both SRFI-114 and SRFI-128 procedures, regardless of how it is constructed.

- Function:
**comparator-comparison-procedure?***c* - Function:
**comparator-hash-function?***c* [SRFI-114] {

`srfi-114`} Returns true iff a comparator`c`can be used to order objects or to hash them, respectively. These are aliases of built-in`comparator-ordered?`

and`comparator-hashable?`

.

- Function:
**comparator-type-test-procedure***c* [SRFI-114] {

`srfi-114`} Returns type test predicate of a comparator`c`. This is an alias of built-in`comparator-type-test-predicate`

.

- Function:
**comparator-equal?***c a b* [SRFI-114] {

`srfi-114`} Checks equality of`a`and`b`using the equality predicate of a comparator`c`. This can be also written in`=?`

, which is built-in (see Comparator predicates and accessors).(=? c a b)

- Function:
**make-inexact-real-comparator***epsilon rounding nan-handling* [SRFI-114] {

`srfi-114`} Returns a comparator for inexact real numbers, taking into account of errors and NaNs.The basic idea is that we compare two finite real numbers after rounding them to

`epsilon`interval, which must be a nonnegative real number. (Note that it’s not to compare two numbers “close enough”, as often being done to compare inexact numbers. “Close enough” scheme won’t be transitive.)The rounding mode is specified by the

`rounding`argument. It can be either one of the symbols`round`

,`ceiling`

,`floor`

or`truncate`

, or a procedure that takes two arguments, a real number and an epsilon, and returns the rounded result of the first argument according to the given epsilon.The

`nan-handling`argument determines how to handle the case to compare NaN and non-NaN numbers. (If both are NaNs, this comparator regards them as equal). It can be either one of the followings:`min`

If it’s a symbol

`min`

, NaN is compared as smaller than all other real numbers, even than`-inf.0`

.`max`

If it’s a symbol

`min`

, NaN is compared as greater than all other real numbers, even than`+inf.0`

.`error`

If it’s a symbol

`error`

, an error is signaled.- a procedure taking one argument
The procedure is invoked with the real number which is not NaN. If it ever returns, it must return either 1, 0 or -1, for it’s used as the result of the comparison procedure of the comparator. However, since the procedure doesn’t know

*which*argument is non-NaN, it’s hard to have consistent semantics; the best bet is to throw a custom error.

(define c (make-inexact-real-comparator 0.1 'round 'error)) (comparator-compare c 0.112 0.098) ⇒ 0 (comparator-compare c 0.131 0.172) ⇒ -1

Note: Rounding to the nearest epsilon interval would involve scaling inexact numbers, and that may reveal small difference between the actual number and its notation. For example, an inexact real number denoted as

`0.15`

is actually slightly smaller than`15/100`

, and rounding with epsilon`0.1`

would result`0.1`

, not`0.2`

.

- Function:
**make-car-comparator***cmpr* - Function:
**make-cdr-comparator***cmpr* [SRFI-114] {

`srfi-114`} Returns comparators that accept pairs, and compare them with their car or cdr by`cmpr`, respectively.Using

`make-key-comparator`

, these cam be written as follows (see Combining comparators, for`make-key-comparator`

).(define (make-car-comparator cmpr) (make-key-comparator cmpr pair? car)) (define (make-cdr-comparator cmpr) (make-key-comparator cmpr pair? cdr))

- Function:
**make-list-comparator***element-comparator* - Function:
**make-vector-comparator***element-comparator* - Function:
**make-bytevector-comparator***element-comparator* {

`srfi-114`} [SRFI-114] Returns a new comparator that compares lists, vectors and bytevectors element-wise using`element-comparator`, respectively. These are more general versions of`list-comparator`

,`vector-comparator`

and`bytevector-comparator`

, which use`default-comparator`

as`element-comparator`.For a list comparator, it is an error to pass improper lists.

Note that comparing sequences of different lengths is slightly different between lists and vector/bytevectors. List comparator uses “dictionary” order, so

`(1 3)`

comes after`(1 2 3)`

, assuming elements are compared numerically. For vectors and bytevectors, shorter one always precedes the other, so`#(1 3)`

comes before`#(1 2 3)`

.

- Function:
**make-listwise-comparator***type-test element-comparator empty? head tail* [SRFI-114] {

`srfi-114`} More general version of`make-list-comparator`

. Returns a comparator that compares structures which can be traversed using three procedures,`empty?`,`head`and`tail`. Each of those procedure receives a structure to be compared, and`empty?`must return`#t`

iff the structure is empty,`head`must return the first element in the structure, and`tail`must return the same type of structure containing all the elements but the head. The`type-test`predicate checks if the arguments passed to the comparator to be a suitable structure.That is,

`make-list-comparator`

can be written in`make-listwise-comparator`

as follows.(make-list-compartator element-comparator) ≡ (make-listwise-comparator list? element-comparator null? car cdr)

This can be used to compare list-like structures. For example, the following call returns a comparator that compares elements of two lazy streams (see Stream library).

(make-listwise-comparator stream? element-comparator stream-null? stream-car stream-cdr)

- Function:
**make-vectorwise-comparator***type-test element-comparator length ref* [SRFI-114] {

`srfi-114`} More general version of`make-vector-comparator`

. Returns a comparator that compares structures which can be traversed using two procedures,`length`and`ref`. The`length`procedure must return the number of elements in the structure. The`ref`procedure receives a structure and a nonnegative exact integer index`k`, and must return`k`-th element of the structure.That is, the following equivalence holds:

(make-vector-comparator element-comparator) ≡ (make-vectorwise-comparator vector? element-comparator vector-length vector-ref) (make-bytevector-comparator element-comparator) ≡ (make-vectorwise-comparator u8vector? element-comparator u8vector-length u8vector-ref)

- Function:
**make-pair-comparator***car-comparator cdr-comparator* [SRFI-114] {

`srfi-114`} Creates a comparator that compares pairs, with their cars by`car-comparator`and their cdrs by`cdr-comparator`.

- Function:
**make-improper-list-comparator***element-comparator* [SRFI-114] {

`srfi-114`} This may be understood as recursive pair comparator; if objects to be compared are pairs, we recurse their cars then their cdrs. If objects to be compared are not pairs, we use`element-comparator`to compare them.

- Function:
**make-selecting-comparator***comparator1 comparator2 …* [SRFI-114] {

`srfi-114`} This creates a comparator that works any one of the given comparators; the objects to be compared are type-tested with each of the comparators in order, and the first comparator that accepts all objects will be used.

- Function:
**make-refining-comparator***comparator1 comparator2 …* [SRFI-114] {

`srfi-114`} This is similar to`make-selecting-comparator`

, except that if the first comparator that accepts given objects to compare finds they are equal (or 0 by the comparison procedure), it tries other comparators down the list, if any.

- Function:
**make-reverse-comparator***comparator* [SRFI-114] {

`srfi-114`} Returns a comparator that just reverses the comparison order of`comparator`.

- Function:
**make-debug-comparator***comparator* [SRFI-114] {

`srfi-114`}

- Function:
**make-comparison<***lt-pred* - Function:
**make-comparison>***gt-pred* - Function:
**make-comparison<=***le-pred* - Function:
**make-comparison>=***ge-pred* - Function:
**make-comparison=/<***eq-pred lt-pred* - Function:
**make-comparison=/>***eq-pred gt-pred* [SRFI-114] {

`srfi-114`} Utility procedures to create a comparison procedure (the one returns -1, 0, or 1) from the given predicate. For example,`make-comparison<`

can be defined as follows:(define (make-comparison< pred) (^[a b] (cond [(pred a b) -1] [(pred b a) 1] [else 0])))

- Macro:
**if3***expr less equal greater* [SRFI-114] {

`srfi-114`} Three-way`if`

: Evaluates`expr`, and then evaluates either one of`less`,`equal`, or`greater`, depending on the value of`expr`is either less than zero, equal to zero, or greater than zero, respectively.

- Macro:
**if=?***expr consequent :optional alternate* - Macro:
**if<?***expr consequent :optional alternate* - Macro:
**if>?***expr consequent :optional alternate* - Macro:
**if<=?***expr consequent :optional alternate* - Macro:
**if>=?***expr consequent :optional alternate* - Macro:
**if-not=?***expr consequent :optional alternate* [SRFI-114] {

`srfi-114`} Conditional evaluation according to comparison expression`expr`; that is,`if`

evaluates`OP`?`consequent`if`(`

is true, otherwise it evaluates`OP`expr 0)`alternate`when provided.(if<? (compare 10 20) 'yes) ⇒ yes (if>=? (compare 10 20) 'yes 'no) ⇒ no

- Function:
**make=?***comparator* - Function:
**make<?***comparator* - Function:
**make>?***comparator* - Function:
**make<=?***comparator* - Function:
**make>=?***comparator* [SRFI-114] {

`srfi-114`}((make=? comparator) obj1 obj2 obj3 …) ≡ (=? comparator obj1 obj2 obj3 …)

- Function:
**in-open-interval?***[comparator] obj1 obj2 obj3* - Function:
**in-closed-interval?***[comparator] obj1 obj2 obj3* - Function:
**in-open-closed-interval?***[comparator] obj1 obj2 obj3* - Function:
**in-closed-open-interval?***[comparator] obj1 obj2 obj3* [SRFI-114] {

`srfi-114`} Check if`obj1`,`obj2`and`obj3`has the following relationships:(and (op1 obj1 obj2) (op2 obj2 obj3))

Where each of

`op1`and`op2`can be`(make<? comparator)`

(if that end is*open*), or`(make<=? comparator)`

(if that end is*closed*).When

`comparator`is omitted, the default comparator is used.(use srfi-42) (list-ec (: x 0 5) (list x (in-closed-open-interval? 1 x 3))) ⇒ ((0 #f) (1 #t) (2 #t) (3 #f) (4 #f))

`comparator-min`

and `comparator-max`

are the
same as `srfi-162`

. See Comparator sublibrary.

DRAFT