Strings, Constants and Variables

Subarrays are created by use of the Subarray member function of any ILNumerics array. For languages which support them, indexer bring an even more convenient snytax.

Both methods use identical parameter specifications. The range definition is given for every dimension seperately. Ranges are described with strings or with regular code elements, like constants or variables. Most the time, defining ranges by constants or variables results in more shorter syntax. However, cases exist, where string definitions are convenient too. Therefore, we will describe both of them here.

All examples on this page use matrices for demonstration. However, all concepts described here apply for n-dimensional arrays as well.

Yielding single elements

Every parameter given to the Subarray function defines the range in the corresponding dimension. For single elements, every parameter will address a single location inside that dimension only. ILNumerics uses zero based indexing! The definition of every dimension can be given by

• a numeric constant, mostly integer constants, like 1, 2 etc,
• a numeric string, or
• any variable which evaluates to a scalar integer value.

Examples of subarray definitions in C#. The following matrix will be reused in subsequent examples below.

Every dimension can use its own method of definition, as shown in the last example. Of course, dynamic evaluation of the range is possible as well. Next, we use an integer variable and an (scalar) array of integer elements:

A special placeholder exists for addressing the last element of a dimension: 'end'

Yielding ranges

In addition to scalar dimension specifiers, each dimension specification of the Subarray function (or the C# indexer) can receive a range definition. This way, several locations of the corresponding dimension are extracted. A single range for each dimension may be defined in one of the following ways:

Defining dimension ranges by strings

Each string parameter for a single dimension can contain a comma seperated list of any of

• integer numbers explicitely counting the indices needed,
• a colon ':' as a special character substituting for the whole corresponding dimension,
• the 'end' keyword as a placeholder for the index of the last element in the corresponding dimension,
• a regular range definition in the format [start]:[end], which will expand to [start],[start+1],[start+2],...[end-1],[end] [start] and [end] must be integer numbers or the keyword 'end'.
• a regular stepped range definition in the format [start]:[step]:[end], which will expand to [start],[start+step],[start+2*step],...[start+?*step] until the number exeeds the end limit. start, step and end must be integer numbers. start and/or end may be the keyword 'end'. Otherwise they must fit inside the dimension length. step can be negative.

The following example constructs a matrix of size 3x4:

A subarray of the first (0) and third (2) column (0..2) is created:

The same result could be achieved by one of the following statements:

The next example demonstrates more advanced range definitions - yet only by using strings. For every dimension the full dimension as well as individual indices are addressed. Starting point is the matrix A above:

The rows count from the first to the last row and than back from the last to the first row. For columns the second (index 1), the last (index 3) and after that all columns are selected for the result, which will give the matrix above.

The same result can be produced with one of the following statements:

Defining ranges by constants or variables

String definitions can get cumbersome, especially if local variables come into play. Therefore, better methods exist. Besides the definition with strings, a range for every single dimension can be addressed by any of the following:

• Numeric constants of any numeric system type, evaluating to an integer value. Example: A[1,2];
• Variables of any numeric system type, evaluating to an integer value. Example:

  ILNumerics arrays of any numeric element type, of empty, scalar or vector shape. All elements must evaluate to an integer value. Example:
• Any system type, which implicitly converts to such ILNumerics array (system arrays, constants etc.)
• The 'full' member of the ILMath class. It serves as placeholder for 'the full dimension'. Example: A[full,0]; // extracts the first column of A
• The 'end' member of the ILMath class. It will be replaced with the index of the last element in the corresponding dimension. Example: A[full,end]; // extracts the last column of A
• A regular range definition. Such ranges are created by the r function. It allows for stepped and unstepped range definition. Details are found below.
• Any combination of the above variants. If more than one range is to be defined for one dimension, all definitions must be wrapped into a Cell by utilizing the cell function. It receives an arbitrary number of range definitions and joins them together for a single dimension. Example:

Another example: consider again the matrix A from the examples above. A loop iterates over the columns and transfers them into another matrix. Columns having an odd index are copied into the destination matrix at the corresponding position. For columns having an even index, the last column will be inserted instead.

Of course, easier ways exist to create the same result. Some examples:

or even more simple:

and without strings:

For details of the set methods, visit the Altering Arrays tutorial.

Addressing the last element by end

The end member serves as placeholder addressing the last element of the corresponding dimension. It may be used inside subarray range definitions for addressing indices relative to the last element. Example:

All basic operations (+,-,/,*) can be utilized in conjunction with end and any object, evaluating to an integer value. This includes numeric constants and scalar arrays:

Regular Ranges by r()

The r() function allows the definition of ranges at runtime. This method is recommended, especially whenever the range limit is not known at compile time. The method receives range definitions - similar to string definitions described above - in the following scheme: r(start,[step],end). Here, start and/or end must be one of the following:

• A scalar ILNumerics array of any type, evaluating to an integer value inside the limits of the corresponding dimension.
• Any system type, which implicitly converts to such a scalar array.
• The placeholder end, addressing the last element of the corresponding dimension.

Examples:

Nonconsecutive elements can be addressed by using the optional step parameter. step defines a step width between indices of yielded elements. If ommited, step defaults to 1. If the >end parameter evaluates to a smaller number than the start parameter, a negative number for step must be given in order to generate a reverse range.