
Calling Sequence


Array(indfncs, dims, init, opts)


Parameters


indfncs



(optional) procedure(s); indexing function(s)

dims



(optional) range(s) of integers; dimension(s)

init



(optional) Maple procedure, function, table, array, list, Array, set of equations, expression of type algebraic; initial values for the Array

opts



(optional) equations of the form keyword = value; specifies additional properties of the Array





Options



The opts parameter is used to specify one or more additional properties of the Array. If a property is included in the calling sequence, it must be an equation of the form keyword = value. The permissible options are described in this section.


Specifies the datatype of the Array elements, and can be one of integer[n], float[n], double, complex[n], or any Maple type specification (such as is accepted by type() or ::).


For integer[n], n can be 1, 2, 4, or 8, indicating the number of bytes per integer. For float[n] and complex[n], the only allowable value of n is currently 8. The double datatype is the same as the float[8] datatype. The default datatype is the Maple type anything.


Note: When the initializer is an existing Array, and datatype = value is not specified, the datatype is inherited from the initializer.


Specifies the storage of the Array. Permissible values are:

rectangular

triangular[upper]

triangular[lower]

triangular[upper, strict]

triangular[lower, strict]

Hessenberg[upper]

Hessenberg[lower]

band[b1, b2]

diagonal

sparse

sparse[upper]

sparse[lower]

empty






The default value of storage is determined by the last indexing function specified. If the initializer is an rtable (Array, Matrix, or Vector) and no storage option is included in the calling sequence, then the resulting Array will have sparse storage if the initializer has any kind of sparse storage; otherwise, the resulting Array has rectangular shape.


Specifies the internal ordering of the structure. Permissible values are C_order and Fortran_order. The default order is Fortran_order.


Note: When the initializer is an existing Array, and order is not specified, the order is inherited from the initializer.


