The generic-comparability Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The generic-comparability Reference Manual

This is the generic-comparability Reference Manual, version 1.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:41:04 2022 GMT+0.

Table of Contents


1 Introduction

GENERIC-COMPARABILITY

This is an implementation of CDR-8. Build Status

CDR-8 provides an interface for the EQUALS function, which is defined as a general equality predicate, as well as a set of ordering (COMPARE) functions for comparison. The semantics are described in the CDR-8 standard.

 EQUALS a b &rest keys &key recursive &allow-other-keys → result
COMPARE a b &rest keys &key recursive &allow-other-keys → result

COMPARE returns >, <, =, /=


LT a b &rest keys &key recursive &allow-other-keys → result
LTE a b &rest keys &key recursive &allow-other-keys → result
GT a b &rest keys &key recursive &allow-other-keys → result
GTE a b &rest keys &key recursive &allow-other-keys → result

The *T(E?) family returns T, NIL, or raises the INCOMPARABLE-OBJECT condition.

Contributing

Please issue a pull request.

Versioning

Semantic Versioning

License


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 generic-comparability

CDR-8 implementation

Author

Paul Nathan

License

LLGPL

Version

1.0.1

Dependency

alexandria (system).

Source

generic-comparability.asd.

Child Component

generic-comparability.lisp (file).


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


3.1.1 generic-comparability/generic-comparability.asd

Source

generic-comparability.asd.

Parent Component

generic-comparability (system).

ASDF Systems

generic-comparability.


3.1.2 generic-comparability/generic-comparability.lisp

Source

generic-comparability.asd.

Parent Component

generic-comparability (system).

Packages

generic-comparability.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 generic-comparability

Source

generic-comparability.lisp.

Use List
  • alexandria.
  • common-lisp.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: incomparable-object (v1 v2)
Package

generic-comparability.

Source

generic-comparability.lisp.


5.1.2 Generic functions

Generic Function: compare (a b &rest keys &key recursive case-sensitive &allow-other-keys)

The generic function COMPARE defines methods to
test the ordering of two objects a and b, if such order exists. The result value returned by COMPARE is one of the four symbols: :<, :>, :=, or :/=. The COMPARE function returns :/= as result by default; thus it can represent partial orders among objects. The equality tests should be coherent with what the generic function EQUALS does.

If the argument recursive is T, then COMPARE may recurse down the ‘structure‘ of a and b. The description of each known method contains the relevant information about its recursive dependent behavior.

Package

generic-comparability.

Source

generic-comparability.lisp.

Methods
Method: compare ((a string) (b string) &rest keys &key case-sensitive)
Method: compare ((a character) (b character) &rest keys &key case-sensitive)
Method: compare ((a symbol) (b symbol) &rest keys)
Method: compare ((a number) (b number) &rest keys)
Method: compare (a b &rest keys)
Generic Function: equals (a b &rest keys &key recursive key by-key by-value check-properties reference-equality case-sensitive floating-compare max-relative-diff &allow-other-keys)

a b – Common Lisp objects.
recursive – a generalized boolean; default is NIL.
result – a boolean.
keys – a list (as per the usual behavior).
by-key – a generalized boolean; default is T.
by-values – a generalized boolean; default is T.
check-properties – a generalized boolean; default is NIL. case-sensitive – a generalized boolean; default is T.

Description:

The EQUALS generic functions defines methods to test for ‘equality‘ of two objects a and b. When two objects a and b are EQUALS under an appropriate and context-dependent notion of ‘equality‘, then the function returns T as result; otherwise EQUALS returns NIL as result.

If the argument recursive is T, then EQUALS may recurse down the ‘structure‘ of a and b. The description of each known method contains the relevant information about its recursive dependent behavior.

EQUALS provides some default behavior, but it is intended mostly as a hook for users. As such, it is allowed to add keyword arguments to user-defined EQUALS methods, as the &key and &allow-other-keys lambda-list markers imply.

Package

generic-comparability.

Source

generic-comparability.lisp.

Methods
Method: equals ((a array) (b array) &rest keys &key recursive &allow-other-keys)

EQUALS array array &key recursive

This implements a straightforward comparison element by element of the array.

