</code></pre></div></div><p>There are 2 different types of arrays currently available:</p><ul><li><p><strong>Lists</strong> - a set of values with specific size (number of elements), where all elements have numeric indexes starting from zero (0) up to array length minus one.</p><p>For example:</p><divclass="language-c++ highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="c1">// this creates list with 3 elements. Element "A" has index 0, element "B" has index 1, element "C" - 2</span>
</code></pre></div></div><p>Limitations:</p><ul><li>all indexes are numeric, starting from 0;</li><li>to assign value to a specific index, you must first resize array to contain this index (for example, if list is of size 3 (indexes from 0 to 2), you can’t assign value to index 4 unless you change list size to 5 first).</li></ul></li><li><p><strong>Maps</strong> (or associative arrays) - a set of key=>value pairs, where all elements (values) are accessed by corresponding keys.</p><p>Differences from list:</p><ul><li>maps don’t have specific size (to assign values, you don’t need to resize array first);</li><li>keys, just like values, can be of any type (but avoid using -1 as array keys or you won’t be able to use some functions reliably).</li></ul></li></ul><p>Both array types have their pros and cons and are suited for different tasks.</p><h2id="arrays-syntax"><ahref="#arrays-syntax"class="anchor-heading"aria-labelledby="arrays-syntax"><svgviewBox="0 0 16 16"aria-hidden="true"><usexlink:href="#svg-link"></use></svg></a> Arrays syntax </h2><p>Basically arrays are implemented using number of new operators (script functions). But for ease of use, there are some new syntax elements:</p><ul><li>Accessing elements. Use square brackets: <divclass="language-js highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="nx">display_msg</span><spanclass="p">(</span><spanclass="nx">arr</span><spanclass="p">[</span><spanclass="mi">5</span><spanclass="p">]);</span>
</code></pre></div></div></li><li>Alternative accessing for maps. Use dot: <divclass="language-js highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="nx">display_msg</span><spanclass="p">(</span><spanclass="nx">mymap</span><spanclass="p">.</span><spanclass="nx">name</span><spanclass="p">);</span>
</code></pre></div></div></li><li>Array expressions. Create and fill arrays with just one expression: <divclass="language-c++ highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="c1">// create list with 5 values</span>
</code></pre></div></div><p><strong>NOTE:</strong> Make sure to call <codeclass="language-plaintext highlighter-rouge">fix_array</code> if you want the new array to be available in the next frame or <codeclass="language-plaintext highlighter-rouge">save_array</code> if you want to use it for a longer period (see next section for details).</p></li><li>Iterating in loop. Use <codeclass="language-plaintext highlighter-rouge">foreach</code> key word like this: <divclass="language-js highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="nx">foreach</span><spanclass="p">(</span><spanclass="nx">item</span><spanclass="k">in</span><spanclass="nx">myarray</span><spanclass="p">)</span><spanclass="nx">begin</span>
</code></pre></div></div></li></ul><p>See “scripting_docs\compiler\sslc_readme.html” file for full information on new SSL syntax features.</p><h2id="storing-arrays"><ahref="#storing-arrays"class="anchor-heading"aria-labelledby="storing-arrays"><svgviewBox="0 0 16 16"aria-hidden="true"><usexlink:href="#svg-link"></use></svg></a> Storing arrays </h2><p>Apart from lists/maps arrays are divided by how they are stored. There a 3 types of arrays:</p><ul><li><p><strong>Temporary</strong>. They are created using <codeclass="language-plaintext highlighter-rouge">temp_array</code> function or when using array expressions. Arrays of this type are auto-deleted at the end of the frame. So, for example, if you have a global script which runs at regular intervals, where you create temp_array, it will not be available next time your global script is executed.</p></li><li><p><strong>Permanent</strong>. They are created using <codeclass="language-plaintext highlighter-rouge">create_array</code> function or <codeclass="language-plaintext highlighter-rouge">fix_array</code> (from pre-existing temporary array). This type of arrays are always available (by their ID) until you start a new game or load a saved game (at which point they are deleted).</p></li><li><p><strong>Saved</strong>. If you want your array to really stay for a while, use function <codeclass="language-plaintext highlighter-rouge">save_array</code> to make any array “saved”. However, they are, like permanent arrays, “deleted” from memory when loading game. In order to use them properly, you must load them from the savegame using <codeclass="language-plaintext highlighter-rouge">load_array</code> whenever you want to use them.</p><p>Example:</p><divclass="language-js highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="nx">variable</span><spanclass="nx">savedArray</span><spanclass="p">;</span>
<spanclass="nx">traps</span><spanclass="p">[</span><spanclass="nx">k</span><spanclass="p">]</span><spanclass="p">:</span><spanclass="o">=</span><spanclass="nx">load_array</span><spanclass="p">(</span><spanclass="dl">"</span><spanclass="s2">trap_</span><spanclass="dl">"</span><spanclass="o">+</span><spanclass="nx">k</span><spanclass="p">);</span><spanclass="c1">// each object is stored separately</span>
</code></pre></div></div><h2id="array-operators-reference"><ahref="#array-operators-reference"class="anchor-heading"aria-labelledby="array-operators-reference"><svgviewBox="0 0 16 16"aria-hidden="true"><usexlink:href="#svg-link"></use></svg></a> Array operators reference </h2><p><em>*mixed means any type</em></p><ul><li><codeclass="language-plaintext highlighter-rouge">int create_array(int size, int flags)</code>: <ul><li>creates permanent array (but not “saved”)</li><li>if <codeclass="language-plaintext highlighter-rouge">size >= 0</code>, creates list with given size</li><li>if <codeclass="language-plaintext highlighter-rouge">size == -1</code>, creates map (associative array)</li><li>if <codeclass="language-plaintext highlighter-rouge">size == -1</code> and <codeclass="language-plaintext highlighter-rouge">flags == 2</code>, creates a “lookup” map (associative array) in which the values of existing keys are read-only and can’t be updated. This type of array allows you to store a zero (0) key value <ul><li>NOTE: in earlier versions (up to 4.1.3/3.8.13) the second argument is not used, just use 0</li></ul></li><li>returns arrayID (valid until array is deleted)</li></ul></li><li><codeclass="language-plaintext highlighter-rouge">int temp_array(int size, int flags)</code>: <ul><li>works exactly like <codeclass="language-plaintext highlighter-rouge">create_array</code>, only created array becomes “temporary”</li></ul></li><li><codeclass="language-plaintext highlighter-rouge">void fix_array(int arrayID)</code>: <ul><li>changes “temporary” array into “permanent” (“permanent” arrays are not automatically saved into savegames)</li></ul></li><li><codeclass="language-plaintext highlighter-rouge">void set_array(int arrayID, mixed key, mixed value)</code>: <ul><li>sets array value</li><li>if used on list, “key” must be numeric and within valid index range (0..size-1)</li><li>if used on map, key can be of any type</li><li>to “unset” a value from map, just set it to zero (0) <ul><li>NOTE: to add a value of 0 for the key, use the float value of 0.0</li></ul></li><li>this works exactly like statement: <codeclass="language-plaintext highlighter-rouge">arrayID[key] := value;</code></li></ul></li><li><codeclass="language-plaintext highlighter-rouge">mixed get_array(int arrayID, mixed key)</code>: <ul><li>returns array value by key or index</li><li>if key doesn’t exist or index is not in valid range, returns 0</li><li>works exactly like expression: <codeclass="language-plaintext highlighter-rouge">(arrayID[key])</code></li></ul></li><li><codeclass="language-plaintext highlighter-rouge">void resize_array(int arrayID, int size)</code>: <ul><li>changes array size</li><li>applicable to maps too, but only to reduce elements</li><li>there are number of special negative values of “size” which perform various operations on the array, use macros <codeclass="language-plaintext highlighter-rouge">sort_array</code>, <codeclass="language-plaintext highlighter-rouge">sort_array_reverse</code>, <codeclass="language-plaintext highlighter-rouge">reverse_array</code>, <codeclass="language-plaintext highlighter-rouge">shuffle_array</code> from <strong>sfall.h</strong> header</li></ul></li><li><codeclass="language-plaintext highlighter-rouge">void free_array(int arrayID)</code>: <ul><li>deletes any array</li><li>if array was “saved”, it will be removed from a savegame</li></ul></li><li><codeclass="language-plaintext highlighter-rouge">mixed scan_array(int arrayID, mixed value)</code>: <ul><li>searches for a first occurrence of given value inside given array</li><li>if value is found, returns it’s index (for lists) or key (for maps)</li><li>if value is not found, returns -1 (be careful, as -1 can be a valid key for a map)</li></ul></li><li><codeclass="language-plaintext highlighter-rouge">int len_array(int arrayID)</code>: <ul><li>returns number of elements or key=>value pairs in a given array</li><li>if array is not found