Specifies whether the Array is mutable. Permissible values are true or false. If readonly=true is included in the calling sequence (or equivalently, just readonly, it specifies that the Array is immutable, in which case any attempt to modify an Array element will raise an exception.


Note: When the initializer is an existing Array, readonly is not inherited from the initializer, since a common use for copying an Array is to create a writable version of a readonly one.


Specifies the attributes with which the Array is created. Anything that is a valid argument to setattribute can appear as attribute values. The default is to have no attributes.


Note: When the initializer is an existing Array, and attributes are not specified, the attributes are inherited from the initializer.


If transpose or transpose=true is included in the calling sequence, it specifies that the initializer is to be transposed before filling in the Array (or determining its dimensions if no dimensions were specified). In other words, the initializer is assumed to be in columnmajor order.


An equation of the form shape=name or shape=list or shape=procedure specifies one or more builtin or userdefined indexing functions that determine the nonzero structure of the Array. If more than one indexing function is included, they must be entered as a list. The default shape is [] (none). For a full description and list of builtin indexing functions, see Array indexing functions.


Specifies the default value that unspecified Array elements are filled in with. This value must meet the same evaluation requirements as initializer values.


Note: The fill value is only used to fill those elements of the Array that are unspecified in spite of the indexing function. For instance, the fill value is not used to fill the lower triangle of an upper triangular Array. For a sparse Array, the fill value is always ignored.


Note: The transpose and fill options are only constructor options. They are not returned as part of the result of an op(4, ...) call.



Description


•

The Array(..) function is the constructor for the Array data structure. Arrays are implemented as rtables and are distinct from other Maple objects such as arrays, tables, Matrices, and Vectors. Note that Array supersedes the deprecated array.

•

Each of the parameters in the calling sequence is optional. If no parameters are provided, an empty 0dimensional Array is returned.


If dims and init are not specified, or if only a scalar value is specified for init, a 0dimensional Array containing a single element is constructed.

•

The following sections describe permissible values for each parameter if it is included in the calling sequence.


Indexing functions are used to index into an Array to retrieve or store a value. An Array has zero or more indexing functions, which are specified by name when the Array is constructed. The name of an indexing functions is always of the form "index/indfnc". When specifying an indexing function indfnc in the calling sequence, only the indfnc part of the name is specified.


Note: If the initializer (see the Options section) is an existing Array, the indexing functions are not inherited.


The indexing function can be builtin or userdefined. For more information regarding indexing functions, see Array indexing functions.


The number of dimensions of an Array can range from 0 to 63. Each of the dimensions dims in the calling sequence must be specified as a range of integers.


The init parameter specifies the initial values of the Array in one of the following formats.

–

list of values (in the case of a multidimensional Array, nested lists are used)

–

existing Array, Matrix, or Vector

–

set of equations of the form (indices) = value

–

initializer function (procedure)


If the initial values are specified as a list of values or an existing Array, Matrix, or Vector, the number of dimensions of the initial values must match the bounds (if they were specified).


If the initial values are specified as a procedure, table, or set of equations, the dimensions must be specified, and the indices of the initializers must fit within those dimensions.


If a procedure is specified, that function is called for each member of a set of indices, determined by the indexing function. The function must return a value for the specified element of the Array.


Each initial value can be any Maple expression, but this expression must be able to be evaluated to a value of the datatype of the Array (see Options). For hardware floatingpoint Arrays, this must be a hardware floatingpoint number, or one of the special expressions representing undefined or +infinity. For hardware integer Arrays, the expressions must be able to be evaluated to a machine integer. Failure to evaluate to the datatype will generate an error.


The list form of initializer for a two or more dimensional Array is specified in rowmajor order unless the transpose option (see Options) is specified.


If the bounds are determined from the list form of the initializer, then the bounds of each dimension are determined from the first object in that dimension. For example, for a 2dimensional Array, the number of rows is determined by the number of sublists in the main list. The number of columns is determined by the number of elements in the first sublist, and so on for higher dimensioned Arrays. If transpose is specified, then dimension determination starts with the last dimension (i.e. the number of columns is determined by the number of sublists in the main list, and so on).


If there are too few initializer values for a dimension, the remainder of that dimension is filled with an appropriate default for the type of Array (either an appropriate zero, the value specified by the fill option (see Options), or a value determined by the indexing functions). If there are too many initializer values, an exception is raised.


A 0dimensional Array can be initialized by specifying a literal value (i.e. a 0level nesting of lists). For example, Array(2) creates a 0dimensional Array containing the single element, 2. This form can only be used if the value is of a type that cannot be confused with one of the other forms of initializer. If it is desired to initialize a 0dimensional Array with a more complex type, the fill option should be used (e.g. Array(fill=[2, 3]) would create a 0dimensional Array containing the single value [2, 3]).


An Array with scalar storage (see Options) is initialized in the usual way. Any form of initializer works, although the most efficient method would be a set which contains one equation, or by using the fill parameter.


When the initializer is a string, the dimension must either match the length of the string, or be omitted. Similarly, the datatype must be either explicitly specified as integer[1], or left unspecified.

•

After creation, it is possible to change the entries and some of the properties of the Array. See Array assignment and Array options for more information.

•

For additional information on accessing elements or groups of elements of a Array, see Array indexing.

•

Only small Arrays are displayed inline in Maple. A small Array is defined as a 1 or 2dimensional object whose dimension(s) are in the range 1..25 (TTY version of Maple) or the range 1..10 (GUI version of Maple). Any Array whose dimension(s) are larger than this size is displayed by using a placeholder. For information on how to view the contents of a placeholder, see structuredview.


You can display larger Arrays inline by using the interface(rtablesize=value) command, where value is an integer that represents the upper bound of the dimension range.


To change the environment so that Maple always displays rtables inline, include the interface(rtablesize=infinity) command in a Maple initialization file (see maple).



Thread Safety


•

The Array command is threadsafe as of Maple 15.



Examples


Construct a simple Array with three elements:
>

$A\u2254\mathrm{Array}\left(\left[1\,2\,3\right]\right)$

${A}{\u2254}\left[\begin{array}{ccc}{1}& {2}& {3}\end{array}\right]$
 (1) 
Return the bounds of each dimension of A:
>

$\mathrm{ArrayDims}\left(A\right)$

Return upper bound of the dimension of A:
>

$\mathrm{upperbound}\left(A\right)$

Construct another Array B:
>

$B\u2254\mathrm{Array}\left(2..3\,1..1\,\left[\left[1\,2\,3\right]\,\left[4\,5\,6\right]\right]\right)$

Evaluate the number of dimensions of B:
>

$\mathrm{ArrayNumDims}\left(B\right)$

Return the number of elements of B:
>

$\mathrm{ArrayNumElems}\left(B\right)$

An upper triangular Array C, where fill specifies the values at each entry:
>

$C\u2254\mathrm{Array}\left(\mathrm{triangular}\left[\mathrm{upper}\right]\,1..3\,1..4\,\mathrm{fill}=1\right)$

${C}{\u2254}\left[\begin{array}{cccc}{1}& {1}& {1}& {1}\\ {0}& {1}& {1}& {1}\\ {0}& {0}& {1}& {1}\end{array}\right]$
 (6) 
A symmetric twodimensional Array:
>

$F\u2254\mathrm{Array}\left(\mathrm{symmetric}\,1..3\,1..3\right)$

${F}{\u2254}\left[\begin{array}{ccc}{0}& {0}& {0}\\ {0}& {0}& {0}\\ {0}& {0}& {0}\end{array}\right]$
 (7) 
Instead of using the fill option to assign the same value at each entry, you can opt for the following method:
>

$F\left[1,1\right]\u22541\:$

>

$F\left[1,2\right]\u22542\:$

>

$F\left[1,3\right]\u22543\:$

$\left[\begin{array}{ccc}{1}& {2}& {3}\\ {2}& {0}& {0}\\ {3}& {0}& {0}\end{array}\right]$
 (8) 
Specifying data type of each element using the datatype option.
>

$G\u2254\mathrm{Array}\left(\left[1.2\,1\,4.78\right]\,\mathrm{datatype}=\mathrm{float}\left[8\right]\right)$

${G}{\u2254}\left[\begin{array}{ccc}{1.20000000000000}& {1.}& {4.78000000000000}\end{array}\right]$
 (9) 
Creating an integer[1] Array from a string.
>

$A\u2254\mathrm{Array}\left(''Hello''\right)$

${A}{\u2254}\left[\begin{array}{ccccc}{72}& {101}& {108}& {108}& {111}\end{array}\right]$
 (10) 
>

$\mathrm{String}\left(A\right)$



Compatibility


•

The datatype option was updated in Maple 2015.

•

The shape option was introduced in Maple 2024.



