MIRC Scripting/BeyondBasics/Hash Tables

From Wikibooks, open books for an open world
Jump to navigation Jump to search

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'll 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 -smbczuN <name> <item> [data | &binvar] Adds an item to an existing hash table.

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

The -m switch makes /hadd create the hash table if it doesn't already exist.

The -uN switch unsets the item after N seconds.

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

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

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 -sbni <name> <filename> [section] /hsave -sbnioau <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 -b switch loads or saves binary files. $cr and $lf are preserved when saving as binary files.

You can use -n to load or save files as data only, with no items. When loading with -n each line of data is assigned an N item value, starting at N = 1.

/hsave also supports -o to overwite an existing file, and -a to append to an existing file.

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: /hload does not create the table, it must already have been created by /hmake.

$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) 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 isn't 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