fallout2sfall/sfall
0
0
Fork 0
mirror of https://github.com/sfall-team/sfall.git synced 2026-07-27 16:52:34 -07:00
Code Issues Packages Projects Releases Wiki Activity
Files
c4f083b10a93cf73fa4258727586e3d14decae6c
sfall/arrays/index.html
T

68 lines
40 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <link rel="stylesheet" href="/sfall/assets/css/just-the-docs-default.css"> <link rel="stylesheet" href="/sfall/assets/css/just-the-docs-head-nav.css" id="jtd-head-nav-stylesheet"> <style id="jtd-nav-activation"> .site-nav > ul.nav-list:first-child > li:not(:nth-child(2)) > a, .site-nav > ul.nav-list:first-child > li > ul > li a { background-image: none; } .site-nav > ul.nav-list:not(:first-child) a, .site-nav li.external a { background-image: none; } .site-nav > ul.nav-list:first-child > li:nth-child(2) > a { font-weight: 600; text-decoration: none; }.site-nav > ul.nav-list:first-child > li:nth-child(2) > button svg { transform: rotate(-90deg); }.site-nav > ul.nav-list:first-child > li.nav-list-item:nth-child(2) > ul.nav-list { display: block; } </style> <script src="/sfall/assets/js/vendor/lunr.min.js"></script> <script src="/sfall/assets/js/just-the-docs.js"></script> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="icon" href="/sfall/favicon.ico" type="image/x-icon"> <!-- Begin Jekyll SEO tag v2.8.0 --> <title>Arrays | sfall</title> <meta name="generator" content="Jekyll v3.9.2" /> <meta property="og:title" content="Arrays" /> <meta property="og:locale" content="en_US" /> <meta name="description" content="Sfall documentation" /> <meta property="og:description" content="Sfall documentation" /> <link rel="canonical" href="/sfall/arrays/" /> <meta property="og:url" content="/sfall/arrays/" /> <meta property="og:site_name" content="sfall" /> <meta property="og:type" content="website" /> <meta name="twitter:card" content="summary" /> <meta property="twitter:title" content="Arrays" /> <script type="application/ld+json"> {"@context":"https://schema.org","@type":"WebPage","description":"Sfall documentation","headline":"Arrays","url":"/sfall/arrays/"}</script> <!-- End Jekyll SEO tag --> <link rel="apple-touch-icon" sizes="180x180" href="/assets/favicon/apple-touch-icon.png"> <link rel="icon" type="image/png" sizes="32x32" href="/assets/favicon/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon/favicon-16x16.png"> <link rel="manifest" href="/assets/favicon/site.webmanifest"> <link rel="mask-icon" href="/assets/favicon/safari-pinned-tab.svg" color="#5bbad5"> <meta name="msapplication-TileColor" content="#da532c"> <meta name="msapplication-config" content="/assets/favicon/browserconfig.xml"> <meta name="theme-color" content="#ffffff"> </head> <body> <a class="skip-to-main" href="#main-content">Skip to main content</a> <svg xmlns="http://www.w3.org/2000/svg" class="d-none"> <symbol id="svg-link" viewBox="0 0 24 24"> <title>Link</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"> <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <!-- Feather. MIT License: https://github.com/feathericons/feather/blob/master/LICENSE --> <symbol id="svg-external-link" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-external-link"> <title id="svg-external-link-title">(external link)</title> <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path><polyline points="15 3 21 3 21 9"></polyline><line x1="10" y1="14" x2="21" y2="3"></line> </symbol> <symbol id="svg-doc" viewBox="0 0 24 24"> <title>Document</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file"> <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline> </svg> </symbol> <symbol id="svg-search" viewBox="0 0 24 24"> <title>Search</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search"> <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line> </svg> </symbol> <!-- Bootstrap Icons. MIT License: https://github.com/twbs/icons/blob/main/LICENSE.md --> <symbol id="svg-copy" viewBox="0 0 16 16"> <title>Copy</title> <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard" viewBox="0 0 16 16"> <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/> <path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/> </svg> </symbol> <symbol id="svg-copied" viewBox="0 0 16 16"> <title>Copied</title> <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard-check-fill" viewBox="0 0 16 16"> <path d="M6.5 0A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3Zm3 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3Z"/> <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1A2.5 2.5 0 0 1 9.5 5h-3A2.5 2.5 0 0 1 4 2.5v-1Zm6.854 7.354-3 3a.5.5 0 0 1-.708 0l-1.5-1.5a.5.5 0 0 1 .708-.708L7.5 10.793l2.646-2.647a.5.5 0 0 1 .708.708Z"/> </svg> </symbol> </svg> <header class="side-bar"> <div class="site-header"> <a href="/sfall/" class="site-title lh-tight"> sfall </a> <button id="menu-button" class="site-button btn-reset" aria-label="Menu" aria-expanded="false"> <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-menu"></use></svg> </button> </div> <nav aria-label="Main" id="site-nav" class="site-nav"> <ul class="nav-list"><li class="nav-list-item"><a href="/sfall/" class="nav-list-link">Home</a></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Arrays submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/arrays/" class="nav-list-link">Arrays</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/array-functions/" class="nav-list-link">Array functions</a></li><li class="nav-list-item"><a href="/sfall/lists/" class="nav-list-link">Lists</a></li></ul></li><li class="nav-list-item"><a href="/sfall/best-practices/" class="nav-list-link">Best practices</a></li><li class="nav-list-item"><a href="/sfall/data-types/" class="nav-list-link">Data types</a></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Global scripts submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/global-scripts/" class="nav-list-link">Global scripts</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/global-script-functions/" class="nav-list-link">Global script functions</a></li></ul></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Hooks submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/hooks/" class="nav-list-link">Hooks</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/hook-functions/" class="nav-list-link">Hook functions</a></li><li class="nav-list-item"><a href="/sfall/hook-types/" class="nav-list-link">Hook types</a></li></ul></li><li class="nav-list-item"><a href="/sfall/sslc/" class="nav-list-link">SSLC</a></li><li class="nav-list-item"><a href="/sfall/optimization/" class="nav-list-link">Optimization</a></li><li class="nav-list-item"><a href="/sfall/animations/" class="nav-list-link">Animations</a></li><li class="nav-list-item"><a href="/sfall/art-and-appearance/" class="nav-list-link">Art and appearance</a></li><li class="nav-list-item"><a href="/sfall/audio/" class="nav-list-link">Audio</a></li><li class="nav-list-item"><a href="/sfall/car/" class="nav-list-link">Car</a></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Combat submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/combat/" class="nav-list-link">Combat</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/knockback/" class="nav-list-link">Knockback</a></li><li class="nav-list-item"><a href="/sfall/weapons-and-ammo/" class="nav-list-link">Weapons and ammo</a></li></ul></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Direct memory access submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/direct-memory-access/" class="nav-list-link">Direct memory access</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/call_offset_vx/" class="nav-list-link">call_offset_vX</a></li><li class="nav-list-item"><a href="/sfall/read_xxx/" class="nav-list-link">read_xxx</a></li><li class="nav-list-item"><a href="/sfall/write_xxx/" class="nav-list-link">write_xxx</a></li></ul></li><li class="nav-list-item"><a href="/sfall/explosions/" class="nav-list-link">Explosions</a></li><li class="nav-list-item"><a href="/sfall/global-variables/" class="nav-list-link">Global variables</a></li><li class="nav-list-item"><a href="/sfall/graphics/" class="nav-list-link">Graphics</a></li><li class="nav-list-item"><a href="/sfall/ini-settings/" class="nav-list-link">INI settings</a></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Interface submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/interface/" class="nav-list-link">Interface</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/cursor/" class="nav-list-link">Cursor</a></li><li class="nav-list-item"><a href="/sfall/inventory/" class="nav-list-link">Inventory</a></li><li class="nav-list-item"><a href="/sfall/main-interface/" class="nav-list-link">Main interface</a></li><li class="nav-list-item"><a href="/sfall/outline/" class="nav-list-link">Outline</a></li><li class="nav-list-item"><a href="/sfall/pip-boy/" class="nav-list-link">Pip-Boy</a></li><li class="nav-list-item"><a href="/sfall/tags/" class="nav-list-link">Tags</a></li><li class="nav-list-item"><a href="/sfall/windows-and-images/" class="nav-list-link">Windows and images</a></li></ul></li><li class="nav-list-item"><a href="/sfall/keyboard-and-mouse/" class="nav-list-link">Keyboard and mouse</a></li><li class="nav-list-item"><a href="/sfall/locks/" class="nav-list-link">Locks</a></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Maps and encounters submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/maps-and-encounters/" class="nav-list-link">Maps and encounters</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/rest/" class="nav-list-link">Rest</a></li><li class="nav-list-item"><a href="/sfall/worldmap/" class="nav-list-link">Worldmap</a></li></ul></li><li class="nav-list-item"><a href="/sfall/objects-and-scripts/" class="nav-list-link">Objects and scripts</a></li><li class="nav-list-item"><a href="/sfall/other/" class="nav-list-link">Other</a></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Perks and traits submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/perks-and-traits/" class="nav-list-link">Perks and traits</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/npc-perks/" class="nav-list-link">NPC perks</a></li></ul></li><li class="nav-list-item"><a href="/sfall/sfall-funcx-macros/" class="nav-list-link">Sfall funcX macros</a></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Sfall submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/sfall/" class="nav-list-link">Sfall</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/funcx/" class="nav-list-link">funcX</a></li><li class="nav-list-item"><a href="/sfall/version/" class="nav-list-link">Version</a></li></ul></li><li class="nav-list-item"><a href="/sfall/skills/" class="nav-list-link">Skills</a></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Stats submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/stats/" class="nav-list-link">Stats</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/alter-min-max/" class="nav-list-link">Alter min/max</a></li></ul></li><li class="nav-list-item"><a href="/sfall/tiles-and-paths/" class="nav-list-link">Tiles and paths</a></li><li class="nav-list-item"><button class="nav-list-expander btn-reset" aria-label="Utility submenu" aria-expanded="false"> <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg> </button><a href="/sfall/utility/" class="nav-list-link">Utility</a><ul class="nav-list"><li class="nav-list-item"><a href="/sfall/math/" class="nav-list-link">Math</a></li><li class="nav-list-item"><a href="/sfall/strings/" class="nav-list-link">Strings</a></li></ul></li><li class="nav-list-item"><a href="/sfall/virtual-file-system/" class="nav-list-link">Virtual file system</a></li></ul> </nav> <div class="d-md-block d-none site-footer"> This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. </div> </header> <div class="main" id="top"> <div id="main-header" class="main-header"> <div class="search" role="search"> <div class="search-input-wrap"> <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search sfall" autocomplete="off"> <label for="search-input" class="search-label"> <span class="sr-only">Search sfall</span> <svg viewBox="0 0 24 24" class="search-icon" aria-hidden="true"><use xlink:href="#svg-search"></use></svg> </label> </div> <div id="search-results" class="search-results"></div> </div> <nav aria-label="Auxiliary" class="aux-nav"> <ul class="aux-nav-list"> <li class="aux-nav-list-item"> <a href="https://nma-fallout.com/threads/fo2-engine-tweaks-sfall.178390/" class="site-button" > Forum </a> </li> <li class="aux-nav-list-item"> <a href="https://github.com/phobos2077/sfall/" class="site-button" > GitHub </a> </li> </ul> </nav> </div> <div class="main-content-wrap"> <div id="main-content" class="main-content"> <main> <h1 class="no_toc" id="arrays"> <a href="#arrays" class="anchor-heading" aria-labelledby="arrays"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Arrays </h1> <p>sfall introduces new method of storing variables - arrays.</p> <p>Array is basically a container which can store variable number of values (elements). Each element in array can be of any type. Arrays can be extremely useful for some more advanced scripting, in conjunction with loops. See array function reference <a href="/sfall/array-functions/">here</a>.</p> <ul id="markdown-toc"> <li><a href="#arrays-concept" id="markdown-toc-arrays-concept">Arrays concept</a></li> <li><a href="#arrays-syntax" id="markdown-toc-arrays-syntax">Arrays syntax</a></li> <li><a href="#storing-arrays" id="markdown-toc-storing-arrays">Storing arrays</a></li> <li><a href="#practical-examples" id="markdown-toc-practical-examples">Practical examples</a> <ul> <li><a href="#use-arrays-to-implement-variable-argument-procedures" id="markdown-toc-use-arrays-to-implement-variable-argument-procedures">Use arrays to implement variable-argument procedures</a></li> <li><a href="#create-arrays-of-objects-maps-for-advanced-scripting" id="markdown-toc-create-arrays-of-objects-maps-for-advanced-scripting">Create arrays of objects (maps) for advanced scripting</a></li> </ul> </li> <li><a href="#array-operators-reference" id="markdown-toc-array-operators-reference">Array operators reference</a></li> <li><a href="#backward-compatibility-notes" id="markdown-toc-backward-compatibility-notes">Backward compatibility notes</a></li> </ul> <h2 id="arrays-concept"> <a href="#arrays-concept" class="anchor-heading" aria-labelledby="arrays-concept"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Arrays concept </h2> <p>Array elements are accessed by index or key. For example:</p> <div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// this code puts some string in array "list" at index 5:</span>
<span class="n">list</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span> <span class="o">:=</span> <span class="s">"Value"</span><span class="p">;</span>
</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> <div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// this creates list with 3 elements. Element "A" has index 0, element "B" has index 1, element "C" - 2</span>
<span class="n">list</span> <span class="o">:=</span> <span class="p">[</span><span class="s">"A"</span><span class="p">,</span> <span class="s">"B"</span><span class="p">,</span> <span class="s">"C"</span><span class="p">];</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=&gt;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> <h2 id="arrays-syntax"> <a href="#arrays-syntax" class="anchor-heading" aria-labelledby="arrays-syntax"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink: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: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">display_msg</span><span class="p">(</span><span class="nx">arr</span><span class="p">[</span><span class="mi">5</span><span class="p">]);</span>
<span class="nx">mymap</span><span class="p">[</span><span class="dl">"</span><span class="s2">price</span><span class="dl">"</span><span class="p">]</span> <span class="p">:</span><span class="o">=</span> <span class="mf">515.23</span><span class="p">;</span>
</code></pre></div> </div> </li> <li>Alternative accessing for maps. Use dot: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">display_msg</span><span class="p">(</span><span class="nx">mymap</span><span class="p">.</span><span class="nx">name</span><span class="p">);</span>
<span class="nx">mymap</span><span class="p">.</span><span class="nx">price</span> <span class="p">:</span><span class="o">=</span> <span class="mf">232.23</span><span class="p">;</span>
</code></pre></div> </div> </li> <li>Array expressions. Create and fill arrays with just one expression: <div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// create list with 5 values</span>
<span class="p">[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">777</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">3.14</span><span class="p">,</span> <span class="s">"Cool Value"</span><span class="p">]</span>
<span class="c1">// create map:</span>
<span class="p">{</span><span class="mi">5</span><span class="o">:</span> <span class="s">"Five"</span><span class="p">,</span> <span class="s">"health"</span><span class="o">:</span> <span class="mi">50</span><span class="p">,</span> <span class="s">"speed"</span><span class="o">:</span> <span class="mf">0.252</span><span class="p">}</span>
</code></pre></div> </div> <p><strong>NOTE:</strong> Make sure to call <code class="language-plaintext highlighter-rouge">fix_array</code> if you want the new array to be available in the next frame or <code class="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 <code class="language-plaintext highlighter-rouge">foreach</code> key word like this: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">foreach</span> <span class="p">(</span><span class="nx">item</span> <span class="k">in</span> <span class="nx">myarray</span><span class="p">)</span> <span class="nx">begin</span>
<span class="c1">// this block is executed for each array element, where "item" contains current value on each step</span>
<span class="nx">end</span>
<span class="c1">// alternative syntax:</span>
<span class="nx">foreach</span> <span class="p">(</span><span class="nx">key</span><span class="p">:</span> <span class="nx">item</span> <span class="k">in</span> <span class="nx">myarray</span><span class="p">)</span> <span class="nx">begin</span>
<span class="c1">// "key" will contain current key (or numeric index, for lists)</span>
<span class="nx">end</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> <h2 id="storing-arrays"> <a href="#storing-arrays" class="anchor-heading" aria-labelledby="storing-arrays"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink: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 <code class="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 <code class="language-plaintext highlighter-rouge">create_array</code> function or <code class="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 <code class="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 <code class="language-plaintext highlighter-rouge">load_array</code> whenever you want to use them.</p> <p>Example:</p> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">variable</span> <span class="nx">savedArray</span><span class="p">;</span>
<span class="nx">procedure</span> <span class="nx">start</span> <span class="nx">begin</span>
<span class="k">if</span> <span class="nx">game_loaded</span> <span class="nx">then</span> <span class="nx">begin</span>
<span class="nx">savedArray</span> <span class="p">:</span><span class="o">=</span> <span class="nx">load_array</span><span class="p">(</span><span class="dl">"</span><span class="s2">traps</span><span class="dl">"</span><span class="p">);</span>
<span class="nx">end</span> <span class="k">else</span> <span class="nx">begin</span>
<span class="nx">foreach</span> <span class="nx">trap</span> <span class="k">in</span> <span class="nx">traps</span> <span class="nx">begin</span>
<span class="p">....</span>
<span class="nx">end</span>
<span class="nx">end</span>
<span class="nx">end</span>
</code></pre></div> </div> </li> </ul> <h2 id="practical-examples"> <a href="#practical-examples" class="anchor-heading" aria-labelledby="practical-examples"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Practical examples </h2> <h3 id="use-arrays-to-implement-variable-argument-procedures"> <a href="#use-arrays-to-implement-variable-argument-procedures" class="anchor-heading" aria-labelledby="use-arrays-to-implement-variable-argument-procedures"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Use arrays to implement variable-argument procedures </h3> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// define it</span>
<span class="nx">procedure</span> <span class="nx">give_item</span><span class="p">(</span><span class="nx">variable</span> <span class="nx">critter</span><span class="p">,</span> <span class="nx">variable</span> <span class="nx">pidList</span><span class="p">)</span> <span class="nx">begin</span>
<span class="nx">foreach</span> <span class="p">(</span><span class="nx">pid</span><span class="p">:</span> <span class="nx">qty</span> <span class="k">in</span> <span class="nx">pidList</span><span class="p">)</span> <span class="nx">begin</span>
<span class="nx">give_pid_qty</span><span class="p">(</span><span class="nx">critter</span><span class="p">,</span> <span class="nx">pid</span><span class="p">,</span> <span class="nx">qty</span><span class="p">);</span>
<span class="nx">end</span>
<span class="nx">end</span>
<span class="c1">// call it:</span>
<span class="nx">call</span> <span class="nx">give_item</span><span class="p">(</span><span class="nx">dude_obj</span><span class="p">,</span> <span class="p">{</span><span class="na">PID_SHOTGUN</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="na">PID_SHOTGUN_SHELLS</span><span class="p">:</span> <span class="mi">4</span><span class="p">,</span> <span class="na">PID_STIMPAK</span><span class="p">:</span> <span class="mi">3</span><span class="p">});</span>
</code></pre></div></div> <h3 id="create-arrays-of-objects-maps-for-advanced-scripting"> <a href="#create-arrays-of-objects-maps-for-advanced-scripting" class="anchor-heading" aria-labelledby="create-arrays-of-objects-maps-for-advanced-scripting"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Create arrays of objects (maps) for advanced scripting </h3> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">variable</span> <span class="nx">traps</span><span class="p">;</span>
<span class="nx">procedure</span> <span class="nx">init_traps</span> <span class="nx">begin</span>
<span class="c1">// just a quick example, there is a better way of doing it...</span>
<span class="nx">traps</span> <span class="p">:</span><span class="o">=</span> <span class="nx">load_array</span><span class="p">(</span><span class="dl">"</span><span class="s2">traps</span><span class="dl">"</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">traps</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span> <span class="nx">then</span> <span class="nx">begin</span>
<span class="nx">traps</span> <span class="p">:</span><span class="o">=</span> <span class="p">[];</span>
<span class="nx">save_array</span><span class="p">(</span><span class="dl">"</span><span class="s2">traps</span><span class="dl">"</span><span class="p">,</span> <span class="nx">traps</span><span class="p">);</span>
<span class="nx">end</span>
<span class="nx">foreach</span> <span class="nx">k</span><span class="p">:</span> <span class="nx">v</span> <span class="k">in</span> <span class="nx">traps</span> <span class="nx">begin</span>
<span class="nx">traps</span><span class="p">[</span><span class="nx">k</span><span class="p">]</span> <span class="p">:</span><span class="o">=</span> <span class="nx">load_array</span><span class="p">(</span><span class="dl">"</span><span class="s2">trap_</span><span class="dl">"</span><span class="o">+</span><span class="nx">k</span><span class="p">);</span> <span class="c1">// each object is stored separately</span>
<span class="nx">end</span>
<span class="nx">end</span>
<span class="nx">procedure</span> <span class="nx">add_trap</span><span class="p">(</span><span class="nx">variable</span> <span class="nx">trapArray</span><span class="p">)</span> <span class="nx">begin</span>
<span class="nx">variable</span> <span class="nx">index</span><span class="p">;</span>
<span class="nl">index</span> <span class="p">:</span><span class="o">=</span> <span class="nx">len_array</span><span class="p">(</span><span class="nx">traps</span><span class="p">);</span>
<span class="nx">save_array</span><span class="p">(</span><span class="dl">"</span><span class="s2">trap_</span><span class="dl">"</span><span class="o">+</span><span class="nx">k</span><span class="p">,</span> <span class="nx">trapArray</span><span class="p">);</span>
<span class="nx">array_push</span><span class="p">(</span><span class="nx">traps</span><span class="p">,</span> <span class="nx">trapArray</span><span class="p">);</span>
<span class="nx">end</span>
<span class="c1">// use them:</span>
<span class="nx">foreach</span> <span class="nx">trap</span> <span class="k">in</span> <span class="nx">traps</span> <span class="nx">begin</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">self_elevation</span> <span class="o">==</span> <span class="nx">trap</span><span class="p">[</span><span class="dl">"</span><span class="s2">elev</span><span class="dl">"</span><span class="p">]</span> <span class="nx">and</span> <span class="nx">tile_distance</span><span class="p">(</span><span class="nx">self_tile</span><span class="p">,</span> <span class="nx">trap</span><span class="p">[</span><span class="dl">"</span><span class="s2">tile</span><span class="dl">"</span><span class="p">])</span> <span class="o">&lt;</span> <span class="nx">trap</span><span class="p">[</span><span class="dl">"</span><span class="s2">radius</span><span class="dl">"</span><span class="p">])</span> <span class="nx">then</span>
<span class="c1">// kaboom!!!</span>
<span class="nx">end</span>
<span class="nx">end</span>
</code></pre></div></div> <h2 id="array-operators-reference"> <a href="#array-operators-reference" class="anchor-heading" aria-labelledby="array-operators-reference"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Array operators reference </h2> <p><em>*mixed means any type</em></p> <ul> <li><code class="language-plaintext highlighter-rouge">int create_array(int size, int flags)</code>: <ul> <li>creates permanent array (but not “saved”)</li> <li>if <code class="language-plaintext highlighter-rouge">size &gt;= 0</code>, creates list with given size</li> <li>if <code class="language-plaintext highlighter-rouge">size == -1</code>, creates map (associative array)</li> <li>if <code class="language-plaintext highlighter-rouge">size == -1</code> and <code class="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><code class="language-plaintext highlighter-rouge">int temp_array(int size, int flags)</code>: <ul> <li>works exactly like <code class="language-plaintext highlighter-rouge">create_array</code>, only created array becomes “temporary”</li> </ul> </li> <li><code class="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><code class="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: <code class="language-plaintext highlighter-rouge">arrayID[key] := value;</code></li> </ul> </li> <li><code class="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: <code class="language-plaintext highlighter-rouge">(arrayID[key])</code></li> </ul> </li> <li><code class="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 <code class="language-plaintext highlighter-rouge">sort_array</code>, <code class="language-plaintext highlighter-rouge">sort_array_reverse</code>, <code class="language-plaintext highlighter-rouge">reverse_array</code>, <code class="language-plaintext highlighter-rouge">shuffle_array</code> from <strong>sfall.h</strong> header</li> </ul> </li> <li><code class="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><code class="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><code class="language-plaintext highlighter-rouge">int len_array(int arrayID)</code>: <ul> <li>returns number of elements or key=&gt;value pairs in a given array</li> <li>if array is not found, returns -1 (can be used to check if given array exist)</li> </ul> </li> <li><code class="language-plaintext highlighter-rouge">void save_array(mixed key, int arrayID)</code>: <ul> <li>makes the array saveable; it will be saved in <strong>sfallgv.sav</strong> file when saving the game</li> <li>arrayID is associated with given “key”</li> <li>array becomes permanent (if it was temporary) and “saved”</li> <li>key can be of any type (int, float or string)</li> <li>if you specify 0 as the key for the array ID, it will make the array “unsaved”</li> </ul> </li> <li><code class="language-plaintext highlighter-rouge">int load_array(mixed key)</code>: <ul> <li>loads array from savegame data by the same key provided in <code class="language-plaintext highlighter-rouge">save_array</code></li> <li>returns array ID or zero (0) if none found</li> </ul> </li> <li><code class="language-plaintext highlighter-rouge">mixed array_key(int arrayID, int index)</code>: <ul> <li>don’t use it directly; it is generated by the compiler in foreach loops</li> <li>for lists, returns index back (no change)</li> <li>for maps, returns a key at the specified numeric index (don’t rely on the order in which keys are stored though)</li> <li>can be checked if given array is associative or not, by using index (-1): 0 - array is list, 1 - array is map</li> </ul> </li> <li><code class="language-plaintext highlighter-rouge">int arrayexpr(mixed key, mixed value)</code>: <ul> <li>don’t use it directly; it is used by compiler to create array expressions</li> <li>assigns value to a given key in an array, created by last <code class="language-plaintext highlighter-rouge">create_array</code> or <code class="language-plaintext highlighter-rouge">temp_array</code> call</li> <li>always returns 0</li> </ul> </li> </ul> <h2 id="backward-compatibility-notes"> <a href="#backward-compatibility-notes" class="anchor-heading" aria-labelledby="backward-compatibility-notes"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Backward compatibility notes </h2> <p>For those who used arrays in their mods before sfall 3.4:</p> <ul> <li> <p>There is an INI parameter <strong>ArraysBehavior</strong> in <strong>Misc</strong> section of ddraw.ini. If set to 0, all scripts which used sfall arrays before should work. This basically changes that <code class="language-plaintext highlighter-rouge">create_array</code> will create permanent arrays which are “saved” by default and their IDs are also permanent. It is 1 by default.</p> </li> <li> <p><strong>NOTE:</strong> Starting from sfall 4.3.3/3.8.33, the <strong>ArraysBehavior</strong> option is removed, and arrays always work in <strong>ArraysBehavior=1</strong> mode. Make sure to review your scripts if you need to save arrays into savegames.</p> </li> <li> <p>How savegame compatibility is handled?<br /> Saved arrays are stored in <strong>sfallgv.sav</strong> file (in savegame) in new (more flexible) format, just after the old arrays. So basically, when you load older savegame, sfall will load arrays from old format and save them to new format on next game save. If you load savegame made with sfall 3.4 using sfall 3.3 (for example), the game shouldn’t crash, but all arrays will be lost.</p> </li> <li> <p>Previously you had to specify size in bytes for array elements. This parameter is now ignored and you can store strings of arbitrary length in arrays.</p> </li> </ul> <hr> <h2 class="text-delta">Table of contents</h2> <ul> <li> <a href="/sfall/array-functions/">Array functions</a> </li> <li> <a href="/sfall/lists/">Lists</a> </li> </ul> </main> <hr> <footer> <div class="d-md-none mt-4 fs-2"> This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. </div> </footer> </div> </div> <div class="search-overlay"></div> </div> </body> </html>
Reference in New Issue View Git Blame Copy Permalink