Reference Talk:Array - Revision history

Jholsenback: additions

2016-12-13T18:29:07Z

additions

Jholsenback: a few layout / content changes

2016-11-25T11:52:33Z

a few layout / content changes

Jholsenback: fixed typos etc

2016-11-24T14:03:07Z

fixed typos etc

Jholsenback: consistency

2016-11-23T16:53:46Z

consistency

Jholsenback: fixed syntax diagram typos

2016-11-23T16:49:24Z

fixed syntax diagram typos

Jholsenback: corrections and layout

2016-11-23T16:38:22Z

corrections and layout

Show changes

Jholsenback: link repair

2016-11-23T12:06:50Z

link repair

Jholsenback: link correction

2016-11-23T12:02:42Z

link correction

Jholsenback: syntax diagram and various updates

2016-11-23T11:59:12Z

syntax diagram and various updates

Jholsenback: initial creation

2016-11-22T22:19:09Z

initial creation

New page

{{#indexentry:Identifiers, array}}
{{#indexentry:Array, identifiers}}
{{#indexentry:array}}
You may declare arrays of identifiers of up to five dimensions. Any
item that can be declared as an identifier can be declared in an array.

{{#indexentry:Array, declaring}}
{{#indexentry:Declaring, arrays}}
==Declaring Arrays==
The syntax for declaring an array is as follows:
<pre>
ARRAY_DECLARATION:
#declare IDENTIFIER = array[ INT ][[ INT ]]..[ARRAY_INITIALIZER] |
#local IDENTIFIER = array[ INT ][[ INT ]]..[ARRAY_INITIALIZER]
ARRAY_INITIALIZER:
{ARRAY_ITEM, [ARRAY_ITEM, ]... }
ARRAY_ITEM:
RVALUE | ARRAY_INITIALIZER
</pre>

Where IDENTIFIER is the name of the identifier up to 40 characters long
and INT is a valid float expression which is internally truncated to an
integer which specifies the size of the array. The optional 
ARRAY_INITIALIZER is discussed in the next section [[Reference:Array#Array Initializers|Array Initializers]].
Here is an example of a one-dimensional, uninitialized array.
<pre>
#declare MyArray = array[10]
</pre>

This declares an uninitialized array of ten elements. The elements are
referenced as <code>MyArray[0]</code> through <code>MyArray[9]</code>. As
yet, the type of the elements are undetermined. Once you have initialized any
element of the array, all other elements can only be defined as that type. An
attempt to reference an uninitialized element results in an error. For
example:
<pre>
#declare MyArray = array[10]
#declare MyArray[5] = pigment{White} //all other elements must
//be pigments too.
#declare MyArray[2] = normal{bumps 0.2} //generates an error
#declare Thing = MyArray[4] //error: uninitialized array element
</pre>

Multi-dimensional arrays up to five dimensions may be declared. For
example:
<pre>
#declare MyGrid = array[4][5]
</pre>

declares a 20 element array of 4 rows and 5 columns. Elements are
referenced from <code>MyGrid[0][0]</code> to <code>MyGrid[3][4]</code>.
Although it is permissible to reference an entire array as a whole, you may
not reference just one dimension of a multi-dimensional array. For
example:
<pre>
#declare MyArray = array[10]
#declare MyGrid = array[4][5]
#declare YourArray = MyArray //this is ok
#declare YourGrid = MyGrid //so is this
#declare OneRow = MyGrid[2] //this is illegal
</pre>
The <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|:#ifdef|#ifdef]]</code> and <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|:#ifndef|#ifndef]]</code> directives can be used to check whether a specific element of an array has been declared. For methods to determine the size of an array look in the float section for <code>[[Reference:Numeric Expressions#Functions|:dimensions|dimensions]]</code> and
<code>[[Reference:Numeric Expressions#Functions|:dimension_size|dimension_size]]</code>.

Large uninitialized arrays do not take much memory. Internally they are
arrays of pointers so they probably use just 4 bytes per element. Once
initialized with values, they consume memory depending on what you put in
them.

The rules for local vs. global arrays are the same as any other identifier.
Note: This applies to the entire array. You cannot mix local and global
elements in the same array. See [[Reference:Declare and Local Directives#declare vs. local|#declare vs. #local]] for
information on identifier scope.
Any legitimate use of the <code>#declare</code> directive can also be put into an array. In other words, you can also create multidimensional arrays by making an array of arrays.

{{#indexentry:Array, initialization}}
{{#indexentry:Initialization, arrays}}

==Array Initializers==
Because it is cumbersome to individually initialize the elements of an
array, you may initialize it as it is created using array initializer syntax.
For example:
<pre>
#include "colors.inc"
#declare FlagColors = array[3] {Red,White,Blue}
</pre>

Multi-dimensional arrays may also be initialized this way. For
example:
<pre>
#declare Digits =
array[4][10] {
{7,6,7,0,2,1,6,5,5,0},
{1,2,3,4,5,6,7,8,9,0},
{0,9,8,7,6,5,4,3,2,1},
{1,1,2,2,3,3,4,4,5,5}
}
</pre>

The commas are required between elements and between dimensions as shown
in the example.

{{#indexentry:Array, declaring}}
{{#indexentry:Declaring, arrays}}
==Dictionary Container Types==
A {{New}} version 3.7.1 feature allows arrays to be modified as follows:

<ol>
<li>Array elements will no longer have to be all of the same type. Caveats listed below:</li>
<ol type="a">
<li>Mixing elements of different types will increase memory consumption</li>
<li>The increased memory footprint will not revert even if the array is later set to elements all of the same type</li>
</ol>
<li>An array can be declared without specifying any dimensions; in this case the array will be one-dimensional and be able to grow in size dynamically</li>
<li>Accessing an element beyond the nominal size of such an array will automatically increase the nominal size just enough to include that element. Caveats listed below:</li>
<ol type="a">
<li>The memory footprint may be twice as high than required for the current nominal size.</li>
<li>Growth of such an array is triggered by any access to an element beyond the nominal size</li>
<li>This includes tests such as <code>#ifdef(ARRAY[INDEX])</code></li>
</ol>
<li>When using square bracket notation, the keys do not necessarily have to be string literals, but can be arbitrary string expressions</li>
<li>When using dot notation, the indices must follow the generic rules for identifiers</li>
<li>When using square bracket notation, the keys do not necessarily have to be string literals, but can be arbitrary string expressions</li>
</ol>

Also, so-called dictionaries will be added, i.e. containers that map string keys to arbitrary-type values; if the syntax remains as currently implemented, it will be as follows:

<pre>
// create an empty dictionary
#declare Fnord = dictionary;

// create a dictionary with elements
#declare Fnord = dictionary {
["Foo"]: 42,
["Bar"]: sphere { <0,0,0>, 1 }
}

// alternative
#declare Fnord = dictionary {
.Foo: 42,
.Bar: sphere { <0,0,0>, 1 }
}

// access a dictionary element
#declare Fnord["Foo"] = 42;
#declare Answer = Fnord["Foo"];

// alternative
#declare Fnord.Foo = 42;
#declare Answer = Fnord.Foo;

// testing whether a dictionary contains a particular key
#ifdef (Fnord["Foo"]) ... #end
#declare FooKeyExists = defined(Fnord.Foo);

// removing a key from a dictionary
#undef Fnord["Foo"];
</pre>

@@ Line 4: / Line 4: @@
 {{#indexentry:dictionary, array}}
 {{#indexentry:array}}
 <p>You may declare arrays of identifiers with up to five dimensions. Any item that can be declared as an identifier can be declared in an array. Consequential to the improvements with the classic <code>array</code> container topology, a {{New}} feature in version 3.7.1 extended functionality to allow the creation of <code>dictionary</code> container types. Dictionaries can be used for mapping string keys to arbitrary-type values.</p>
@@ Line 91: / Line 95: @@
        <li>When using <em>square bracket notation</em> the keys do not necessarily have to be string literals, they can also be arbitrary string expressions.</li>
        <li>If using <em>dot notation</em> the indices must follow the generic rules for identifiers.</li>
      </ul>
 </ul>
@@ Line 126: / Line 131: @@
 // remove a key from a dictionary
 #undef Fnord["Foo"];
 </pre>

@@ Line 80: / Line 80: @@
 <p>Any legitimate use of the <code>#declare</code> directive can also be put into an array. In other words, you can also create multidimensional arrays by making an array of arrays.</p>
-<p>Additional points to consider are as follows:</p>
+<p>{{New}} to version 3.7.1 points to also consider:</p>
-<ol>
+<ul>
-   <li>Array elements will no longer have to be all of the same type. <em>Caveats</em> listed below:</li>
+   <li>Array elements no longer have to be all of the same type. However, be aware that mixing elements of different types will increase memory consumption. That increased memory footprint will not revert even if the array is later set to elements all of the same type.</li>
-  <ol type="a">
+   <li>An array can be declared without specifying any dimensions; in this case the array will be one-dimensional and be able to grow in size dynamically.</li>
-    <li>Mixing elements of different types will increase memory consumption</li>
+   <li>Accessing an element beyond the nominal size of such an array will automatically increase the nominal size just enough to include that element.</li>
-    <li>The increased memory footprint will not revert even if the array is later set to elements all of the same type</li>
+   <li>The memory footprint may be <em>twice</em> as high than required for the current nominal size.</li>
-  </ol>
+  <li>Growth of such an array is triggered by <em>any</em> access to an element beyond the nominal size, this includes tests such as <code>#ifdef(ARRAY[INDEX])</code>.</li>
-   <li>An array can be declared without specifying any dimensions; in this case the array will be one-dimensional and be able to grow in size dynamically</li>
+   <li>The following applies to <code>dictionary</code> containers <em>only</em>:</li>
-   <li>Accessing an element beyond the nominal size of such an array will automatically increase the nominal size just enough to include that element. <em>Caveats</em> listed below:</li>
+    <ul>
-   <ol type="a">
+      <li>When using <em>square bracket notation</em> the keys do not necessarily have to be string literals, they can also be arbitrary string expressions.</li>
-    <li>The memory footprint may be <em>twice</em> as high than required for the current nominal size.</li>
+      <li>If using <em>dot notation</em> the indices must follow the generic rules for identifiers.</li>
-    <li>Growth of such an array is triggered by <em>any</em> access to an element beyond the nominal size</li>
+    </ul>
-    <li>This includes tests such as <code>#ifdef(ARRAY[INDEX])</code></li>
+</ul>
 <p>Additional usage examples are as follows:</p>

@@ Line 4: / Line 4: @@
 {{#indexentry:dictionary, array}}
 {{#indexentry:array}}
-<p>You may declare arrays of identifiers with up to five dimensions. Any item that can be declared as an identifier can be declared in an array. A {{New}} feature in version 3.7.1 extends <code>array</code> functionality to allow the creation of <code>dictionary</code> container types. Dictionaries can support mapping string keys to arbitrary-type values.</p>
+<p>You may declare arrays of identifiers with up to five dimensions. Any item that can be declared as an identifier can be declared in an array. Consequential to the improvements with the classic <code>array</code> container topology, a {{New}} feature in version 3.7.1 extended functionality to allow the creation of <code>dictionary</code> container types. Dictionaries can be used for mapping string keys to arbitrary-type values.</p>
 {{#indexentry:Array, declaring}}
 {{#indexentry:Declaring, arrays}}
 ==Declaring Arrays==
-<p>The syntax for declaring an <code>array</code> is as follows:</p>
+<p>The syntax is as follows:</p>
 <pre>
@@ Line 19: / Line 19: @@
 ARRAY_ITEM:
    RVALUE | ARRAY_INITIALIZER
 DICTIONARY_DECLARATION:
    #declare IDENTIFIER = dictionary; | #local IDENTIFIER = dictionary;
@@ Line 38: / Line 33: @@
 <p>Where IDENTIFIER is the name of the identifier and INT is a valid float expression, internally truncated to an integer, and used to specify the size of the array.</p>
-<p class="Note"><strong>Note:</strong> In previous versions IDENTIFIER names <em>were</em> limited to 40 characters. There has been a {{Change}} that removes than restriction.</p>
+<p class="Note"><strong>Note:</strong> In previous versions IDENTIFIER names <em>were</em> limited to 40 characters. There has been a {{Change}} removing that restriction.</p>
 <p>See [[Reference:Array#Array Initializers|Array Initializers]] for more about the optional <em>ARRAY_INITIALIZER</em> parameter.</p>
-<p>Here is an example of a one-dimensional, uninitialized array:</p>
+<p>Consider the following example of a one-dimensional, uninitialized array:</p>
 <pre>
@@ Line 48: / Line 43: @@
 </pre>
-<p>It declares an uninitialized array of ten elements. The elements are referenced as <code>MyArray[0]</code> through <code>MyArray[9]</code>. As yet, the type of the elements are undetermined. Once you have initialized any element of the array, all other elements can only be defined as that type.</p>
+<p>It declares an uninitialized array of ten elements. The elements are referenced as <code>MyArray[0]</code> through <code>MyArray[9]</code>. As yet, the type of the elements are undetermined. Once you have initialized any element of the array, all other elements can only be defined as that type. Any attempt to reference an uninitialized element results in an error. More below:</p>
 <pre>
@@ Line 75: / Line 69: @@
 </pre>
-<p>The <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|#ifdef]]</code> and <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|#ifndef]]</code> directives can be used to check whether a specific element of an array has been declared. For methods to determine the size of an array look in the float section for <code>[[Reference:Numeric Expressions#Functions|dimensions]]</code> and
+<p>The <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|#ifdef]]</code> and <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|#ifndef]]</code> directives can be used to check whether a specific element of an array has been declared. See also: <code>[[Reference:Numeric Expressions#Functions|dimensions]]</code> and <code>[[Reference:Numeric Expressions#Functions|dimension_size]]</code> for additional information about the methods used to determine the size of arrays.</p>
 <p>Large uninitialized arrays do not take much memory. Internally they are arrays of pointers so they probably use just 8 bytes per element. Once initialized with values, they consume memory depending on what they contain.</p>
-<p>The rules for local vs. global arrays are the same as any other identifier.</p>
+<p>The rules for <em>local</em> vs <em>global</em> arrays are the same as any other identifier.</p>
 <p class="Note"><strong>Note:</strong> This applies to the entire array. You cannot mix local and global
@@ Line 87: / Line 80: @@
 <p>Any legitimate use of the <code>#declare</code> directive can also be put into an array. In other words, you can also create multidimensional arrays by making an array of arrays.</p>
-<p>When declaring <em>dictionaries</em> be aware of the following:</p>
+<p>Additional points to consider are as follows:</p>
 <ol>
    <li>Array elements will no longer have to be all of the same type. <em>Caveats</em> listed below:</li>
@@ Line 106: / Line 99: @@
 </ol>
-<p>Here are some usage examples:</p>
+<p>Additional usage examples are as follows:</p>
 <pre>
@@ Line 132: / Line 125: @@
 #declare Answer = Fnord.Foo;
-// testing whether a dictionary contains a particular key
+// test whether a dictionary contains a particular key
 #ifdef (Fnord["Foo"]) ... #end
 #declare FooKeyExists = defined(Fnord.Foo);
-// removing a key from a dictionary
+// remove a key from a dictionary
 #undef Fnord["Foo"];
 </pre>
 {{#indexentry:Array, initialization}}
 {{#indexentry:Initialization, arrays}}
 ==Array Initializers==
 <p>Because it can be cumbersome to individually initialize the elements of an array, you may initialize it as it is created using <code>array</code> initializer syntax.</p>

@@ Line 25: / Line 25: @@
 <pre>
 DICTIONARY_DECLARATION:
-   #declare | #local IDENTIFIER = dictionary; |
+   #declare IDENTIFIER = dictionary; | #local IDENTIFIER = dictionary;
-   #declare | #local IDENTIFIER = dictionary DICTIONARY_INITIALIZER
+   #declare IDENTIFIER = dictionary DICTIONARY_INITIALIZER |
 DICTIONARY_INITIALIZER:
    {DICTIONARY_ITEM, [DICTIONARY_ITEM, ]... }

@@ Line 25: / Line 25: @@
 <pre>
 DICTIONARY_DECLARATION:
-   #[declare | local] IDENTIFIER = dictionary; |
+   #declare | #local IDENTIFIER = dictionary; |
-   #[declare | local] IDENTIFIER = dictionary DICTIONARY_INITIALIZER
+   #declare | #local IDENTIFIER = dictionary DICTIONARY_INITIALIZER
 DICTIONARY_INITIALIZER:
    {DICTIONARY_ITEM, [DICTIONARY_ITEM, ]... }

@@ Line 49: / Line 49: @@
 #declare OneRow  = MyGrid[2]  //this is illegal
 </pre>
-<p>The <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|:#ifdef|#ifdef]]</code> and <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|:#ifndef|#ifndef]]</code> directives can be used to check whether a specific element of an array has been declared. For methods to determine the size of an array look in the float section for <code>[[Reference:Numeric Expressions#Functions|:dimensions|dimensions]]</code> and
+<p>The <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|#ifdef]]</code> and <code>[[Reference:Conditional Directives#The ifdef and ifndef Directives|#ifndef]]</code> directives can be used to check whether a specific element of an array has been declared. For methods to determine the size of an array look in the float section for <code>[[Reference:Numeric Expressions#Functions|dimensions]]</code> and
-<code>[[Reference:Numeric Expressions#Functions|:dimension_size|dimension_size]]</code>.</p>
+<code>[[Reference:Numeric Expressions#Functions|dimension_size]]</code>.</p>
 <p>Large uninitialized arrays do not take much memory. Internally they are arrays of pointers so they probably use just 4 bytes per element. Once initialized with values, they consume memory depending on what they contain.</p>

@@ Line 2: / Line 2: @@
 {{#indexentry:Array, identifiers}}
 {{#indexentry:array}}
-<p>You may declare arrays of identifiers with up to five dimensions. Any item that can be declared as an identifier can be declared in an array. See also: this {{New}} feature for version 3.7.1 [[Reference Talk:Array#Dictionary Data Types|Dictionary Data Types]].</p>
+<p>You may declare arrays of identifiers with up to five dimensions. Any item that can be declared as an identifier can be declared in an array. See also: this {{New}} feature for version 3.7.1 [[Reference:Array#Dictionary Data Types|Dictionary Data Types]].</p>
 {{#indexentry:Array, declaring}}

@@ Line 2: / Line 2: @@
 {{#indexentry:Array, identifiers}}
 {{#indexentry:array}}
-<p>You may declare arrays of identifiers of up to five dimensions. Any
+<p>You may declare arrays of identifiers with up to five dimensions. Any item that can be declared as an identifier can be declared in an array. See also: this {{New}} feature for version 3.7.1 [[Reference Talk:Array#Dictionary Data Types|Dictionary Data Types]].</p>
 {{#indexentry:Array, declaring}}
@@ Line 19: / Line 18: @@
 </pre>
-<p>Where IDENTIFIER is the name of the identifier up to 40 characters long
+<p>Where IDENTIFIER is the name of the identifier up to 40 characters long and INT is a valid float expression which is internally truncated to an integer which specifies the size of the array. The optional <em>ARRAY_INITIALIZER</em> is discussed in the next section <!--<linkto "Array Initializers">Array Initializers</linkto>--->[[Reference:Array#Array Initializers|Array Initializers]]. Here is an example of a one-dimensional, uninitialized array.</p>
 and INT is a valid float expression which is internally truncated to an
 <pre>
 #declare MyArray = array[10]
 </pre>
-<p>This declares an uninitialized array of ten elements. The elements are
+<p>This declares an uninitialized array of ten elements. The elements are referenced as <code>MyArray[0]</code> through <code>MyArray[9]</code>. As yet, the type of the elements are undetermined. Once you have initialized any element of the array, all other elements can only be defined as that type. An attempt to reference an uninitialized element results in an error. For
 example:</p>
 <pre>
 #declare MyArray = array[10]
@@ Line 42: / Line 35: @@
 </pre>
-<p>Multi-dimensional arrays up to five dimensions may be declared. For
+<p>Multi-dimensional arrays up to five dimensions may be declared. For example:</p>
 <pre>
 #declare MyGrid = array[4][5]
 </pre>
-<p>declares a 20 element array of 4 rows and 5 columns. Elements are
+<p>declares a 20 element array of 4 rows and 5 columns. Elements are referenced from <code>MyGrid[0][0]</code> to <code>MyGrid[3][4]</code>. Although it is permissible to reference an entire array as a whole, you may not reference just one dimension of a multi-dimensional array. For example:</p>
 referenced from <code>MyGrid[0][0]</code> to <code>MyGrid[3][4]</code>.
 <pre>
 #declare MyArray = array[10]
@@ Line 63: / Line 52: @@
 <code>[[Reference:Numeric Expressions#Functions|:dimension_size|dimension_size]]</code>.</p>
-<p>Large uninitialized arrays do not take much memory. Internally they are
+<p>Large uninitialized arrays do not take much memory. Internally they are arrays of pointers so they probably use just 4 bytes per element. Once initialized with values, they consume memory depending on what they contain.</p>
 arrays of pointers so they probably use just 4 bytes per element. Once
-initialized with values, they consume memory depending on what you put in
+<p>The rules for local vs. global arrays are the same as any other identifier.</p>
-them.</p>
 <p class="Note"><strong>Note:</strong> This applies to the entire array. You cannot mix local and global
-elements in the same array. See <!--<linkto "#declare vs. #local">#declare vs. #local</linkto>--->[[Reference:Declare and Local Directives#declare vs. local|#declare vs. #local]] for
+elements in the same array. See <!--<linkto "#declare vs. #local">#declare vs. #local</linkto>--->[[Reference:Declare and Local Directives#declare vs. local|#declare vs. #local]] for information on identifier scope.</p>
 information on identifier scope.</p>
 <p>Any legitimate use of the <code>#declare</code> directive can also be put into an array. In other words, you can also create multidimensional arrays by making an array of arrays.</p>
@@ Line 78: / Line 65: @@
 ==Array Initializers==
-<p>Because it is cumbersome to individually initialize the elements of an
+<p>Because it is cumbersome to individually initialize the elements of an array, you may initialize it as it is created using array initializer syntax. For example:</p>
 <pre>
 #include &quot;colors.inc&quot;
@@ Line 86: / Line 71: @@
 </pre>
-<p>Multi-dimensional arrays may also be initialized this way. For
+<p>Multi-dimensional arrays may also be initialized this way. For example:</p>
 <pre>
 #declare Digits =
@@ Line 98: / Line 82: @@
 </pre>
-<p>The commas are required between elements and between dimensions as shown
+<p>The commas are required between elements and between dimensions as shown in the example.</p>
 in the example.</p>
 ==Dictionary Container Types==
-<p>A {{New}} version 3.7.1 feature allows arrays to be modified as follows:</p>
+<p>A {{New}} version 3.7.1 feature extends <code>array</code> functionality to allow the creation of <code>dictionary</code> container types. Dictionaries can support mapping string keys to arbitrary-type values. The syntax is as follows:</p>
 <ol>
@@ Line 124: / Line 122: @@
 </ol>
-<p>Also, so-called <em>dictionaries</em> will be added, i.e. containers that map string keys to arbitrary-type values; if the syntax remains as currently implemented, it will be as follows:</p>
+<p>See the following usage examples:</p>
 <pre>