ArrayTools - Maple Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Programming : Low-level Manipulation : Matrices, Vectors, and Arrays : ArrayTools : ArrayTools/Alias

ArrayTools

  

Alias

  

provide different view of rectangular Matrix, Vector, or Array

 

Calling Sequence

Parameters

Description

Examples

Compatibility

Calling Sequence

Alias(A, offset, bounds, orient, order, datatype, options)

Parameters

A

-

rectangular storage Matrix, Vector, or Array of any data type and ordering

offset

-

(optional) integer; offset into data for creation of new rtable

bounds

-

(optional) list of integers or ranges of integers; bounds for the new alias

orient

-

(optional) orientation of the output Vector alias ('row' or 'column'). This parameter can be specified only if the output is a Vector

order

-

(optional) ordering of the output alias ('C_order' or 'Fortran_order')

datatype

-

(optional) hardware datatype of the output alias

options

-

other options

Description

• 

The Alias command provides a different view of the same data for an existing Matrix, Vector, or Array. The input Matrix, Vector, or Array must have rectangular (dense) storage.

• 

Alias does not change the underlying data of the input rtable object. Instead, Alias casts it to another rtable object with the same data but a different description that can be specified through options. In contrast to ArrayTools[Reshape], Alias does not create a copy of the underlying data, but instead creates and returns a new rtable object which references the same block of internal data as the input. As such, changes to the contents of the view also affect the contents of the original input rtable, and vice-versa. A limited form of casting to a different data type is also available from ArrayTools[ComplexAsFloat].

  

Note: If the original rtable has an indexing function, then you must create the alias as readonly. More information on this is provided for the readonly option.

• 

If the original Matrix, Vector, or Array has been unassigned, it will still exist in the attributes of the view, but changing the data will only affect the current view and other views defined on the same rtable.

  

Important: Use this function with caution. If you remove the table reference from the attributes and unassign the original input object, accessing or changing the data in the view will crash Maple. If a persistent and permanent copy of the data is desired, then use copy, ArrayTools[Copy], or ArrayTools[Reshape] instead.

• 

The offset option is a nonnegative integer value that specifies the offset into the input at which the output alias begins. For example, an offset of 4 allows creation of an alias of the last 6 elements of a 10 element Vector as a 6 element Vector.

• 

The bounds option is a list of integers or integer ranges that specify the Matrix, Vector, or Array bounds of the output alias. If bounds is a single integer value, then a Vector alias is returned. If bounds is a list of two integer values, then a Matrix alias is returned. If there are more than two values, or any one of the bounds is specified as a range a..b (where a, b are both integers with a<b), then the output is an Array alias.

  

In the case where bounds is a single element list with an integer value, the output will be a Vector alias, and the orientation can be set by passing orient with a value of either 'row' or 'column'.

  

The combination of the new bounds and the offset must not extend past the data storage for the input rtable. If it does, an error is returned.

• 

The order option describes the order of the output alias, and can be either 'C_order' or 'Fortran_order'. The default value is chosen to be the same order as used for the input rtable.

  

Note: No underlying data is changed by this operation, so this does not provide an order conversion, but rather a new view on the existing unchanged data. For more information on ordering, see the rtable order help page.

• 

The datatype option describes the hardware datatype of the output alias, and can be one of 'float[8]', 'float[4]', 'complex[8]', 'integer[8]', 'integer[4]', 'integer[2]', or 'integer[1]'.  The default value is the same datatype as the input, A.

  

Note: No underlying data is changed by this operation, so this does not provide data conversion.  Aliasing an 8 element integer[1] byte array to a float[8] array will result in a single element float[8] array with its value given by the hardware byte pattern in the original array.  As such the user must be aware of potential endianness issues.

  

As hinted at above, different datatypes require different numbers of bytes of storage.  The specified dimensions designate the input selection area, and the output alias' size will be adjusted accordingly.  For example aliasing the first two elements of a complex[8] array will result in an integer[1] array with 16 elements, a integer[2] array with 8 elements, a float[8] array with 2 elements, etc.

• 

readonly=true or false

  

This option specifies whether the created alias is readonly. If the original rtable is readonly, then specifying this option to be false results in an error.

  

Important: This option must be explicitly stated when aliasing to an rtable with an indexing function, as the alias will not have the indexing function, so it is possible to corrupt the indexed nature of the original rtable by assigning to an alias created with readonly=false.

• 

This function is part of the ArrayTools package, so it can be used in the short form Alias(..) only after executing the command with(ArrayTools).  However, it can always be accessed through the long form of the command by using ArrayTools[Alias](..).

Examples

withArrayTools&colon;

interfacertablesize&equals;12

10

(1)

Viewing a 10 element Vector as a 2 x 5 Matrix - shown for both orderings

VVector&lsqb;row&rsqb;10&comma;i&rarr;i

V12345678910

(2)

AfAliasV&comma;2&comma;5&comma;Fortran_order

