4D Doc Center : Creating Arrays

4D v13.4

Creating Arrays

You create an array with one of the array declaration commands described in this chapter. The following table lists the array declaration commands:

Command	Creates or resizes an array of
ARRAY INTEGER	2-byte Integer values
ARRAY LONGINT	4-byte Integer values (*)
ARRAY REAL	Real values
ARRAY TEXT	Text values (up to 2 GB of text per element) (**)
ARRAY STRING	(obsolete in Unicode mode) (**)
ARRAY DATE	Date values
ARRAY BOOLEAN	Boolean values
ARRAY PICTURE	Pictures values
ARRAY POINTER	Pointer values

Each array declaration command can create or resize one-dimensional or two-dimensional arrays. For more information about two-dimensional arrays, see the section Two-dimensional Arrays.

(*) Longint arrays allows you to manipulate data of Time type. To display a Time array in a form, apply to the associated form object the display format &/x, in which x represents the number of the format in the Time formats list (by order of appearance). For example, &/4 will display the Hour Min format.

(**) Text and String arrays work with the same types of elements: characters.

In Unicode mode (default mode for databases created beginning with version 11 of 4D), there is no difference between Text and String arrays. The strLen parameter of the ARRAY STRING command is ignored. In this context, it is recommended to use Text arrays. The ARRAY STRING command is only kept for compatibility reasons.
In compatibility mode (non-Unicode), the ARRAY TEXT and ARRAY STRING commands differ:
- In a Text array, each element is of variable length and stores its characters in a separate part of memory. Each element of a Text array can contain up to 32,000 characters.
- In a String array, all elements have the same fixed length (the length passed in the strLen parameter when the array was created). All elements are stored one after the other in the same part of memory,which makes String arrays faster than Text arrays. However, String arrays cannot be longer than 255 characters.
  For more information, please refer to the ASCII Codes section.

The following line of code creates (declares) an Integer array of 10 elements:

ARRAY INTEGER(aiAnArray;10)

Then, the following code resizes that same array to 20 elements:

ARRAY INTEGER(aiAnArray;20)

Then, the following code resizes that same array to no elements:

ARRAY INTEGER(aiAnArray;0)

You reference the elements in an array by using curly braces ({…}). A number is used within the braces to address a particular element; this number is called the element number. The following lines put five names into the array called atNames and then display them in alert windows:

 ARRAY TEXT(atNames;5)

 atNames{1}:="Richard"

 atNames{2}:="Sarah"

 atNames{3}:="Sam"

 atNames{4}:="Jane"

 atNames{5}:="John"

 For($vlElem;1;5)

    ALERT("The element #"+String($vlElem)+" is equal to: "+atNames{$vlElem})

 End for

Note the syntax atNames{$vlElem}. Rather than specifying a numeric literal such as atNames{3}, you can use a numeric variable to indicate which element of an array you are addressing.

Using the iteration provided by a loop structure (For...End for, Repeat...Until or While...End while Boolean Commands), compact pieces of code can address all or part of the elements in an array.

Arrays and other areas of the 4D language

There are other 4D commands that can create and work with arrays. More particularly:

To work with arrays and selection of records, use the commands SELECTION RANGE TO ARRAY, SELECTION TO ARRAY, ARRAY TO SELECTION and DISTINCT VALUES.
Objects of the List box type are based on arrays; several commands of the “List box” theme work with arrays, for instance LISTBOX INSERT ROWS.
You can create graphs and charts on series of values stored in tables and arrays. For more information, see the GRAPH command.
Although version 6 brings a full set of new commands to work with hierarchical lists, the commands LIST TO ARRAY and ARRAY TO LIST (from the previous version) have been retained for compatibility.
Many commands can build arrays in one call, for example: FONT LIST, WINDOW LIST, VOLUME LIST, FOLDER LIST, DOCUMENT LIST, GET SERIAL PORT MAPPING, SAX GET XML ELEMENT, etc.