.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "TRIEHASH 1" .TH TRIEHASH 1 "2020-03-08" "triehash v0.3" "triehash" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" triehash \- Generate a perfect hash function derived from a trie. .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBtriehash\fR [\fIoption\fR] [\fIinput\ file\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" triehash takes a list of words in input file and generates a function and an enumeration to describe the word .SH "INPUT FILE FORMAT" .IX Header "INPUT FILE FORMAT" The file consists of multiple lines of the form: .PP .Vb 1 \& [label ~ ] word [= value] .Ve .PP This maps word to value, and generates an enumeration with entries of the form: .PP .Vb 1 \& label = value .Ve .PP If \fIlabel\fR is undefined, the word will be used, the minus character will be replaced by an underscore. If value is undefined it is counted upwards from the last value. .PP There may also be one line of the format .PP .Vb 1 \& [ label ~] = value .Ve .PP Which defines the value to be used for non-existing keys. Note that this also changes default value for other keys, as for normal entries. So if you place .PP .Vb 1 \& = 0 .Ve .PP at the beginning of the file, unknown strings map to 0, and the other strings map to values starting with 1. If label is not specified, the default is \&\fIUnknown\fR. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-C\fR\fI.c file\fR \fB\-\-code\fR=\fI.c file\fR" 4 .IX Item "-C.c file --code=.c file" Generate code in the given file. .IP "\fB\-H\fR\fIheader file\fR \fB\-\-header\fR=\fIheader file\fR" 4 .IX Item "-Hheader file --header=header file" Generate a header in the given file, containing a declaration of the hash function and an enumeration. .IP "\fB\-\-enum\-name=\fR\fIword\fR" 4 .IX Item "--enum-name=word" The name of the enumeration. .IP "\fB\-\-function\-name=\fR\fIword\fR" 4 .IX Item "--function-name=word" The name of the function. .IP "\fB\-\-label\-prefix=\fR\fIword\fR" 4 .IX Item "--label-prefix=word" The prefix to use for labels. .IP "\fB\-\-label\-uppercase\fR" 4 .IX Item "--label-uppercase" Uppercase label names when normalizing them. .IP "\fB\-\-namespace=\fR\fIname\fR" 4 .IX Item "--namespace=name" Put the function and enum into a namespace (\*(C+) .IP "\fB\-\-class=\fR\fIname\fR" 4 .IX Item "--class=name" Put the function and enum into a class (\*(C+) .IP "\fB\-\-enum\-class\fR" 4 .IX Item "--enum-class" Generate an enum class instead of an enum (\*(C+) .IP "\fB\-\-counter\-name=\fR\fIname\fR" 4 .IX Item "--counter-name=name" Use \fIname\fR for a counter that is set to the latest entry in the enumeration + 1. This can be useful for defining array sizes. .IP "\fB\-\-ignore\-case\fR" 4 .IX Item "--ignore-case" Ignore case for words. .IP "\fB\-\-multi\-byte\fR=\fIvalue\fR" 4 .IX Item "--multi-byte=value" Generate code reading multiple bytes at once. The value is a string of power of twos to enable. The default value is 320 meaning that 8, 4, and single byte reads are enabled. Specify 0 to disable multi-byte completely, or add 2 if you also want to allow 2\-byte reads. 2\-byte reads are disabled by default because they negatively affect performance on older Intel architectures. .Sp This generates code for both multiple bytes and single byte reads, but only enables the multiple byte reads of \s-1GNU C\s0 compatible compilers, as the following extensions are used: .RS 4 .IP "Byte-aligned integers" 8 .IX Item "Byte-aligned integers" We must be able to generate integers that are aligned to a single byte using: .Sp .Vb 1 \& typedef uint64_t _\|_attribute_\|_((aligned (1))) triehash_uu64; .Ve .IP "Byte-order" 8 .IX Item "Byte-order" The macros _\|_BYTE_ORDER_\|_ and _\|_ORDER_LITTLE_ENDIAN_\|_ must be defined. .RE .RS 4 .Sp We forcefully disable multi-byte reads on platforms where the variable \&\fI_\|_ARM_ARCH\fR is defined and \fI_\|_ARM_FEATURE_UNALIGNED\fR is not defined, as there is a measurable overhead from emulating the unaligned reads on \&\s-1ARM.\s0 .RE .IP "\fB\-\-language=\fR\fIlanguage\fR" 4 .IX Item "--language=language" Generate a file in the specified language. Currently known are 'C' and 'tree', the latter generating a tree. .IP "\fB\-\-include=\fR\fIheader\fR" 4 .IX Item "--include=header" Add the header to the include statements of the header file. The value must be surrounded by quotes or angle brackets for C code. May be specified multiple times. .SH "LICENSE" .IX Header "LICENSE" triehash is available under the MIT/Expat license, see the source code for more information. .SH "AUTHOR" .IX Header "AUTHOR" Julian Andres Klode