Hash Tables

Hash tables allow you to efficiently store large amounts of information which can be quickly referenced and retrieved later on.

A hash table can be created, freed, referenced, or modified using the following commands and identifiers.

/hmake -s <name> <N>

Creates a new hash table with N slots.

A hash table can store an unlimited number of items regardless of the N you choose, however the bigger N is, the faster it will work, depending on the number of items stored eg. if you expect that you will be storing 1000 items in the table, a table of N set to 100 is quite sufficient.

The -s switch makes the command display the result.

/hfree -sw <name>

Frees an existing hash table.

The -w switch indicates that name is a wildcard, all matching tables are freed.

/hadd -smNbczkuN <name> <item> [text | &binvar]

Adds an item to an existing hash table.

If the item you are adding already exists, the old item is replaced.

The -mN switch creates the hash table if it does not already exist, where N is the number of slots.

The -uN switch unsets the item after N seconds.

The -k switch keeps the current -uN setting for an item.

The -b indicates that you are adding a &binvar item to the hash table.

The -c switch treats the &binvar as text and chops it at the first null value.

The -z switch decreases hash item once per second until it reaches zero and then unsets it.

The /hinc and /hdec commands use the same parameters as /hadd and increase or decrease the number value of an item.

When used with /hinc or /hdec, the -c switch increases or decreases the value once per second.

/hdel -sw <name> <item>

Deletes an item from a hash table.

The -w switch indicates that item is a wildcard, all matching items are freed.

/hload -smNbBni <name> <filename> [section]

/hsave -sbniau <name> <filename> [section]

Load or save a table to/from a file.

These load/save plain text to a text file, with item and data on separate lines. $cr and $lf characters are stripped from text when saving as plain text.

The -mN switch creates the hash table when loading if it does not already exist, where N is the number of slots.

The -b switch loads or saves binary files. This uses an index that allows item values up to 65535 in length.

The -B switch loads or saves binary files. This uses an index that allows item values up to 4294967295 in length. This is not compatible with files created by the -b switch.

Note: $cr and $lf are preserved when saving tables as binary files.

The -n switch loads or saves files as data only, with no items. When loading, each line of data is assigned an N item value, starting at N = 1.

/hsave also supports -a to append to an existing file instead of overwriting it.

By default /hsave excludes items that are in the /hadd -uN unset list, the -u switch forces it to include the unset items.

The -i switch treats the file as an ini file. You can specify an optional section name after the filename.

Note: Due to how hash tables work, items are stored in hash tables in a random order. You should not depend on items being stored, saved, or loaded in any particular order.

$hget(name/N)

Returns name of a hash table if it exists, or returns the name of the Nth hash table.

Properties: size

$hget(moo).size   returns the N size of table, as specified in /hmake

$hget(name/N, item)

Returns the data associated with an item in the specified hash table.

Properties: unset

The unset property returns the time remaining before an item is unset.

$hget(name/N, item, &binvar)

Assigns the contents of an item to a &binvar.

$hget(name/N, N).item

This allows you to reference the table as an index from 0 to N, in order to look up the Nth item in the table.

If N is zero, returns the total number of items in the table.

You can also reference the Nth data value directly with $hget().data.

Note: This method is provided as a convenience, it is not an efficient way to use the hash table.

$hfind(name/N, text, N, M, @window | command)

Searches table for the Nth item name which matches text. Returns item name.

Properties: data

If you specify the .data property, searches for a matching data value.

M is optional, and can be:

 n        normal text comparison (default if M is not specified)

 w        text is wildcard text

 W        hash table item/data is wildcard text

 r        text is regular expression

 R        hash table item/data is regular expression

If you specify a custom @window name (with a listbox), the custom @window listbox will be filled with the results.

If you specify a command, it will be performed on every item that is found. You can use $1- to refer to the item, eg. //echo 1 result: $hfind(name, *, 0, w, echo $1-)

If you use /halt in the command/alias, this halts the search.

Note: In the case of 'r' regular expression searching through a binary variable, long results will be truncated.