The table-extensions Module

This library contains a number of useful additional table classes, and a number of functions that could be useful in constructing your own table classes.


<case-insensitive-string-table> [ sealed instantiable Class]

Implements a <table> class, keyed by strings keyed without regard for case.

Superclasses

<value-table>

Initialization Keywords

None.

Description

<case-insensitive-string-table> implements a <table> class whose keys are instances of <string> . However, instead of using \= for the equivalence relation, strings which are the same modulo case are considered equivalent.

Note that the case-insensitivity is true in general only for English strings -- non-English characters have their case "normalized" by subtracting the difference in integer code for the character 'a' and 'A'. This works only for ASCII and Unicode, and only for English.


<equal-table> [ sealed instantiable Class]

Implements a class which compares keys using \= .

Superclasses

<table>

Initialization Keywords

None.

Description

<equal-table> implements a <table> class whose keys are compared with \= rather than \== . So for example, two instances of list that don't have object identity, but did contain references to the same object, would be considered equivalent keys by <equal-table> .


<hash-state> [Class]

The type of hash states.

Superclasses

None.

Initialization Keywords

None.

Description

<hash-state> is the type of the hash state returned as the second value of hash functions. For example, $permanent-hash-state is of type <hash-state> .


<string-table> [ sealed instantiable Class]

A <table> class keyed by strings.

Superclasses

<value-table>

Initialization Keywords

None.

Description

This class implements a <table> class that is keyed by \= equal <string> instances.


<value-table>[ open abstract Class]

Intended as the abstract superclass of user-defined tables.

Superclasses

<table>

Initialization Keywords

None.

Description

This class is intended to be an abstract superclass of <table> classes that have user-defined key comparison and hash functions. (NB: The hash functions cannot involve physical addresses.)


case-insensitive-equal [Generic]

Tests whether two objects (usually strings) are the same modulo case.

Synopsis

case-insensitive-equal ( object-1 , object-2 ) => ( answer )

Parameters

object-1 An instance of <object> .
object-2 An instance of <object> .

Return Values

answer An instance of <boolean> .

Description

Tests whether two objects have the same string value modulo case. Comparisons to non- <string> or <character> instances return #f.


case-insensitive-equal [Method]

Least-specific method testing whether two objects are the same modulo case.

Synopsis

case-insensitive-equal ( object-1 , object-2 ) => ( answer )

Parameters

object-1 An instance of <object> .
object-2 An instance of <object> .

Return Values

answer An instance of <boolean> .

Description

Since at least one of the arguments is not a <character> or <string> , this method always returns #f.


case-insensitive-equal [Method]

Method testing whether two characters are the same modulo case.

Synopsis

case-insensitive-equal ( object-1 , object-2 ) => ( answer )

Parameters

object-1 An instance of <character> .
object-2 An instance of <character> .

Return Values

answer An instance of <boolean> .

Description

This method returns #t if either the two arguments are the same character, or if they are alphabetic characters that are the same character modulo case. (This only works for English characters in general.)


case-insensitive-equal [Method]

Method testing whether two strings are the same modulo case.

Synopsis

case-insensitive-equal ( object-1 , object-2 ) => ( answer )

Parameters

object-1 An instance of <string> .
object-2 An instance of <string> .

Return Values

answer An instance of <boolean> .

Description

This method returns #t if the two arguments are the same size, and each component character returns #t with a case-insensitive-equal.


case-insensitive-string-hash[Function]

The default hash function for case-insensitive strings.

Synopsis

case-insensitive-string-hash ( s , initial-state ) => ( id , hash-state )

Parameters

s An instance of <string> .
initial-state An instance of <hash-state> .

Return Values

id An instance of <integer> .
hash-state An instance of <hash-state> .

Description

This is a convenient hash function for case-insensitive strings. It is returned as the table-protocol method's second value for <case-insensitive-string-table> .


collection-hash [Function]

