Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-custom-hash-table Reference Manual, version 0.3, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:39:54 2021 GMT+0.
• Introduction | What cl-custom-hash-table is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
CL-CUSTOM-HASH-TABLE allows creation and use of "custom hash tables". Custom hash tables can use arbitrary TEST/HASH functions, in addition to the TEST functions allowed by the standard (EQ, EQL, EQUAL and EQUALP).
This library is primarily a compatibility layer, unifying how to create these hash table in different Lisp implementations. Furthermore this library provides a simple yet fully functional fall-back solution for implementations that don't support this functionality natively (yet).
CL-CUSTOM-HASH-TABLE is released under a BSD-like license, see the ASD file.
This library does not shadow symbols in the COMMON-LISP package. It does require that all access to (potential) custom hash tables is lexical wrapped in a WITH-CUSTOM-HASH-TABLE form (see example below).
The standard hash table related functions are supported:
Hash table iteration using LOOP (using HASH-KEY or HASH-VALUE) is not supported in Lisp implementations where the fall-back solution is used, therefore cannot be used in core that is supposed to be portable.
In the fall-back solution HASH-TABLE-COUNT returns the correct number of entries, but HASH-TABLE-SIZE returns the size of the underlying helper hash table which might be lower than HASH-TABLE-COUNT. Functions HASH-TABLE-REHASH-SIZE and HASH-TABLE-REHASH-THRESHOLD also refer to that helper hash table.
The fall-back solution is not thread-safe. The native implementation may or may not be.
See the build status on Travis-CI, and the coverage status on Coveralls:
| Common Lisp Implementation | Native | Fallback |
|:-:|:-:|:-:|
| ABCL | n/a | |
| Allegro CL |
|
|
| Clozure CL |
|
|
| CLISP | n/a |
|
| CMUCL | ? | ? |
| ECL | n/a |
|
| LispWorks | ? | ? |
| SBCL |
|
|
Custom TEST and HASH functions:
(defun foo-equal-p (x y) (= x y))
(defun foo-hash (x) (mod x 10))
Define the hash table type:
(use-package :cl-custom-hash-table)
(define-custom-hash-table-constructor make-foo-ht
:test foo-equal-p :hash-function foo-hash)
Now MAKE-FOO-HT is a function that will create the custom hash table:
(defparameter *foo-ht* (make-foo-ht)
"Hash table using FOO-HASH and FOO-EQUAL-P")
You can trace your test/hash functions to check they are really getting called later:
(trace foo-equal-p foo-hash)
Use WITH-CUSTOM-HASH-TABLE around access to the hash table. This ensures functions GETHASH, REMHASH and MAPHASH do the right thing. If you forget this, your code will not work in implementations that don't support custom TEST/HASH functions natively!
(with-custom-hash-table
(setf (gethash 1 *foo-ht*) 1
(gethash 10 *foo-ht*) 10
(gethash 2 *foo-ht*) 2)
(maphash (lambda (k v)
(format t "~A: ~A~%" k v)
(remhash k *foo-ht*))
*foo-ht*))
Several Lisp implementations already support custom TEST and HASH arguments for MAKE-HASH-TABLE. This library is a small wrapper around the vendor-specific extensions. (Allegro CL, CCL, CMUCL, LispWorks, SBCL)
In other Lisp implementations (ABCL, CLISP, ECL) a fall-back solution is used:
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The cl-custom-hash-table system |
Willem Broekema
Copyright (c) 2010-2014, Willem Broekema All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This library allows creation of hash tables with arbitrary TEST/HASH functions,
in addition to the TEST functions allowed by the standard (EQ, EQL, EQUAL and EQUALP),
even in implementations that don’t support this functionality directly.
0.3
cl-custom-hash-table.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
• The cl-custom-hash-table.asd file | ||
• The cl-custom-hash-table/package.lisp file | ||
• The cl-custom-hash-table/custom-hash-table.lisp file |
Next: The cl-custom-hash-table/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-custom-hash-table.asd
cl-custom-hash-table (system)
Next: The cl-custom-hash-table/custom-hash-table․lisp file, Previous: The cl-custom-hash-table․asd file, Up: Lisp files [Contents][Index]
cl-custom-hash-table (system)
package.lisp
Previous: The cl-custom-hash-table/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
cl-custom-hash-table (system)
custom-hash-table.lisp
checking-reader-conditionals (macro)
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The cl-custom-hash-table package |
package.lisp (file)
common-lisp
checking-reader-conditionals (macro)
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported macros |
Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Generate a function that can be used to create a new hash table that uses the given TEST and HASH-FUNCTION.
For example: (DEFINE-CUSTOM-HASH-TABLE-CONSTRUCTOR MAKE-FOO-HT :TEST FOO-EQUAL-P :HASH-FUNCTION FOO-HASH)
defines function (MAKE-FOO-HT &REST OPTIONS).
OPTIONS are passed on to MAKE-HASH-TABLE if the platform supports custom hash tables natively, and ignored otherwise.
custom-hash-table.lisp (file)
Wrap BODY in an environment where access to custom hash-tables (GET-HASH etc) works as expected.
This macro is a no-op in Lisp implementations that support custom hash-tables natively, but it is
required in implementations where the fallback solution is used (*FEATURES* value :CUSTOM-HASH-TABLE-FALLBACK)
custom-hash-table.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal macros |
Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Break unless the body contains exactly one form. Inspired by code from Steve Haflich.
custom-hash-table.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | C F L |
---|
Jump to: | C F L |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | C D M W |
---|
Jump to: | C D M W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C P S |
---|
Jump to: | C P S |
---|