Method: equals ((a hash-table) (b hash-table) &rest keys &key recursive by-key by-value check-properties &allow-other-keys)

EQUALS hash-table hash-table &key recursive (by-key t) (by-value t) (check-properties t)

by-key implies checking hash table keys for equality

by-value implies checking hash table values for equality

check-properties implies checking both hash-table-rehash-size and
hash-table rehash-threshhold.

This is expensive: O( 2 * n * (time-of-key-comparison + time-of-value-comparison)).

Method: equals ((a standard-object) (b standard-object) &rest keys)
Method: equals ((a structure-object) (b structure-object) &rest keys &key reference-equality)
Method: equals ((a string) (b string) &rest keys &key case-sensitive)
Method: equals ((a character) (b character) &rest keys &key case-sensitive)
Method: equals ((a cons) (b cons) &rest keys)
Method: equals ((a number) (b number) &rest keys)
Method: equals ((a float) (b float) &rest keys &key floating-compare max-relative-diff)

EQUALS float float &key (floating-compare nil) (max-relative-diff 1.19e7)

If floating-compare is true, then the floating comparison algorithm is used, as opposed to ‘=‘.

The floating comparison is derived from here: http://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/

The Internet Archive has a copy of this URL.

The implemented algorithm is AlmostEqualRelative. It is not the best
possible float equality algorithm, but is simple and
understandable (and easy to code). Improvements with citations from
the literature are welcome.

Observe the following comparison and beware:
CL-USER> (equals 1.0 1.0000001 :floating-compare t)
NIL
CL-USER> (equals 1.0 1.00000001 :floating-compare t)
T

Method: equals (a b &rest keys)
Generic Function: greaterp (a b &rest keys &key recursive &allow-other-keys)
Package

generic-comparability.

Alias for

gt.

Generic Function: gt (a b &rest keys &key recursive &allow-other-keys)
Package

generic-comparability.

Source

generic-comparability.lisp.

Methods
Method: gt (a b &rest keys)
Generic Function: gte (a b &rest keys &key recursive &allow-other-keys)
Package

generic-comparability.

Source

generic-comparability.lisp.

Methods
Method: gte (a b &rest keys)
Generic Function: hash-code (a)

The HASH-CODE generic function is provided as a
companion to EQUALS for the benefit of those Common Lisp implementations that provide a handle on the inner working of hash tables (usually in the form of an extra :sxhash or :hash-function keyword argument to make-hash-table), or for bottom-up hash table implementations.

HASH-CODE is modeled after the Java hashCode() method of java.lang.Object. The same description applies almost unchanged.

The general contract of HASH-CODE is the following.

Whenever it is invoked on the same object more than once during an a Common Lisp session, the HASH-CODE generic function must consistently return the same fixnum, provided no information used in EQUALS comparisons on the object a is modified. This integer need not remain consistent from one Common Lisp session to another. If two objects are equal according to the EQUALS generic predicate, then calling the HASH-CODE generic function on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the EQUALS generic predicate, then calling the HASH-CODE generic function on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

Package

generic-comparability.

Source

generic-comparability.lisp.

Methods
Method: hash-code (a)

The generic hash-code implementation defaults to SXHASH of the value passed in.

Generic Function: lessp (a b &rest keys &key recursive &allow-other-keys)
Package

generic-comparability.

Alias for

lt.

Generic Function: lt (a b &rest keys &key recursive &allow-other-keys)
Package

generic-comparability.

Source

generic-comparability.lisp.

Methods
Method: lt (a b &rest keys)
Generic Function: lte (a b &rest keys &key recursive &allow-other-keys)
Package

generic-comparability.

Source

generic-comparability.lisp.

Methods
Method: lte (a b &rest keys)
Generic Function: not-greaterp (a b &rest keys &key recursive &allow-other-keys)
Package

generic-comparability.

Alias for

lte.

Generic Function: not-lessp (a b &rest keys &key recursive &allow-other-keys)
Package

generic-comparability.

Alias for

gte.


5.1.3 Standalone methods

Method: print-object ((object incomparable-object) stream)
Source

generic-comparability.lisp.


5.1.4 Conditions

