Skip to main content

Multidimensional Arrays

InterSystems IRIS® data platform includes support for multidimensional arrays. A multidimensional array is a persistent variable consisting of one or more elements, each of which has a unique subscript. You can intermix different kinds of subscripts. An example is the following MyVar array:

  • MyVar

  • MyVar(22)

  • MyVar(-3)

  • MyVar(“MyString”)

  • MyVar(-123409, “MyString”)

  • MyVar(“MyString”, 2398)

  • MyVar(1.2, 3, 4, “Five”, “Six”, 7)

The array node MyVar is an ObjectScript variable and follows the conventions for that variable type.

The subscripts of MyVar are positive and negative numbers, strings, and combinations of these. A subscript can include any characters, including Unicode characters. A numeric subscript is stored and referenced as a canonical number. A string subscript is stored and referenced as a case-sensitive literal. A canonical number (or a number that reduces to a canonical number) and a string containing that canonical number are equivalent subscripts.

What Multidimensional Arrays Are

Succinctly, multidimensional arrays are persistent, n-dimensional arrays that are denoted through the use of subscripts. Individual nodes are also known as “globals” and are the building block of InterSystems IRIS data storage. They have other characteristics as well:

  • They exist in tree structures.

  • They are sparse.

  • They are one of three basic kinds.

Multidimensional Tree Structures

The entire structure of a multidimensional array is called a tree; it begins at the top and grows downwards. The root, MyVar above, is at the top. The root, and any other subscripted form of it, are called nodes. Nodes that have no nodes beneath them are called leaves. Nodes that have nodes beneath them are called parents or ancestors. Nodes that have parents are called children or descendants. Children with the same parents are called siblings. All siblings are automatically sorted numerically or alphabetically as they are added to the tree.

Sparse Multidimensional Storage

Multidimensional arrays are sparse. This means that the example above uses only seven reserved memory locations, one for each defined node. Further, since there is no need to declare arrays or specify their dimensions, there are additional memory benefits: no space is reserved for them ahead of time; they use no space until needing it; and all the space that they use is dynamically allocated. As an example, consider an array used to keep track of players’ pieces for a game of checkers; a checkerboard is 8 by 8. In a language that required an 8–by-8 checkerboard-sized array would use 64 memory locations, even though no more than 24 positions are ever occupied by checkers; in ObjectScript, the array would require 24 positions only at the beginning, and would need fewer and fewer during the course of the game.

Kinds of Multidimensional Arrays

Multidimensional arrays can be one of three basic kinds. In all of these cases, an array can be differentiated from a scalar by virtue of the fact that an array has one or more subscripts.

  • Any local variable with subscripts is an array. For example, creating x(1) defines x as an array.

  • Any global with subscripts is an array. For example, creating ^y(1) defines ^y as an array.

  • A property in a class can be a multidimensional array if it has the MultiDimensional keyword in its definition, for example:

    Property MyProp as %String [ MultiDimensional ];

    You can then set its value with a statement such as:

    myObj.MyProp(1) = "hello world"

    Note that multidimensional properties in persistent or serial classes are not saved to disk when an object is saved, unless custom code is written to save the property.

Manipulating Multidimensional Arrays

You can write to and read from them using the Read and Write commands respectively.

InterSystems IRIS provides a comprehensive set of commands and functions for working with multidimensional arrays:

  • Set places values in an array.

  • Kill removes all or part of an array structure.

  • Merge copies all or part of an array structure to a second array structure.

  • $Order and $Query allows you to iterate over the contents of an array.

  • $Data allows you to test for the existence of nodes in an array.

This set of commands and functions can operate on multidimensional globals and multidimensional local variables. Globals can be easily identified by their leading “^” (caret) character.

See Also

For further information on multidimensional arrays, see Using Globals.

FeedbackOpens in a new tab