1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
------------------------------------------------------------------------------
-- --
-- GNAT COMPILER COMPONENTS --
-- --
-- G N A T . P E R F E C T _ H A S H _ G E N E R A T O R S --
-- --
-- S p e c --
-- --
-- Copyright (C) 2002-2023, AdaCore --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
-- ware Foundation; either version 3, or (at your option) any later ver- --
-- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE. --
-- --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception, --
-- version 3.1, as published by the Free Software Foundation. --
-- --
-- You should have received a copy of the GNU General Public License and --
-- a copy of the GCC Runtime Library Exception along with this program; --
-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
-- <http://www.gnu.org/licenses/>. --
-- --
-- GNAT was originally developed by the GNAT team at New York University. --
-- Extensive contributions were provided by Ada Core Technologies Inc. --
-- --
------------------------------------------------------------------------------
-- This package provides a generator of static minimal perfect hash functions.
-- To understand what a perfect hash function is, we define several notions.
-- These definitions are inspired from the following paper:
-- Zbigniew J. Czech, George Havas, and Bohdan S. Majewski ``An Optimal
-- Algorithm for Generating Minimal Perfect Hash Functions'', Information
-- Processing Letters, 43(1992) pp.257-264, Oct.1992
-- Let W be a set of m words. A hash function h is a function that maps the
-- set of words W into some given interval I of integers [0, k-1], where k is
-- an integer, usually k >= m. h (w) where w is a word in W computes an
-- address or an integer from I for the storage or the retrieval of that
-- item. The storage area used to store items is known as a hash table. Words
-- for which the same address is computed are called synonyms. Due to the
-- existence of synonyms a situation called collision may arise in which two
-- items w1 and w2 have the same address. Several schemes for resolving
-- collisions are known. A perfect hash function is an injection from the word
-- set W to the integer interval I with k >= m. If k = m, then h is a minimal
-- perfect hash function. A hash function is order preserving if it puts
-- entries into the hash table in a prespecified order.
-- A minimal perfect hash function is defined by two properties:
-- Since no collisions occur each item can be retrieved from the table in
-- *one* probe. This represents the "perfect" property.
-- The hash table size corresponds to the exact size of W and *no larger*.
-- This represents the "minimal" property.
-- The functions generated by this package require the words to be known in
-- advance (they are "static" hash functions). The hash functions are also
-- order preserving. If w2 is inserted after w1 in the generator, then h (w1)
-- < h (w2). These hashing functions are convenient for use with realtime
-- applications.
with System.Perfect_Hash_Generators;
package GNAT.Perfect_Hash_Generators is
package SPHG renames System.Perfect_Hash_Generators;
Default_K_To_V : constant Float := 2.05;
-- Default ratio for the algorithm. When K is the number of keys, V =
-- (K_To_V) * K is the size of the main table of the hash function. To
-- converge, the algorithm requires K_To_V to be strictly greater than 2.0.
Default_Pkg_Name : constant String := "Perfect_Hash";
-- Default package name in which the hash function is defined
Default_Position : constant String := "";
-- The generator allows selection of the character positions used in the
-- hash function. By default, all positions are selected.
Default_Tries : constant Positive := 20;
-- This algorithm may not succeed to find a possible mapping on the first
-- try and may have to iterate a number of times. This constant bounds the
-- number of tries.
type Optimization is new SPHG.Optimization;
-- Optimize either the memory space or the execution time. Note: in
-- practice, the optimization mode has little effect on speed. The tables
-- are somewhat smaller with Memory_Space.
Verbose : Boolean renames SPHG.Verbose;
-- Output the status of the algorithm. For instance, the tables, the random
-- graph (edges, vertices) and selected char positions are output between
-- two iterations.
procedure Initialize
(Seed : Natural;
K_To_V : Float := Default_K_To_V;
Optim : Optimization := Memory_Space;
Tries : Positive := Default_Tries);
-- Initialize the generator and its internal structures. Set the ratio of
-- vertices over keys in the random graphs. This value has to be greater
-- than 2.0 in order for the algorithm to succeed. The word set is not
-- modified (in particular when it is already set). For instance, it is
-- possible to run several times the generator with different settings on
-- the same words.
--
-- A classical way of doing is to Insert all the words and then to invoke
-- Initialize and Compute. If this fails to find a perfect hash function,
-- invoke Initialize again with other configuration parameters (probably
-- with a greater K_To_V ratio). Once successful, invoke Produce and then
-- Finalize.
procedure Finalize;
-- Deallocate the internal structures and the words table
procedure Insert (Value : String);
-- Insert a new word into the table. ASCII.NUL characters are not allowed.
Too_Many_Tries : exception renames SPHG.Too_Many_Tries;
-- Raised after Tries unsuccessful runs
procedure Compute (Position : String := Default_Position);
-- Compute the hash function. Position allows the definition of selection
-- of character positions used in the word hash function. Positions can be
-- separated by commas and ranges like x-y may be used. Character '$'
-- represents the final character of a word. With an empty position, the
-- generator automatically produces positions to reduce the memory usage.
-- Raise Too_Many_Tries if the algorithm does not succeed within Tries
-- attempts (see Initialize).
procedure Produce
(Pkg_Name : String := Default_Pkg_Name;
Use_Stdout : Boolean := False);
-- Generate the hash function package Pkg_Name. This package includes the
-- minimal perfect Hash function. The output is normally placed in the
-- current directory, in files X.ads and X.adb, where X is the standard
-- GNAT file name for a package named Pkg_Name. If Use_Stdout is True, the
-- output goes to standard output, and no files are written.
end GNAT.Perfect_Hash_Generators;
|
