Writing to Arrays

Local arrays in ILNumerics can be modified after creation. The mutability is basically provided by only two member functions:

• A.SetValue(value, indices) changes the value of a single element and expects a single system type as value. SetValue exposes ILNumericsV4 array style indexing semantics. Just like its counterpart GetValue(), SetValue() interacts with system types and is mostly useful for Array Import and Export. It is not further considered here.
• A.SetRange(value, range) allows the modification of arbitrary ranges of A. SetRange() fully supports all features of both: numpy arrays and ILNumericsV4 (including Matlab(R)-style) arrays.

In C# and all languages which support them, indexer offer a more convenient syntax for left side assignments. A[range] = value, however, is just an alias for A.SetRange(value,range).

Range Modification Options

A.SetRange(value,range) receives the definition of the range to be altered and the definition of the new values.

• Range Definition: All rules for Subarray Definitions apply for modification ranges as well. The range definition may include strings, constants, numeric variables and arrays, r([start],[end]) range definitions, stepped range defintions r([start],[step],[end]) and the keywords full and end. For an overview of all subarray options consult the Quick Start section!

• Value Definition: The arrays containing the new values must match the size and shape defined by the range definition. The only exception is a scalar array. In that case, the value is assigned to all elements addressed by the range. The type of the value must match the element type of the destination array or an implicit conversion must exist. Note: most numeric system types implicitely convert to a double array.

Basic Modification Examples

The following examples demonstrate some basic array altering techniques. For simplicitiy reasons, we use the array indexer of C#. The same functionality could be achieved by utilizing the SetRange function.

Expanding Arrays

If at least one of the indices from the range definition lays outside of the current array dimension limits, the array is resized automatically to match the range requested. New elements created that way receive the default value of the element type, for numeric arrays:  

Changing the size of an array that way is a costly operation from a performance point of view. Frequent expanding modifications should be prevented by first creating an array large enough for all future changes and inserting new elements than. If one can not prevent from expanding an existing array, it is better to start inserting elements with the outermost element. That way, the array is expanded to the final size immediately.

Removing from Arrays

Parts of an array can be removed by assigning null or an empty array. The range definition must address the full dimension - for all dimensions except the one, which is to be removed. We demonstrate this with the array from the example above:

Note, the last dimension is a singleton dimension now. It is not removed automatically.

Removals are triggered by assigning null or an empty array. Just like all size changing operations, removals are costly as well. If needed frequently, consider creating an array of the needed size and copying all elements from the source array at once.

Special Case: Remove by Sequential Indices

in strict correspondence to reshaping range definitions on read access, modifying an array by the specification of a single dimension only makes ILNumerics interprete the elements in the single range as sequential indices. This works as expected as long as the modification does only alter existing elements: