.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" 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 "ici::doc::pod3::sdrhash 3" .TH ici::doc::pod3::sdrhash 3 "2016-07-07" "perl v5.24.1" "ICI library functions" .\" 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" sdrhash \- Simple Data Recorder hash table management functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include "sdr.h" \& \& Object sdr_hash_create (Sdr sdr, int keyLength, \& int estNbrOfEntries, \& int meanSearchLength); \& int sdr_hash_insert (Sdr sdr, Object hash, char *key, \& Address value, Object *entry); \& int sdr_hash_delete_entry (Sdr sdr, Object entry); \& int sdr_hash_entry_value (Sdr sdr, Object hash, Object entry); \& int sdr_hash_retrieve (Sdr sdr, Object hash, char *key, \& Address *value, Object *entry); \& int sdr_hash_count (Sdr sdr, Object hash); \& int sdr_hash_revise (Sdr sdr, Object hash, char *key, \& Address value); \& int sdr_hash_remove (Sdr sdr, Object hash, char *key, \& Address *value); \& int sdr_hash_destroy (Sdr sdr, Object hash); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \s-1SDR\s0 hash functions manage hash table objects in an \s-1SDR. \s0 .PP Hash tables associate values with keys. A value is always in the form of an \s-1SDR\s0 Address, nominally the address of some stored object identified by the associated key, but the actual significance of a value may be anything that fits into a \fIlong\fR. A key is always an array of from 1 to 255 bytes, which may have any semantics at all. .PP Keys must be unique; no two distinct entries in an \s-1SDR\s0 hash table may have the same key. Any attempt to insert a duplicate entry in an \s-1SDR\s0 hash table will be rejected. .PP All keys must be of the same length, and that length must be declared at the time the hash table is created. Invoking a hash table function with a key that is shorter than the declared length will have unpredictable results. .PP An \s-1SDR\s0 hash table is an array of linked lists. The location of a given value in the hash table is automatically determined by computing a \*(L"hash\*(R" of the key, dividing the hash by the number of linked lists in the array, using the remainder as an index to the corresponding linked list, and then sequentially searching through the list entries until the entry with the matching key is found. .PP The number of linked lists in the array is automatically computed at the time the hash table is created, based on the estimated maximum number of entries you expect to store in the table and the mean linked list length (i.e., mean search time) you prefer. Increasing the maximum number of entries in the table and decreasing the mean linked list length both tend to increase the amount of \s-1SDR\s0 heap space occupied by the hash table. .IP "Object sdr_hash_create(Sdr sdr, int keyLength, int estNbrOfEntries, int meanSearchLength)" 4 .IX Item "Object sdr_hash_create(Sdr sdr, int keyLength, int estNbrOfEntries, int meanSearchLength)" Creates an \s-1SDR\s0 hash table. Returns the \s-1SDR\s0 address of the new hash table on success, zero on any error. .IP "int sdr_hash_insert(Sdr sdr, Object hash, char *key, Address value, Object *entry)" 4 .IX Item "int sdr_hash_insert(Sdr sdr, Object hash, char *key, Address value, Object *entry)" Inserts an entry into the hash table identified by \fIhash\fR. On success, places the address of the new hash table entry in \fIentry\fR and returns zero. Returns \-1 on any error. .IP "int sdr_hash_delete_entry(Sdr sdr, Object entry)" 4 .IX Item "int sdr_hash_delete_entry(Sdr sdr, Object entry)" Deletes the hash table entry identified by \fIentry\fR. Returns zero on success, \-1 on any error. .IP "Address sdr_hash_entry_value(Sdr sdr, Object hash, Object entry)" 4 .IX Item "Address sdr_hash_entry_value(Sdr sdr, Object hash, Object entry)" Returns the value of the hash table entry identified by \fIentry\fR. .IP "int sdr_hash_retrieve(Sdr sdr, Object hash, char *key, Address *value, Object *entry)" 4 .IX Item "int sdr_hash_retrieve(Sdr sdr, Object hash, char *key, Address *value, Object *entry)" Searches for the value associated with \fIkey\fR in this hash table, storing it in \&\fIvalue\fR if found. If the entry matching \fIkey\fR was found, places the address of the hash table entry in \fIentry\fR and returns 1. Returns zero if no such entry exists, \-1 on any other failure. .IP "int sdr_hash_count(Sdr sdr, Object hash)" 4 .IX Item "int sdr_hash_count(Sdr sdr, Object hash)" Returns the number of entries in the hash table identified by \fIhash\fR. .IP "int sdr_hash_revise(Sdr sdr, Object hash, char *key, Address value)" 4 .IX Item "int sdr_hash_revise(Sdr sdr, Object hash, char *key, Address value)" Searches for the hash table entry matching \fIkey\fR in this hash table, replacing the associated value with \fIvalue\fR if found. Returns 1 if the entry matching \fIkey\fR was found, zero if no such entry exists, \-1 on any other failure. .IP "int sdr_hash_remove(Sdr sdr, Object hash, char *key, Address *value)" 4 .IX Item "int sdr_hash_remove(Sdr sdr, Object hash, char *key, Address *value)" Searches for the hash table entry matching \fIkey\fR in this hash table; if the entry is found, stores its value in \fIvalue\fR, deletes the entry, and returns 1. Returns zero if no such entry exists, \-1 on any other failure. .IP "void sdr_hash_destroy(Sdr sdr, Object hash);" 4 .IX Item "void sdr_hash_destroy(Sdr sdr, Object hash);" Destroys \fIhash\fR, destroying all entries in all linked lists of the array and destroying the hash table array structure itself. \s-1DO NOT\s0 use \fIsdr_free()\fR to destroy a hash table, as this would leave the hash table's content allocated yet unreferenced. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIsdr\fR\|(3), \fIsdrlist\fR\|(3), \fIsdrtable\fR\|(3)