The generic-comparability Reference Manual

Table of Contents

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 2.4 "Will Decker" on Wed Jun 20 11:52:14 2018 GMT+0.


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

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


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

2 Systems

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


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

2.1 generic-comparability

Author

Paul Nathan

License

LLGPL

Description

CDR-8 implementation

Version

1.0.1

Dependency

alexandria

Source

generic-comparability.asd (file)

Component

generic-comparability.lisp (file)


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

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


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 generic-comparability.asd

Location

generic-comparability.asd

Systems

generic-comparability (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 generic-comparability/generic-comparability.lisp

Parent

generic-comparability (system)

Location

generic-comparability.lisp

Packages

generic-comparability

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 generic-comparability

Source

generic-comparability.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: incomparable-object V1 V2
Package

generic-comparability

Source

generic-comparability.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

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 (file)

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

Source

generic-comparability.lisp (file)

Methods
Method: greaterp A B &rest KEYS
Generic Function: gt A B &rest KEYS &key RECURSIVE &allow-other-keys
Package

generic-comparability

Source

generic-comparability.lisp (file)

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 (file)

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 (file)

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

Source

generic-comparability.lisp (file)

Methods
Method: lessp A B &rest KEYS
Generic Function: lt A B &rest KEYS &key RECURSIVE &allow-other-keys
Package

generic-comparability

Source

generic-comparability.lisp (file)

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 (file)

Methods
Method: lte A B &rest KEYS
Generic Function: not-greaterp A B &rest KEYS &key RECURSIVE &allow-other-keys
Package

generic-comparability

Source

generic-comparability.lisp (file)

Methods
Method: not-greaterp A B &rest KEYS
Generic Function: not-lessp A B &rest KEYS &key RECURSIVE &allow-other-keys
Package

generic-comparability

Source

generic-comparability.lisp (file)

Methods
Method: not-lessp A B &rest KEYS

Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Conditions

Condition: incomparable-object ()
Package

generic-comparability

Source

generic-comparability.lisp (file)

Direct superclasses

error (condition)

Direct methods
  • print-object (method)
  • value2 (method)
  • value2 (method)
  • value1 (method)
  • value1 (method)
Direct slots
Slot: value1
Initargs

:value1

Initform

(quote nil)

Readers

value1 (generic function)

Writers

(setf value1) (generic function)

Slot: value2
Initargs

:value2

Initform

(quote nil)

Readers

value2 (generic function)

Writers

(setf value2) (generic function)


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

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Generic functions

Generic Function: value1 CONDITION
Generic Function: (setf value1) NEW-VALUE CONDITION
Package

generic-comparability

Methods
Method: value1 (CONDITION incomparable-object)
Method: (setf value1) NEW-VALUE (CONDITION incomparable-object)
Source

generic-comparability.lisp (file)

Generic Function: value2 CONDITION
Generic Function: (setf value2) NEW-VALUE CONDITION
Package

generic-comparability

Methods
Method: value2 (CONDITION incomparable-object)
Method: (setf value2) NEW-VALUE (CONDITION incomparable-object)
Source

generic-comparability.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   G   L  
Index Entry  Section

F
File, Lisp, generic-comparability.asd: The generic-comparability<dot>asd file
File, Lisp, generic-comparability/generic-comparability.lisp: The generic-comparability/generic-comparability<dot>lisp file

G
generic-comparability.asd: The generic-comparability<dot>asd file
generic-comparability/generic-comparability.lisp: The generic-comparability/generic-comparability<dot>lisp file

L
Lisp File, generic-comparability.asd: The generic-comparability<dot>asd file
Lisp File, generic-comparability/generic-comparability.lisp: The generic-comparability/generic-comparability<dot>lisp file

Jump to:   F   G   L  

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

A.2 Functions

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

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

C
compare: Exported generic functions
compare: Exported generic functions
compare: Exported generic functions
compare: Exported generic functions
compare: Exported generic functions
compare: Exported generic functions

E
equals: Exported generic functions
equals: Exported generic functions
equals: Exported generic functions
equals: Exported generic functions
equals: Exported generic functions
equals: Exported generic functions
equals: Exported generic functions
equals: Exported generic functions
equals: Exported generic functions
equals: Exported generic functions
equals: Exported generic functions

F
Function, incomparable-object: Exported functions

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

H
hash-code: Exported generic functions
hash-code: Exported generic functions

I
incomparable-object: Exported functions

L
lessp: Exported generic functions
lessp: Exported generic functions
lt: Exported generic functions
lt: Exported generic functions
lte: Exported generic functions
lte: Exported generic functions

M
Method, (setf value1): Internal generic functions
Method, (setf value2): Internal generic functions
Method, compare: Exported generic functions
Method, compare: Exported generic functions
Method, compare: Exported generic functions
Method, compare: Exported generic functions
Method, compare: Exported generic functions
Method, equals: Exported generic functions
Method, equals: Exported generic functions
Method, equals: Exported generic functions
Method, equals: Exported generic functions
Method, equals: Exported generic functions
Method, equals: Exported generic functions
Method, equals: Exported generic functions
Method, equals: Exported generic functions
Method, equals: Exported generic functions
Method, equals: Exported generic functions
Method, greaterp: Exported generic functions
Method, gt: Exported generic functions
Method, gte: Exported generic functions
Method, hash-code: Exported generic functions
Method, lessp: Exported generic functions
Method, lt: Exported generic functions
Method, lte: Exported generic functions
Method, not-greaterp: Exported generic functions
Method, not-lessp: Exported generic functions
Method, value1: Internal generic functions
Method, value2: Internal generic functions

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

V
value1: Internal generic functions
value1: Internal generic functions
value2: Internal generic functions
value2: Internal generic functions

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

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

A.3 Variables

Jump to:   S   V  
Index Entry  Section

S
Slot, value1: Exported conditions
Slot, value2: Exported conditions

V
value1: Exported conditions
value2: Exported conditions

Jump to:   S   V  

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

A.4 Data types

Jump to:   C   G   I   P   S  
Index Entry  Section

C
Condition, incomparable-object: Exported conditions

G
generic-comparability: The generic-comparability system
generic-comparability: The generic-comparability package

I
incomparable-object: Exported conditions

P
Package, generic-comparability: The generic-comparability package

S
System, generic-comparability: The generic-comparability system

Jump to:   C   G   I   P   S