Condition: incomparable-object
Package

generic-comparability.

Source

generic-comparability.lisp.

Direct superclasses

error.

Direct methods
Direct slots
Slot: value1
Initform

(quote nil)

Initargs

:value1

Readers

value1.

Writers

(setf value1).

Slot: value2
Initform

(quote nil)

Initargs

:value2

Readers

value2.

Writers

(setf value2).


5.2 Internals


Previous: , Up: Internals   [Contents][Index]

5.2.1 Generic functions

Generic Reader: value1 (condition)
Generic Writer: (setf value1) (condition)
Package

generic-comparability.

Methods
Reader Method: value1 ((condition incomparable-object))
Writer Method: (setf value1) ((condition incomparable-object))
Source

generic-comparability.lisp.

Target Slot

value1.

Generic Reader: value2 (condition)
Generic Writer: (setf value2) (condition)
Package

generic-comparability.

Methods
Reader Method: value2 ((condition incomparable-object))
Writer Method: (setf value2) ((condition incomparable-object))
Source

generic-comparability.lisp.

Target Slot

value2.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
C   E   F   G   H   I   L   M   N   P   V  
Index Entry  Section

(
(setf value1): Private generic functions
(setf value1): Private generic functions
(setf value2): Private generic functions
(setf value2): Private generic functions

C
compare: Public generic functions
compare: Public generic functions
compare: Public generic functions
compare: Public generic functions
compare: Public generic functions
compare: Public generic functions

E
equals: Public generic functions
equals: Public generic functions
equals: Public generic functions
equals: Public generic functions
equals: Public generic functions
equals: Public generic functions
equals: Public generic functions
equals: Public generic functions
equals: Public generic functions
equals: Public generic functions
equals: Public generic functions

F
Function, incomparable-object: Public ordinary functions

G
Generic Function, (setf value1): Private generic functions
Generic Function, (setf value2): Private generic functions
Generic Function, compare: Public generic functions
Generic Function, equals: Public generic functions
Generic Function, greaterp: Public generic functions
Generic Function, gt: Public generic functions
Generic Function, gte: Public generic functions
Generic Function, hash-code: Public generic functions
Generic Function, lessp: Public generic functions
Generic Function, lt: Public generic functions
Generic Function, lte: Public generic functions
Generic Function, not-greaterp: Public generic functions
Generic Function, not-lessp: Public generic functions
Generic Function, value1: Private generic functions
Generic Function, value2: Private generic functions
greaterp: Public generic functions
gt: Public generic functions
gt: Public generic functions
gte: Public generic functions
gte: Public generic functions

H
hash-code: Public generic functions
hash-code: Public generic functions

I
incomparable-object: Public ordinary functions

L
lessp: Public generic functions
lt: Public generic functions
lt: Public generic functions
lte: Public generic functions
lte: Public generic functions

M
Method, (setf value1): Private generic functions
Method, (setf value2): Private generic functions
Method, compare: Public generic functions
Method, compare: Public generic functions
Method, compare: Public generic functions
Method, compare: Public generic functions
Method, compare: Public generic functions
Method, equals: Public generic functions
Method, equals: Public generic functions
Method, equals: Public generic functions
Method, equals: Public generic functions
Method, equals: Public generic functions
Method, equals: Public generic functions
Method, equals: Public generic functions
Method, equals: Public generic functions
Method, equals: Public generic functions
Method, equals: Public generic functions
Method, gt: Public generic functions
Method, gte: Public generic functions
Method, hash-code: Public generic functions
Method, lt: Public generic functions
Method, lte: Public generic functions
Method, print-object: Public standalone methods
Method, value1: Private generic functions
Method, value2: Private generic functions

N
not-greaterp: Public generic functions
not-lessp: Public generic functions

P
print-object: Public standalone methods

V
value1: Private generic functions
value1: Private generic functions
value2: Private generic functions
value2: Private generic functions

Jump to:   (  
C   E   F   G   H   I   L   M   N   P   V  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   S   V  
Index Entry  Section

S
Slot, value1: Public conditions
Slot, value2: Public conditions

V
value1: Public conditions
value2: Public conditions

Jump to:   S   V