Revision as of 12:30, 8 November 2015

Template:mIRC Guide

A hash table is an associative array with key-value pairing. That is, a value stored in the table is associated with a specific key. Logically speaking, a basic table would like something like this:

mIRC provides facilities for manipulating the table and the values in variety of ways.

General Details

Hash tables, unlike INI files, are stored completely in memory and are never written to disk, making them much faster when it comes to storing and retrieving information. The performance gain is much more obvious with a large amount of keyval pairs.

Note: Because hash tables are only in memory, it must be saved to a file if mIRC has to exit for any reason. You can reload the table from a file at a later period.

Creating a table

A hash table must be created before you can work with it. This also applies to loading a hash table from a file. To create a table you need to use the /hmake command. The syntax is:

hmake <table_name>
hmake <table_name> <buckets>
;hmake also have an -s switch which prints debug info

If you don't specify the number of buckets, the default is used which is 100. Generally speaking the number of buckets should be decided based on the following equation:

For example: a table with 100 buckets is optimal for 78 items. For 1000 items, 1300 buckets is best.

Adding Items

The /hadd command is used to add a keyval pair to the table. The syntax is:

hadd <table_name> <key> <value>
hadd -b <table_name> <key> <&bvar>

Let's consider a table of favorite colors:

/hadd -ms colors John Blue
/hadd -s colors Mary Green
/hadd -s colors Gary Orange

The code above will produce the following result:

* Made hash table 'colors' (100)
* Added item 'John' to hash table 'colors'
* Added item 'Mary' to hash table 'colors'
* Added item 'Gary' to hash table 'colors'

Deleting Items

To delete pairs from the table, you need to use the /hdel command. It's syntax is:

hdel <table_name> <key>
hdel -w <table_name> <wild_key>
;hdel has a -s switch which is the same as /hmake's

A wildcard pattern for the key can be specified to delete multiple keys at once. If we go back to our example:

/hdel colors Mary

Will leave our table looking like this:

Value retrieval

To get a value associated with a given key we will use the $hget identifier which has the following syntax:

$hget(<table_name>, <key>)

For example, if we were to check what is John's favorite color from our table; we will use the following piece of code:

//echo -a $hget(colors, John)
;Blue

The $hget identifier can also be used to check if a table exists using the following syntax:

$hget(<table_name>)
; returns $null if the table does not exist

Saving/Loading Hash Table to/from file

Because a hash table is stored exclusively in memory, it is important to save it to a file if one wishes to keep its content after a reboot or shut down. If a hash table is not stored in a file before mIRC closes, it will be gone for good.

mIRC offers the /hsave and /hload commands to handle the saving and loading of hash tables from your hard disk.

The syntax for the /hsave command is:

/hsave <table_name> <filename>
; The -o switch will override existing file
; The -a switch will append to an existing file
; The -i switch will create an ini file
; The -b switch will treat the file as a binary file,
; making it possible to save things like carriage returns
; and line feeds.

If we wanted to save our little colors table to an INI file, we could use the following piece of code.:

/hsave -i Colors colors.ini
;colors.ini will have:
;  [hashtable]
;  Gary=Orange
;  John=Blue

To load a hash table we use the following syntax:

; NOTE: The table must exists. I.e. you must have called /hmake first
/hload <table_name> <filename>
; The -i switch will create an ini file
; The -b switch will treat the file as a binary file,
;        making it possible to save things like carriage returns and line feeds.

To load the table we've just saved we would use the following code:

/hload -i Colors colors.ini

Deleting a Table

To complete destroy a table and all its values, you can use the hfree command:

/hfree <table_name>
/hfree -w <*wild*table*>
;hfree has a -s switch which is the same as /hmake's

With the -w switch you can specify a wildcard pattern. All matching tables will be freed.

Iterating Over a Hash Table

The $hget identifier can be used to iterate over the hash table. The syntax is:

; Total Number of items in the table:
$hget(<table_name>, 0)
; Get the Nth Key
$hget(<table_name>, <Nth>).item
; Get the value associated with the Nth key
$hget(<table_name>, <Nth>).data

Note: Iterating over a hash table like this is an inefficient way to retrieve values and keys. It's best to get a value using its key.

An example of looping over every value in our Colors table will look like this:

Alias print_fav_colors {
  var %i = 1
  echo Colors Table:
  ; iterate over each item
  while ($hget(Colors, %i).item) {
    ; print the key/value pair
    echo -a %i $+ ) $v1 => $hget(Colors, $v1)
    inc %i
  }
}

The execution of the alias (/print_fav_colors) will produce the following result:

Colors Table:
1) Gary => Orange
2) John => Blue

Searching for a key and value pair

The $find identifier can be used to search the table for a particular pair.

; The Nth key that matches the wildcard pattern
$hfind(<table_name>, <pattern>, <Nth>, w)
; The Nth key that matches the RegExp pattern
$hfind(<table_name>, <pattern>, <Nth>, r)
; $find(...).data will search the data instead of the key.

If you specify 0 for Nth key, the total number of matches will be returned instead. An example from our Colors table would be:

//echo -a $hfind(Colors, *ary*, 1, w)

Which will return "Gary".