A function for building hash functions that test collection equivalence.

Synopsis

collection-hash ( key-hash , element-hash , col , initial-state , #key ordered ) => ( id , state )

Parameters

key-hash An instance of <function> . Computes hash ids for the keys. It takes an object and a <hash-state> as an argument, and returns a hash id and a hash state.
element-hash An instance of <function> . Computes hash ids for the elements. It takes an object and a <hash-state> as an argument, and returns a hash id and a hash state.
col An instance of <collection> .
initial-state An instance of <hash-state> .
ordered :An instance of <boolean> . Whether or not to do an ordered merge of the key/element hash codes. The default is #f.

Return Values

id An instance of <integer> . The hash id.
state An instance of <hash-state> .

Description

Two collections will yield the same hash id, if each of their keys/element pairs hash to the same value. It's safe to set the ordered: keyword argument to #t only if the collection has a natural iteration order.


equal-hash [Generic]

Computes hash ids for objects such that two objects that are \= equal have the same hash id.

Synopsis

equal-hash ( thing , state ) => ( id , state )

Parameters

thing An instance of <object> .
state An instance of <hash-state> .

Return Values

id An instance of <integer> .
state An instance of <hash-state> .

Description

Methods on equal-hash should return hash ids such that the id for two \= equal objects are the same.

There is a default method is defined on all instances of <object>, and it returns a valid hash id in all cases. However, performance *will* suck horribly (algorithmically, even) if you don't define better methods for your own objects that will live in <equal-table> instances.

Good methods for equal-hash are defined for <integer>, <float>, <symbol>, <type>, <function>, <boolean>, <condition>, and <collection>. (Note that <collection> is a supertype of <string>.)


remove-all-keys! [Function]

Remove all keys from a table.

Synopsis

remove-all-keys! ( coll ) => ( coll )

Parameters

coll An instance of <mutable-explicit-key-collection> .

Return Values

coll An instance of <mutable-explicit-key-collection> .

Description

This function iterates through all the keys and calls remove-key! on each one.


sequence-hash [Function]

Like collection-hash , only a more efficient version just for sequences.

Synopsis

sequence-hash ( element-hash , seq , initial-state ) => ( id , state)

Parameters

element-hash An instance of <function> . Computes hash ids for the elements. It takes an object and a <hash-state> as an argument, and returns a hash id and a hash state.
seq An instance of <sequence> .
initial-state An instance of <hash-state> .

Return Values

id An instance of <integer> .
stateAn instance of <hash-state>.

Description

This is similar to an equal-hash, except that it hashes things with ordered: #t and ignores the sequence keys. USE WITH CAUTION: This isn't a proper equal-hash because two collections of different types but identical key/element pairs won't generate the same hash id, even though the two collections are \=.


string-hash [Function]

A convenient function for hashing strings

Synopsis

string-hash ( s , initial-state ) => ( id , state )

Parameters

s An instance of <string> .
initial-state An instance of <hash-state> .

Return Values

id An instance of <integer> .
state An instance of <hash-state> .

Description

A convenient method for hashing strings. Used by <string-table> .


value-hash [Generic]

Computes hash ids for objects such that two objects that are \= equal have the same hash id.

Synopsis

value-hash ( thing , state ) => ( id , state )

Parameters

thing An instance of <object> .
state An instance of <hash-state> .

Return Values

id An instance of <integer> .
state An instance of <hash-state> .

Description

Methods on equal-hash should return hash ids such that the id for two \= equal objects are the same.

There is a default method is defined on all instances of <object>, and it returns a valid hash id in all cases. However, performance *will* suck horribly (algorithmically, even) if you don't define better methods for your own objects that will live in <equal-table> instances.

Good methods for equal-hash are defined for <integer>, <float>, <symbol>, <type>, <function>, <boolean>, <condition>, and <collection>. (Note that <collection> is a supertype of <string>.)