Skip to content

Latest commit

 

History

History
145 lines (118 loc) · 3.98 KB

README.md

File metadata and controls

145 lines (118 loc) · 3.98 KB

cl-dawg

  • A map implementation based on DAWG (Directed Acyclic Word Graph)
    • Maps are serialized to sequences of bytes using double array trie format
  • This takes static key set, and assigns the unique identifiers for the each keys
    • Note that the input keys must be unique and lexically ordered
    • The identifier assigned to a key is the zero-origin index of the key in the input sequence
  • This library aims to provide a handy way for building maps which have tens of millions of elements in Common Lisp

Build

(require :asdf)
(push *default-pathname-defaults* asdf:*central-registry*)
(asdf:load-system :dawg)

Example

(dawg:build :input "/usr/share/dict/words" :output "words.dawg")
(defparameter *dawg* (dawg:load "words.dawg"))

(dawg:member? "hello" *dawg*)
T

(dawg:get-id "hello" *dawg*)
50195

(dawg:each-common-prefix (id end) ("hello" *dawg*)
  (print (list id (subseq "hello" 0 end))))
(49012 "h")
(49845 "he")
(50183 "hell")
(50195 "hello")

API

dawg:build (&key input output byte-order show-progress) => t

Builds a DAWG index file from the input key set.

  • input:
    • The pathname of a key set file or a list of keys
      • "key set file" is line delimitered plain text file (a line represents a key)
    • Restrictions:
      • The input keys must be unique and lexically ordered
      • A key cannot contain null characters
    • Type: (or string pathname list)
  • output:
    • The pathname of the resulting DAWG index file
    • Type: (or string pathname)
  • byte-order:
    • The endianness of the output file
    • Type: (member :native :little :big)
    • Default: :native
  • show-progress:
    • Indicates whether or not to show the progress
    • Type: boolean
    • Default: nil

dawg:load (index-path &key byte-order) => dawg:dawg

Loads the DAWG map from the specified index file.

  • index-path:
    • The pathname of an index file that built via dawg:build function
    • Type: (or string pathname file-stream)
  • byte-order:
    • The endianness of the input file
    • Type: (member :native :little :big)
    • Default: :native

dawg:member? (key dawg &key start end) => boolean

Returns t if dawg contains the given key, otherwise nil.

  • key:
    • Type: (simple-array character)
  • dawg:
    • Type: dawg:dawg
  • start:
    • The start position in key
    • Type: positive-fixnum
    • Default: 0
  • end:
    • The end position in key
    • Type: positive-fixnum
    • Default: (length key)

dawg:get-id (key dawg &key start end) => (or null fixnum)

Returns the identifier assigned to the given key. If the key does not exist in dawg, this function will return nil.

  • key:
    • Type: (simple-array character)
  • dawg:
    • Type: dawg:dawg
  • start:
    • The start position in key
    • Type: positive-fixnum
    • Default: 0
  • end:
    • The end position in key
    • Type: positive-fixnum
    • Default: (length key)  

dawg:each-common-prefix ((match-id match-end) (key dawg &key start end) &body body)

Executes common-prefix search for the given key.

For each key in dawg that matches the prefix part of key, match-id and match-end are bound then body is exeucted.

By using the return function, it is possible to break the loop halfway.

  • match-id:
    • The identifier of the key matched with the prefix part of the input key
    • Type: positive-fixnum
  • match-end:
    • The end position of the matched part in the input key (i.e., the length of the matched key)
    • Type: positive-fixnum
  • key:
    • Type: (simple-array character)
  • dawg:
    • Type: dawg:dawg
  • start:
    • The start position in key
    • Type: positive-fixnum
    • Default: 0
  • end:
    • The end position in key
    • Type: positive-fixnum
    • Default: (length key)
  • body:
    • The expression to be executed in each iteration

dawg:each-predictive ((match-id) (key dawg &key start end) &body body)

A simplified version of dawg:each-common-prefix that does not bind the match-end variable in each iteration.