I thought that the Records section would've been helpful in figuring out multidimensional maps -- maybe not; Veracity might've gone a bit too far with that example (which I understand, as she was trying to cover all her bases with one single unifying example). --[[User:Heeheehee|Heeheehee]] 06:42, 10 March 2010 (UTC)

==An attempt at explaining maps==

A map consists of two types of component.
* The key
* The value
A normal map (without using a record) can have multiple keys, but only one value. A map is formed by specifying a normal datatype for the value and including a key, then giving the map a name:

<pre>datatype [key] name;</pre>

Eg.
<pre>string [int] message;</pre>

This in itself is a useful feature, but there are many situations where you may wish to associate two values. For example, in the message map above, I may wish to specify both a message and a name to send it to. There are two ways I could deal with this problem. The first would be to create a second map with a corresponding key. I could then assume that message[key] should be send to recipient[key]. While this works, it is inefficient and untidy, as well as inflexible.

Mafia supports the ability to customise maps using record. Record tells mafia what each entry in a map means, thereby enabling us to have more than one value to the map. The best way to visualise maps is to see a row on a page:

<pre>key value</pre>

We can extend our keys already by specifying multiples:

<pre>value [key1 , key2] name;</pre>

Produces:

<pre>key1 key2 value</pre>

What record lets us do is add more values:

<pre>key value1 value2</pre>

Each line in a record is the next value and has to include the datatype of that value. Before we specified the value's datatype when we named the map (since there was only one value to assign a datatype to). Now we have to make a record of ALL the datatypes that will come up, and then when we make our map we will use the record name in place of a single datatype:

<pre>record kmailer{
string message;
string recipient;
}
kmailer [int] my_messages;</pre>

The example above creates the following map:

<pre>key value1 value2
int message recipient</pre>

So far, so simple. The next bit is where it gets interesting. We can no longer assign a value to the map as a whole. Without a record, we can do the following:

<pre>string [int] message;
message[1] = "Hi there!";</pre>

This makes the string "Hi there!" our value for key = 1:

<pre>key value
1 Hi there!</pre>

With a record, we can no longer assign a value to a key alone; we have more than one value and we need to specify which one it is we want to assign something to. So using the record above, to assign a message we would have to do the following:

<pre>record kmailer{
string message;
string recipient;
}
kmailer [int] my_messages;
my_messages[1].message = "Hi there!";
my_messages[1].recipient = "Grotfang";</pre>

Both values are assigned to our "1" key, but we must specify the value we are assigning. The following details what is going on in the map:

<pre>key value1 value2
int message recipient
1 Hi there! Grotfang</pre>

===Multiple Keys===

This is more complex. Maps with single keys are easy to understand how they will return - specify the map and key and you return the value (you need to specify which value you want if you use a record, but the principle is the same).

More than one key is where maps get truly interesting. To all extents and purposes, multiple keys tend to be a way to categorise data into groups and subgroups. The return values get more complicated, though.

Whenever you add a value to a map, all keys MUST be specified. However, when you are retrieving data this is not the case. This works best with an example:

<pre>string [string , string] my_map;
my_map["a","b"] = "ab";
print(my_map["a","b"]);</pre>

This returns:

<pre>ab</pre>

As you might expect. Here we specified a map with two keys and one value. We assigned a value "ab" to the combination of key1 ("a") and key2 ("b"). When we retrieved the value for that combination, we got "ab". So far, so unsurprising.

However, the natural question arises, what if we try to retrieve a value while only specifying one of the keys? The answer is that we need to change our perspective of the map to what I suggested earlier - that of groups and sub-groups.

The way I visualise this is to imaging key1 represents a group and key2 is a subgroup. If two map entries have the same key1, then you should perceive them as having some commonality. What happens when you retrieve using key1 only is that you return a map of all the map entries that have the specified value of key1. This means (as you are returning an aggregate) you need to specify a new map for the values to be placed in. The following example illustrates this:

<pre>string [string , string] my_map;
my_map["a","b"] = "ab";
my_map["b","c"] = "bc";
my_map["b","d"] = "bd";
my_map["c","d"] = "cd";
my_map["e","f"] = "ef";

string [string] my_map2 = my_map["b"];

foreach x in my_map2 {
print( my_map2[x] );
}</pre>

