<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE doc
  SYSTEM '../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../clonk.xsl"?>
<doc>
  <title>Data Types</title>
  <h>Data Types</h>
  <part>
    <text>C4Script supports the following data types for variables, parameters, and return values:</text>
    <text>
      <table>
        <rowh>
          <col>Type Name</col>
          <col>Full Name</col>
          <col>Contents of Variable</col>
          <col>Example</col>
        </rowh>
        <row>
          <col><code>int</code></col>
          <col>Integer</col>
          <col>A whole number from -2.147.483.648 to +2.147.483.647.</col>
          <col><code>42</code></col>
        </row>
        <row>
          <col><code>bool</code></col>
          <col>Boolean</col>
          <col>"true" (value <code>true</code>) or "false" (value <code>false</code>). Expected as parameter by many structures such as <funclink>if</funclink> and <funclink>while</funclink>.</col>
          <col><code>true</code></col>
        </row>
        <row>
          <col><code>string</code></col>
          <col>String</col>
          <col>Any text.</col>
          <col><code>&quot;This is a text!&quot;</code></col>
        </row>
        <row>
          <col><code>array</code></col>
          <col>Array</col>
          <col>A type containing multiple variables, whose number can be enquired with <funclink>GetLength</funclink>, and which can be recalled with <code><em>array</em>[<em>index</em>]</code>.</col>
          <col><code>[0,23,Clonk]</code></col>
        </row>
        <row>
          <col><code>proplist</code></col>
          <col>Object</col>
          <col>A general purpose object type. <funclink>GetProperty</funclink> and <funclink>SetProperty</funclink> can get respectively set properties. If the property <code>"Prototype"</code> is set, and a property that is not set is gotten, the prototype is asked.</col>
          <col><code>{ foo = 0, &quot;bar baz&quot; = 13, Prototype = Clonk }</code></col>
        </row>
        <row>
          <col><code>object</code></col>
          <col>Ingame Object</col>
          <col>Reference to an existing object at runtime. No direct representation. See <funclink>FindObject</funclink>()</col>
          <col><code>CreateObject(Clonk)</code></col>
        </row>
        <row>
          <col><code>nil</code></col>
          <col></col>
          <col>The type of <code>nil</code>.</col>
          <col><code>nil</code></col>
        </row>
        <row>
          <col><code>any</code></col>
          <col></col>
          <col>When used as a function parameter type, the type check is skipped.</col>
          <col></col>
        </row>
        <row>
          <col><code>id</code></col>
          <col>definition id</col>
          <col>ID of an object definition (see <emlink href="definition/index.html#ObjektundEntwicklerIdentifikation">Object Definitions</emlink>).Will be changed into a proplist immediately.</col>
          <col><code>Clonk</code></col>
        </row>
      </table>
    </text>
    <h>Arrays</h>
    <part>
      <text>Arrays can be created directly with <code>[<em>expression 1</em>, <em>expression 2</em>, ...]</code> or indirectly with <funclink>CreateArray</funclink>(). They are automatically enlarged if necessary on element access, but it's faster to create them with the needed length from the start. If an array is stored in a variable or used as a parameter to a function, the new variable has it's own copy of the array. The actual copy is deferred if possible, though. If an array is passed to a function for modification, a reference has to be used.</text>
      <text>Access to element <code>i</code> of array <code>a</code> is achieved through <code>a[i]</code>. <code>i=0</code> is the first element. Negative indices are counted from the end of the array, so that <code>a[-1]</code> refers to the last element of the array.</text>
      <text>A range within an array can be copied with <code>a[i:j]</code>. The resulting array contains all elements with indices in the half-open interval <code>[i,j)</code>. Negative indices are treated as when accessing single elements. Both indices are optional and assumed as <code>0</code> and <code><funclink>GetLength</funclink>(a)</code> respectively if not given.</text>
      <h>Example 1</h>
      <code>func ArraySum(array a)
{
  var l = <funclink>GetLength</funclink>(a);
  var result = 0;
  for (var i = 0; i &lt; l; ++i)
  {
    result += a[i];
  }
  return (result);
}</code>
      <text>This function adds up all elements of an array.</text>
      <h>Example 2</h>
      <code>func RandomID()
{
  var a = [Clonk, Wipf, Bird];
  return (a[<funclink>Random</funclink>(3)]);
}</code>
      <text>This function randomly chooses one out of four ids and returns it.</text>
      <h>Example 3</h>
      <code>func DetonateNearest()
{
  var a = <funclink>FindObjects</funclink>(<funclink>Find_ID</funclink>(Dynamite), <funclink>Sort_Distance</funclink>());
  for (var dyna in a[:6])
  {
    dyna-&gt;DoExplode();
  }
}</code>
      <text>This function calls <code>DoExplode()</code> on the six nearest Dynamite objects.</text>
    </part>
    <h>Proplists</h>
    <part>
      <text>Proplists are a datatype that maps values to strings and supports prototype inheritance.</text>
      <text>Proplists can be created with <code>{<i>key 1</i>=<i>expression 1</i>, <i>key 2</i>=<i>expression 2</i>, ...}</code> or with <funclink>CreateProplist</funclink>.</text>
    </part>
    <h>Conversion</h>
    <text>
      <ul>
        <li>All values except for <code>false</code>, <code>nil</code> and <code>0</code> are treated as <code>true</code> when a bool is required.</li>
        <li><code>nil</code> and <code>false</code> can be converted to <code>0</code>. <code>true</code> can be converted to <code>1</code>.</li>
        <li><code>nil</code> can always be used as a function parameter, if the function doesn't implement a separate check.</li>
        <li>If an object has been converted into a proplist then it can be converted back to an object. Otherwise proplists cannot be converted into objects.</li>
      </ul>
    </text>
  </part>
  <author>Günther</author><date>2010-2011</date>
  <author>PeterW</author><date>2006-04</date>
</doc>