Af13579246810

(3)

AcAliasV&comma;2&comma;5&comma;C_order

Ac12345678910

(4)

Viewing the last 6 elements of a 10 element Vector as a 6 element Array

A6AliasV&comma;4&comma;1..6

A65678910

(5)

typeA6&comma;Array

true

(6)

Viewing a 3 x 4 Matrix as a 12 element row Vector

AMatrix3&comma;4&comma;i&comma;j&rarr;10i&plus;j&comma;order&equals;C_order

A111213142122232431323334

(7)

VAliasA&comma;12&comma;row

V111213142122232431323334

(8)

op0&comma;V

Vectorrow

(9)

or as an Array

VAliasA&comma;1..12

V111213142122232431323334

(10)

op0&comma;V

Array

(11)

The data itself does not move, but specification of different bounds can make it appear to. Conversion of the Matrix A to a 2-D Array with indices starting at zero

ArAliasA&comma;0..2&comma;0..3

ArArray0..2&comma;0..3&comma;0&comma;0&equals;11&comma;0&comma;1&equals;12&comma;0&comma;2&equals;13&comma;0&comma;3&equals;14&comma;1&comma;0&equals;21&comma;1&comma;1&equals;22&comma;1&comma;2&equals;23&comma;1&comma;3&equals;24&comma;2&comma;0&equals;31&comma;2&comma;1&equals;32&comma;2&comma;2&equals;33&comma;2&comma;3&equals;34&comma;order&equals;C_order&comma;attributes&equals;source_rtable&equals;111213142122232431323334

(12)

A1&comma;1&comma;Ar0&comma;0

11&comma;11

(13)

A2&comma;4&comma;Ar1&comma;3

24&comma;24

(14)

A3&comma;2&comma;Ar2&comma;1

32&comma;32

(15)

Note that the data is shared between the input rtable and its view.

AMatrix3&comma;4&comma;i&comma;j&rarr;10i&plus;j&comma;order&equals;C_order

A111213142122232431323334

(16)

VAliasA&comma;12&comma;row

V111213142122232431323334

(17)

A1&comma;10&colon;A2&comma;30&colon;

V

0121314212202431323334

(18)

Obtain a transpose that changes with the original Matrix.

AMatrix3&comma;4&comma;i&comma;j&rarr;10i&plus;j&comma;order&equals;C_order

A111213142122232431323334

(19)

AtAliasA&comma;4&comma;3&comma;Fortran_order

At112131122232132333142434

(20)

A&period;At

63011301630113020302930163029304230

(21)

A1&comma;10&colon;A1&comma;20&colon;A1&comma;30&colon;A1&comma;41&colon;

A&comma;At

00012122232431323334&comma;02131022320233312434

(22)

A&period;At

1243424203029303429304230

(23)

Another example using the order option. A has the default Fortran order.

AMatrix4&comma;4&comma;i&comma;j&rarr;4j1&plus;i

A15913261014371115481216

(24)

AliasA&comma;C_order

12345678910111213141516

(25)

BArray3.14&comma;2.22&comma;datatype&equals;float&lsqb;8&rsqb;

B3.140000000000002.22000000000000

(26)

writebytesalias_test&comma;B

16

(27)

fclosealias_test

AArray1..16&comma;datatype&equals;integer&lsqb;1&rsqb;

A 1 .. 16 ArrayData Type: integer1Storage: rectangularOrder: Fortran_order

(28)

readbytesalias_test&comma;A

1 .. 16 ArrayData Type: integer1Storage: rectangularOrder: Fortran_order

(29)

ArrayTools:-AliasA&comma;float&lsqb;8&rsqb;

3.140000000000002.22000000000000

(30)

ArrayTools:-AliasA&comma;complex&lsqb;8&rsqb;

3.140000000000002.22000000000000I

(31)

Note that convert(..., bytes) gives unsigned integer results that need to be scaled to fit into an integer[1] array.  You may also need to reorder the elements to get the correct endianness.

dataconvert3.14&comma;bytes

data64&comma;9&comma;30&comma;184&comma;81&comma;235&comma;133&comma;31

(32)

AArraymapx&rarr;`if`127<x&comma;x256&comma;x&comma;data&comma;datatype&equals;integer&lsqb;1&rsqb;

A6493072812112331

(33)

BArrayTools:-FlipDimensionA&comma;2

B3112321817230964

(34)

AliasB&comma;float&lsqb;8&rsqb;

3.14000000000000

(35)

Compatibility

• 

The readonly option was introduced in Maple 16.

• 

For more information on Maple 16 changes, see Updates in Maple 16.

See Also

ArrayTools

ArrayTools[ComplexAsFloat]

ArrayTools[Reshape]

C_order

Fortran_order

interface

Matrix

Vector

 


Download Help Document

Was this information helpful?



Please add your Comment (Optional)
E-mail Address (Optional)
What is ? This question helps us to combat spam