The output is:

<pre>bc
bd</pre>

As you can see, my_map["a","b"], which has "b" as key2 is NOT included in the aggregate return. This is where the concept of dimensions comes from. The more keys, the more level of control you have, but you cannot return (I don't think) a map of key1 that shares key2. It's a one-way structure. Of course, you could work around this with a new map that had the keys in reverse.

Talk:Data Structures

2010-03-11T16:41:44Z

2010-03-10T23:47:30Z

Grotfang:

{{
#vardefine:name|disable}}{{
#vardefine:return_type|void}}{{

FunctionPage|

name={{#var:name}}|
function_category=Miscellaneous|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|func}}|
p1desc={{pspan|func}} is the name of the function you wish to disable.
}}|

function_description=This function allows you to disable commands and/or functions by name. String {{pspan|func}} specifies the name of a CLI command or ASH function that you do not wish to be carried out. Note these include custom ASH functions (that you name yourself), but not aliases.
Mafia has an internal array of function names which are disabled. At the start of each session, this array starts empty. Disable adds names to this array and mafia will not allow functions to be called that are named after any on the disabled list (with the exception of disable and enable). This is useful for debugging scripts, as you can quickly disable functions from the top of a script without digging through the code. In addition, when a disabled function is called, mafia will print a line informing you of this fact, while not acting on it.Important considerations:
<ol>
<li>Mafia cannot differentiate between scripts that call functions of the same name. If function "foo" is disabled from script one, it will still be disabled when you run script two, unless you enable "foo" or restart mafia.</li>
<li>Remember that CLI commands will be disabled if they have the same name (or can be disabled deliberately with this function).</li>
<li>If a disabled function is incorporated into a condition (eg. "if(disabled_function())" ), then mafia will not just skip the entire conditional. If an else statement is present, the condition is treated as false and the else code will be performed.</li>
<li>Using "all" as the string parameter will disable all ASH functions including enable. This will require a restart of KoLmafia to resolve, so use with care. It also disables the usual logout function, so will require exiting mafia by clicking "X".</li>
<li>Despite "all" working in the manner specified above, disable() and enable() cannot be disabled using disable() when specified individually. The only way to disable enable() is to use "disable("all")".</li>
</ol>|

code1={{CodeSample|
title=Code Samples|
description=This mini scriptlet generates a map that is outputted to a data file. In testing you might not want to do this every time, so you can disable map_to_file().|
code=
<syntaxhighlight>
disable("map_to_file");
</syntaxhighlight>
}}|

see_also={{SeeAlso|enable}}|
}}

2010-03-10T15:12:44Z

Grotfang:

Disable

2010-03-10T15:07:00Z

Grotfang: Create page

Wait

2010-03-10T14:56:56Z

Grotfang:

{{
#vardefine:name|wait}}{{
#vardefine:return_type|void}}{{

FunctionPage|

name={{#var:name}}|
function_category=Miscellaneous|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|int|secs}}|
p1desc={{pspan|secs}} is the number of seconds you want to count down from.
}}|

function_description=This function will initiate a countdown from {{pspan|secs}} seconds to 0, during which time nothing else will be acted on. It essentially pauses a script. In addition, a countdown prints to the CLI at varying intervals (every 15 secs for large numbers, 5 seconds for smaller numbers and every second from 5 seconds down).|

needscode=yes|

cli_equiv="wait" can also be used from the CLI. It has the same meaning and can be used to pause basic .txt scripts.|
}}

Wait

2010-03-10T14:53:09Z

Grotfang:

{{
#vardefine:name|wait}}{{
#vardefine:return_type|void}}{{

FunctionPage|

name={{#var:name}}|
function_category=Miscellaneous|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|int|secs}}|
p1desc={{pspan|secs}} is the number of seconds you want to count down from.
}}|

function_description=This function will initiate a countdown from {{pspan|secs}} seconds to 0, during which time nothing else will be acted on. It essentially pauses a script. In addition, a countdown prints to the CLI at varying intervals (every 15 secs for large numbers, 5 seconds for smaller numbers and every second from 5 seconds down).|

needscode=yes|

cli_equiv=wait can also be used from the CLI. It has the same meaning and can be used to pause basic .txt scripts.|
}}