PeopleTools 8.52: PeopleCode API Reference

Array Class

This chapter provides an overview of arrays and discusses how to:

Create arrays.
Populate an array.
Remove items from an array.
Create empty arrays.
Create and populate multi-dimensional arrays.
Use flattening and promotion.
Declare array objects.
Understand the scope of an array object.
Use array class built-in functions.
Use array class methods
Use array class properties

Understanding Arrays

An array is a collection of data storage locations, each of which holds the same type of data. Each storage location is called an element of the array. When you create an array, you don’t have to declare the size of the array at declaration time. Arrays grow and shrink dynamically as you add (or remove) data. The size of an array is limited by the available memory. You can’t access past the end of an array, but you can assign outside the existing boundaries, thereby growing the array.

Creating Arrays

Arrays are declared by using the Array type name, optionally followed by "of" and the type of the elements. If the element type is omitted, it is set by default to ANY.

Local Array of Number &MYARRAY;
Local Array &ARRAYANY;

Arrays can be composed of any valid PeopleCode data type, such as string, record, number, date, and so on.

PeopleSoft recommends you declare every object you use in PeopleCode. This provides some syntax checking when you save PeopleCode. It’s better to find out that you misspelled the name of a method or property at design time, rather than at runtime!

Arrays can be declared as Local, Global, or Component, just like any other PeopleTools object.

Arrays can be created with one or more dimensions. An array with more than one dimension is called an array of arrays. The dimension of an array is the number of Array type names in the declaration. This is also called the depth of an array. The maximum depth of a PeopleCode array is 15 dimensions.

In the following example, &MYARRAY has three dimensions, and &MYA2 has two dimensions.

Local Array of Array of Array of Number &MYARRAY;
Local Array of Array &MYA2;

An array must always have a consistent dimension. This means that in a one-dimensional array none of the elements can be an array, in a two-dimensional array all of the elements must be one-dimensional arrays, and so on.

After you declare an array, use one of the built-in array functions to instantiate it and return an object reference to it. For example, the following creates an array containing one element of type &TEMP, whatever data type &TEMP may be.

&MYARRAY = CreateArray(&TEMP);

Or you can use the CreateArrayRept function to instantiate an array. The Rept stands for repeat. CreateArrayRept creates an array that contains the number of copies you specify of a particular value. The following code creates an array with three copies of the string &MYSTRING. This does not create a three-dimensional array, but rather creates an array that’s already populated with three elements of data (Len = 3), each of which contain the same string (&MYSTRING).

&MYARRAY = CreateArrayRept(&MYSTRING, 3);

An array object can be assigned to an array variable. Array objects can be passed from and returned to any kind of PeopleCode function:

ANewFunc (&myarray);
MyFunc (&myarray);
&MyArray = YourFunc("something");

For example, the ReturnToServer function returns an array of nodes to which a message can be published.

Elements in an array are specified by providing a bracketed subscript after the array object reference:

&MyArray[1] = 123;
&temp = &memory[1][2][3];
&temp = &memory[1, 2, 3]; /* Same as preceding line.  */
MyFunc(&MyArray[7]);
MyFunc(10)[15] = "a string";

To access data in a two-dimensional array, you must specify both indexes. The following accesses the second item in the first subarray:

&VALUE  = &DOUBLE[1][2];

You receive an error if you use a zero or negative index in an array. Accessing an array element whose index is larger than the last array element is also an error, but storing to such an index extends the array. Any intervening elements between the former last element and the new last element are assigned a value based on the element type of the array. This is the same value as an unassigned variable of that type.

An array is an object, which means that assignments to an array are the same as for any other object. An array variable can be assigned the distinguished value NULL, which indicates the absence of any array value.

Array variables are supported for all scopes. This means that you can have local, global, and Component array variables.

See Also

ReturnToServer

Assigning Objects

Populating an Array

There are several ways to populate an array. The example code following each of these methods creates the exact same array, with the same elements:

Use CreateArray when you initially create the array:

Local Array of Number &MyArray;

&MyArray = CreateArray(100, 200, 300);

Assign values to the elements of the array:
```
Local Array of Any &MYARRAY;

&MYARRAY = CreateArray();
&MYARRAY[1] = 100;
&MYARRAY[2] = 200;
&MYARRAY[3] = 300;
```
Note. Using CreateArray without any parameters creates an array of Any.

Use the Push method to add items to the end of the array:

Local Array of Number &MYARRAY;
Local Number &MYNUM;

&MYARRAY = CreateArrayRept(&MYNUM, 0);
/* this creates an empty array of number */
&MYARRAY.Push(100);
&MYARRAY.Push(200);
&MYARRAY.Push(300);

Use the Unshift method to add items to the beginning of the array:

Local Array of Number &MYARRAY;
Local Number &MYNUM;

&MYARRAY = CreateArrayRept(&MYNUM, 0);
/* this creates an empty array of number */
&MYARRAY.Unshift(300);
&MYARRAY.Unshift(200);
&MYARRAY.Unshift(100);

You can also use CreateArrayRept (repeat) when you initially create the array. The following example creates an array with three elements: all three elements have the same data, that is, 100:

Local Array of Number &MYARRAY;

&MYARRAY = CreateArrayRept(100, 3);

Removing Items From an Array

You can remove elements from either the start or the end of the array:

Use the POP method to select and remove an element from the end of an array

Local Array of Number &MYARRAY;

&MYARRAY = CreateArray();
&MYARRAY[1] = 100;
&MYARRAY[2] = 200;
&MYARRAY[3] = 300;

&ANSWER = &MYARRAY.Pop();

&ANSWER will equal 300.

Use the SHIFT method to select and remove an element from the beginning of an array

Local Array of Number &MYARRAY;

&MYARRAY = CreateArray();
&MYARRAY[1] = 100;
&MYARRAY[2] = 200;
&MYARRAY[3] = 300;

&ANSWER = &MYARRAY.Shift();

&ANSWER equals 100.

Creating Empty Arrays

If you create an array using CreateArray of any data type other than ANY, the new array is not empty: it contains one item. If you need to create a completely empty array that contains 0 elements, use one of the following:

Local Array of Number &AN;
Local Array of String &AS;
Local Array of Record &AR;
Local Array of Array of Number &AAN;
Local Record &REC;

&AN = CreateArrayRept(0,0); /* creates an empty array of number */
&AS = CreateArrayRept("", 0); /* creates an empty array of string */
&AR = CreateArrayRept(&REC, 0); /*create empty array of records */
&AAN = CreateArrayRept(&AN, 0); /*creates empty array of array of number */
&BOTH = CreateArray(CreateArrayRept("", 0), CreateArrayRept("", 0)); /* creates an⇒
 empty array of array of string */

Creating and Populating Multi-Dimensional Arrays

You can create arrays with more than one dimension. Each element in a multi-dimensional array is itself an array. For example, a two-dimensional array is really an array of arrays. Each subarray has to be created and populated as an array.

Each subarray in a multi-dimensional array must be of the same type. For example, you can’t create a two dimensional array that has one subarray of type string and a second subarray of type number.

The following example creates an array of array of string, then reads two files, one into each "column" of the array. The CreateArrayRept function call creates an empty array of string (that is, the Len property is 0) but with two dimensions (that is, with two subarrays, Dimension is 2). The first Push method adds elements into the first subarray, so at the end of that WHILE loop in the example, &BOTH has Len larger than 0. The other Push methods add elements to the second subarray.

Local array of array of string &BOTH;
Local File &MYFILE;
Local string &HOLDER;

/* Create empty &BOTH array */
&BOTH = CreateArrayRept(CreateArrayRept("", 0), 0);

/* Read first file into first column */

&MYFILE = GetFile("names.txt", "R");
While &MYFILE.ReadLine(&HOLDER);
   &BOTH.Push(&HOLDER);
End-While;

/* read second file into second column */

&MYFILE = GetFile("numbers.txt", "R");
&LINENO = 1;
While &MYFILE.ReadLine(&HOLDER);
   If &LINENO > &BOTH.Len Then
      /* more number lines than names, use a null name */
      &BOTH.Push(CreateArray("", &HOLDER));
   Else
      &BOTH[&LINENO].Push(&HOLDER);
   End-If;
   &LINENO = &LINENO + 1;
End-While;

/* if more names than numbers, add null numbers */
for &LINENO = &LINENO to &BOTH.Len
      &BOTH[&LINENO].Push("");
End-For;

The following code reads from a two-dimensional array and writes the data from the each subarray into a separate file.

Local File &MYFILE1, &MYFILE2;
Local string &STRING1, &STRING2;
Local array of array of string &BOTH;
.
/* code to load data into array would be here */
.
/* open files to be written to */

&MYFILE1 = GetFile("names.txt", "A");
&MYFILE2 = GetFile("numbers.txt", "A");

/* loop through array and write to files */

For &I = 1 To &BOTH.Len
   &J = 1;
   &STRING1 = &BOTH[&I][&J];
   &MYFILE1.writeline(&STRING1);
   &J = &J + 1;
   &STRING2 = &BOTH[&I][&J];
   &MYFILE2.writeline(&STRING2);
End-For;

&MYFILE1.Close();
&MYFILE2.Close();

The following example populates a multi-dimensional string array using SQL. This could be used for reading small tables.

Component array of array of string &ArrRunStatus;

&ArrRunStatus = CreateArrayRept(CreateArrayRept("", 0), 0);
&ArrRunStatusDescr = CreateArrayRept("", 0);

&SQL = CreateSQL("SELECT FIELDVALUE, XLATSHORTNAME FROM XLATTABLE WHERE FIELDNAME ⇒
= 'RUNSTATUS'");

&LineNo = 1;
While &SQL.Fetch(&FieldValue, &XlatShortName)
      &ArrRunStatus.Push(&FieldValue);
      &ArrRunStatus[&LineNo].Push(&XlatShortName);
      &LineNo = &LineNo + 1;
End-While;

To search for a particular element in this array, use the following:

&iIndex = &ArrRunStatus.Find(&RunStatusToGet);
                
&RunStatusDescr = &ArrRunStatus[&iIndex][2];

The following example shows how to create a two-dimension array using CreateArrayRept and Push. In addition, it shows how to randomly assigns values to the cells in a two-dimension array.

Local array of array of string &ValueArray;

&Dim1 = 10;
&Dim2 = 5;
&ValueArray = CreateArrayRept(CreateArrayRept("", 0), 0);
For &I = 1 To &Dim1
   &ValueArray.Push(CreateArrayRept("", &Dim2));
End-For;

&ValueArray[1][1] = "V11";
&ValueArray[2][1] = "V21";

WinMessage("&ValueArray[1][1] = " | &ValueArray[1][1] | " " | "&ValueArray[2][1] =⇒
 " | &ValueArray[2][1], 0);

Using Flattening and Promotion

Several of the functions and methods that support arrays in PeopleCode use flattening and promotion to convert their operands to the correct dimension for the array.

Flattening converts an array into its elements. For example, the CreateArray built-in function constructs an array from its parameters. If it is constructing a one-dimensional array and is given an array as a parameter, then it flattens that array into its elements and adds each of them to the array that it is building, rather than adding a reference to the array (which would be a dimension error) or reporting an error.

Likewise, for functions that operate on multiple-dimension arrays, if they are given a non-array parameter, they use promotion to convert it into an array of suitable dimension. For example, the Push method appends elements onto the end of an array. If it is operating with a two-dimensional array of Array of Number, and is given a numeric argument, it will convert the argument into a one-dimensional array of Number with the given number as its only element, and then append that to the two-dimensional array.

An array value can only be assigned to an array variable if the value and variable have both the same dimension and base type. This means you cannot assign an Array of Any to an Array of Number variable or vice-versa. You can, however, assign an Array of Number to an Any variable, as long as you do not break the rule that the base element of an array cannot be an array reference value.

Declaring Array Objects

Arrays are declared by using the Array type name, optionally followed by "of" and the type of the elements. If the element type is omitted, it is set by default to ANY.

Local Array of Number &MYARRAY;
Local Array &ARRAYANY;

Arrays can be composed of any valid PeopleCode data type, such as string, record, number, date, and so on.

Understanding the Scope of an Array Object

An array object can only be instantiated from PeopleCode. This object can be used anywhere you have PeopleCode, that is, in an application class, Component Interface PeopleCode, record field PeopleCode, and so on.

Array Class Built-in Functions

Array Class Methods

In this section, we discuss the array class methods.

Clone

Syntax

Clone()

Description

The Clone method returns a reference to a new array, which is a copy of the given array. It copies all levels of the array, meaning, if the array contains elements which are themselves arrays (actually references to arrays), then the copy contains references to copies of the subarrays. Furthermore, if the array contains elements that are references to the same subarray, then the copy contains references to different subarrays (which of course have the same value).

Parameters

None. The array object that the clone method is executed against is the array to be cloned. Assigning the result of this method assigns a reference to the new array.

Returns

An array object copied from the original.

Example

In the following example, &AAN2 contains the three elements like &AAN, but they are distinct arrays. The last line changes only &AAN2[1][1], not &AAN[1][1].

Local Array of Array of String &AAN, &AAN2;

&AAN = CreateArray(CreateArray("A", "B"), CreateArray("C", "D"), "E");
&AAN2 = &AAN.Clone();
&AAN2[1][1] = "Z";

After the following example, &AAN contains three elements: two references to the subarray that was &AAN[2] (with elements C and D), and a reference to a subarray with element E.

&AAN[1] = &AAN[2];

After the following example, &AAN2 contains three elements: references to two different subarrays both with elements C and D, and a subarray with element E.

&AAN2 = &AAN.Clone();

See Also

Array class: Subarray method.

Find

Syntax

Find(value)

Description

For a one-dimensional array, the Find method returns the lowest index of an element in the array that is equal to the given value. If the value is not found in the array, it returns zero.

For a two-dimensional array, the Find method returns the lowest index of a subarray which has its first element equal to the given value. If such a subarray is not found in the array, it returns zero.

Note. This method works with arrays that have only one or two dimensions. You receive a runtime error if you try to use this method with an array that has more than two dimensions.

Parameters

value

The string or subarray to search for.

Returns

An index of an element or zero.

Example

Given an array &AS containing (A, B, C, D, E), the following code sets &IND to the index of D, that is, &IND has the value 4:

Local array of string &AS;

&AS = CreateArrayRept("", 0);
&AS.Push("A");
&AS.Push("B");
&AS.Push("C");
&AS.Push("D");
&AS.Push("E");
&IND = &AS.Find("D");

Given an array of array of string &AABYNAME containing (("John", "July"), ("Jane", "June"), ("Norm", "November"), the following code sets &IND to the index of the subarray starting with "Jane", that is, &IND has the value 2:

&NAME = "Jane";
&IND = &AABYNAME.Find(&NAME);

See Also

Array class: Replace method, Substitute method.

Get

Syntax

Get(index)

Description

Use the Get method to return the index element of an array. This method is used with the Java PeopleCode functions, instead of using subscripts (which aren't available in Java.)

Using this method is the same as using a subscript to return an item of an array. In the following example, the two lines of code are identical:

&Value = &MyArray[8];
                
&value = &MyArray.Get(8);

Parameters

index

The array element to be accessed.

Returns

An element in an array.

See Also

Array class: Set method.

Java Class

Join

Syntax

Join([separator [, arraystart, arrayend  [,stringsizehint]]])

Description

The Join method converts the array that is executing the method into a string by converting each element into a string and joining these strings together, separated by separator.

Note. Join does not join two arrays together.

Each array or subarray to be joined is preceded by the string given by arraystart and followed by the string given by arrayend. If the given array is multi-dimensional, then (logically) each subarray is first joined, then the resulting strings are joined together.

Parameters

separator	Specifies what the elements in the resulting string should be separated with in the resulting string. Separator is set by default to a comma (",").
arraystart	Specifies what each array or subarray to be joined should be preceded with in the resulting string. arraystart is set by default to a left parenthesis ("(").
arrayend	Specifies what each array or subarray to be joined should be followed by in the resulting string. arrayend is set by default to a right parenthesis (")").
stringsizehint	Specify a hint to the Join method about the resulting size of the string. This can improve performance if your application is concatenating a large number of string. See the Example section below.

Returns

A string containing the converted elements of the array.

Example

The following example:

Local array of array of number &AAN;

&AAN = CreateArray(CreateArray(1, 2), CreateArray(3, 4), 5);
&STR = &AAN.Join(", ");

produces in &STR the string:

((1, 2), (3, 4), 5)

The following example makes use of the stringsizehint parameter. The following application class passes the resulting string size hint in the Value property.

class StringBuffer
   method StringBuffer(&InitialValue As string, &MaxSize As integer);
   method Append(&New As string);
   method Reset();
   property string Value get set;
   property integer Length readonly;
private
   instance array of string &Pieces;
   instance integer &MaxLength;
end-class;

method StringBuffer
   /+ &InitialValue as String, +/
   /+ &MaxSize as Integer +/
   &Pieces = CreateArray(&InitialValue);
   &MaxLength = &MaxSize;
   &Length = 0;
end-method;

method Reset
   &Pieces = CreateArrayRept("", 0);
   &Length = 0;
end-method;

method Append
   /+ &New as String +/
   Local integer &TempLength = &Length + Len(&New);
   If &Length > &MaxLength Then
      throw CreateException(0, 0, "Maximum size of StringBuffer exceeded(" | &Max⇒
Length | ")");
   End-If;
   &Length = &TempLength;
   &Pieces.Push(&New);
end-method;

get Value
   /+ Returns String +/
   Local string &Temp = &Pieces.Join("", "", "", &Length);
   /* collapse array now */
   &Pieces = CreateArrayRept("", 0);
   &Pieces.Push(&Temp); /* start out with this combo string */
   Return &Temp;
end-get;

set Value
   /+ &NewValue as String +/
   /* Ditch our current value */
   %This.Reset();
   &Pieces.Push(&NewValue);
end-set;

The following code concatenates strings.

While &file.ReadLine(&line)
   &S.Append(&line);
   &S.Append(&separator);

See Also

Split.

Syntax

Next(&index)

Description

The Next method increments the given index variable. It returns true if and only if the resulting index variable refers to an existing element of the array. Next is typically used in the condition of a WHILE clause to process a series of array elements up to the end of the array.

&index must be a variable of type integer, or of type Any initialized to an integer, as Next attempts to update it.

If you want to start from the first element of the array, start Next with an index variable with the value zero. The first thing Next does is to increment the value by one.

Parameters

&index

The array element where processing should start. &index must be a variable of type integer, or of type Any initialized to an integer, as Next attempts to update it.

Returns

True if the resulting index refers to an existing element of the array, False otherwise.

Example

Next can be used in a While loop to iterate through an array in the following manner:

&INDEX = 0;
While &A.Next(&INDEX)
   /* Process &A[&INDEX] */
End-While;

In the following code example, &BOTH is a two-dimensional array. This example writes the data from each subarray in &BOTH into a different file.

&I = 0;
While &BOTH.Next(&I)
   &J = 1;
   &STRING1 = &BOTH[&I][&J];
   &MYFILE1.writeline(&STRING1);
   &J = &J + 1;
   &STRING2 = &BOTH[&I][&J];
   &MYFILE2.writeline(&STRING2);
End-While;

See Also

Array class: Len property.

Pop

Syntax

Pop()

Description

The Pop method removes the last element from the array and returns its value.

Parameters

None.

Returns

The value of the last element of the array. If the last element is a subarray, the subarray is returned.

Example

The Pop method can be used with the Push method to use an array as a stack. To put values on the end of the array, use Push. To take the values back off the end of the array, use Pop.

Suppose we have a two-dimensional array &SUBPARTS which gives the subparts of each part of some assemblies. Each row (subarray) of &SUBPARTS starts with the name of the part, and then has the names of the subparts. Assuming there are no "loops" in this data, the following code puts all the subparts, subsubparts, and so on, of the part given by &PNAME into the array &ALLSUBPARTS, in "depth first order" (that is, subpart1, subparts of subpart1, …, subpart2, subparts of subpart2, …). We stack the indexes into &SUBPARTS when we want to go down to the subsubparts of the current subpart.

Local array of array of string &SUBPARTS;
Local array of string &ALLSUBPARTS;
Local array of array of number &STACK;
Local array of number &CUR;
Local string &SUBNAME;

/* Set the ALLSUBPARTS array to an empty array of string.  */

&ALLSUBPARTS = CreateArrayRept("dummy", 0);

/* Start with the part name.  */

&STACK = CreateArray(CreateArray(&SUBPARTS.Find(&PNAME), 2));
While &STACK.Len > 0
   &CUR = &STACK.Pop();
   If &CUR[1] <> 0 And
         &CUR[2] <= &SUBPARTS[&CUR[1]].Len Then
      
      /* There is a subpart here.  Add it.  */
      &SUBNAME = &SUBPARTS[&CUR[1], &CUR[2]];
      &ALLSUBPARTS.Push(&SUBNAME);
      
      /* Tour its fellow subparts later.  */
      &STACK.Push(CreateArray(&CUR[1], &CUR[2] + 1));
      
      /* Now tour its subsubparts.  */
      &STACK.Push(CreateArray(&SUBPARTS.Find(&SUBNAME), 2));
      
   End-If;
End-While;

See Also

Array class: Push method, Replace method, Shift method, Unshift method.

Push

Syntax

Push(paramlist)

Where paramlist is an arbitrary-length list of values in the form:

value1 [, value2] ...

Description

The Push method adds the values in paramlist onto the end of the array executing the method. If a value is not the correct dimension, it is flattened or promoted to the correct dimension first, then the resulting values are added to the end of the array.

Considerations Using Arrays With Object References

This method only adds an element to the end of an array. It does not clone or otherwise deep-copy the parameters. For example, if you are adding a reference to an object, Push just adds a reference to the object at the end of the array. This is similar to an assignment. It is not making a copy of the object. The following code snippet only puts a reference to the same record onto the end of the array.

While &SQL.Fetch(&Rec);
&MYARRAY.Push(&Rec);
...
End-While;

Even though the array is growing, all the elements point to the same record. You have only as many standalone record objects as you create. The following code snippet creates new standalone records, so each element in the array points to a new object:

local Record &FetchedRec = CreateRecord(Record.PERSONAL_DATA);

While &SQL.Fetch(&FetchedRec)
     &MYARRAY.Push(&FetchedRec);
     &FetchedRec = CreateRecord(Record.PERSONAL_DATA);
End-While;

Parameters

paramlist

An arbitrary-length list of values, separated by commas.

Returns

None.

Example

The following example loads an array with data from a database table.

Local array of record &MYARRAY;
Local SQL &SQL;

&I = 1;
&SQL = CreateSQL("Select(:1) from %Table(:1) where EMPLID like &lsquo;8%&rsquo;",⇒
 &REC);
While &SQL.Fetch(&REC);
   &MYARRAY.Push(CreateRecord(RECORD.PERSONAL_DATA));
   &I = &I + 1;
   &REC.CopyFieldsTo(&MYARRAY[&I]);
End-While;

See Also

Array class: Pop method, Replace method, Shift method, Unshift method.

Using Flattening and Promotion

Assigning Objects

Replace

Syntax

Replace(start, length[, paramlist])

Where paramlist is an arbitrary-length list of values in the form:

value1 [, value2] ...

Description

Replace replaces the length elements starting at start with the given values, if any. If length is zero, the insertion takes place before the element indicated by start. Otherwise, the replacement starts with start and continues up to and including length, replacing the existing values with paramlist.

If a negative number is used for start, it indicates the starting position relative to the last element in the array, such that −1 indicates the position just after the end of the array. To insert at the end of the array (equivalent to the Push method), use a start of −1 and a length of 0.

If a negative number is used for length, it indicates a length measuring downward to lower indexes. Both flattening and promotion can be applied to change the dimension of the supplied parameters to match the elements of the given array.

Similar to how the built-in function Replace is used to update a string, the Replace method is a general way to update an array, and can cause the array to grow or shrink.

See Using Flattening and Promotion.

Using Replace to Remove an Element

You can use the Replace method to remove an element from an array. Just specify the item you want replaces, with length equal to one.

The following example removes the item from &Index:

&Array.Replace(&Index, 1);

Parameters

start	Specifies where to start replacing the given elements in the array. If a negative number is used for start, it indicates the starting position relative to the last element in the array.
length	Specifies the number of elements in the array to be replaced.
paramlist	Specifies values to be used to replace existing values in the array. This parameter is optional.

Returns

None.

Example

For example, given the following array:

Local array of string &AS;

&AS = CreateArray("AA", "BB", "CC");

After executing the next code, the array &AN will contain four elements, ZZ, YY, BB, CC:

&AS.Replace(1, 1, "ZZ", "YY");

After executing the next code, the array &AN will contain three elements, ZZ, MM, CC:

&AS.Replace(2, 2, "MM");

After executing the next code, the array &AN will contain three elements, ZZ, OO, CC.

&AS.Replace( - 2, - 1, "OO");

&AS expanded in PeopleCode debugger

See Also

Array class: Substitute method, Find method.

Reverse

Syntax

Reverse()

Description

The Reverse method reverses the order of the elements in the array.

If the array is composed of subarrays, the Reverse method reverses only the elements in the super-array, it doesn’t reverse all the elements in the subarrays. For example, the following:

&AN = CreateArray(CreateArray(1, 2), CreateArray(3, 4), CreateArray(5, 6)).reverse⇒
();

results in &AN containing:

 ((5,6), (3,4), (1,2)

Parameters

None.

Returns

None.

Example

Suppose you had the following array.

Local Array of Sting &AS;
                
&AS = CreateArray("R", "O", "S", "E");

If you executed the Reverse method on this array, the elements would be ESOR.

See Also

Array class: Sort method.

Set

Syntax

Set(index)

Description

Use the Set method to set the value of the index element of an array. This method is used with the Java PeopleCode functions, instead of using subscripts (which aren't available in Java.)

Using this method is the same as using a subscript to reference an item of an array. In the following example, the two lines of code are identical:

&MyArray[8] = &MyValue;
                
&MyArray.Set(8) = &MyValue;

Parameters

index

The array element to be accessed.

Returns

None.

See Also

Array class: Get method.

Java Class

Shift

Syntax

Shift()

Description

Use the Shift method to remove the first element from the array and return it. Any following elements are "shifted" to an index of one less than they had.

Parameters

None.

Returns

Returns the value of the first element of the array. If the first element is a subarray, the subarray is returned.

Example

For &I = 1 to &ARRAY.Len;
   &ITEM = &ARRAY.Shift;
   /* do processing */
End-For;

See Also

Array class: Pop method, Push method, Replace method, Unshift method.

Sort

Syntax

Sort(order)

Description

The Sort method rearranges the elements of the array executing the method into an order.

The type of sort done by this function, that is, whether it is a linguistic or binary sort, is determined by the Sort Order Option on the PeopleTools Options page.

If the array is one-dimensional, the elements are arranged in either ascending or descending order.

The type of the first element is used to determine the kind of comparison to be made. Any attempt to sort an array whose elements are not all of the same type results in an error.

If order is "A", the order is ascending; if it is "D", the order is descending. The comparison between elements is the same one as if done using the PeopleCode comparison operators (<, >, =, and so on.)

Note. If you execute this method on a server, the string sorting order is determined by the character set and localization of the server.

If the array is two-dimensional, the subarrays are arranged in order by the first element of each subarray. Sorting an array whose subarrays have different types of first elements will result in an error. The comparison is done by using the PeopleCode comparison operators (<, >, =, and so on.)

Note. This method works with arrays that have only one or two dimensions. You receive a runtime error if you try to use this method with an array that has more than two dimensions.

Parameters

order

Specifies whether the array should be sorted in ascending or descending order. Values for order are:

Value	Description
A	Ascending
D	Descending

Returns

None.

Example

The following example changes the order of the elements in array &A to be ("Frank", "Harry", "John").

&A = CreateArray("John", "Frank", "Harry");
                
&A.Sort();

The following example changes the order of the elements in array &A to be (("Frank", 1957), ("Harry", 1928), ("John", 1952)).

&A = CreateArray(CreateArray("John", 1952), CreateArray("Frank", 1957), Create⇒
Array("Harry", 1928));

&A expanded in PeopleCode debugger

&A.Sort("A");

&A expanded in PeopleCode debugger, showing code results

See Also

Array class: Reverse method.

PeopleTools Options

Subarray

Syntax

Subarray(start, length)

Description

The Subarray method creates a new array from an existing one, taking the elements from start for a total of length. If length if omitted, all elements from start to the end of the array are used.

If the array is multi-dimensional, the subarrays of the created array are references to the same subarrays from the existing array. This means if you make changes to the original subarrays, the referenced subarrays are also changed. To make distinct subarrays, use the Clone method.

Parameters

start	Specifies where in the array to begin the subarray.
length	Specifies the number of elements in the array to be part of the subarray.

Returns

An array object.

Example

To make a distinct array from a multi-dimensional array, use the following:

&A = &AAN.Subarray(1, 2).Clone();

See Also

Array class: Clone method.

Substitute

Syntax

Substitute(old_val, new_val)

Description

The Substitute method replaces every occurrence of a value found in an array with a new value. To replace an element that occurs in a specific location in an array, use Replace.

If the array is one-dimensional, Substitute replaces every occurrence of the old_val in the array with new_val.

If the array is two-dimensional, Substitute replaces every subarray whose first element is equal to old_val, with the subarray given by new_val.

Note. This method works with arrays that have only one or two dimensions. You receive a runtime error if you try to use this method with an array that has more than two dimensions.

Parameters

old_val	Specifies the existing value in the array to be replaced.
new_val	Specifies the value with which to replace occurrences of old_val.

Returns

None

Example

The following example changes the array &A to be ("John", "Jane", "Hamilton" ).

&A = CreateArray();
&A[1] = "John";
&A[2] = "Jane";
&A[3] = "Henry";
&A.Substitute("Henry", "Hamilton");

The following example changes the array &A to be (("John", 1952), ("Jane", 1957), ("Hamilton", 1971), ("Frank", 1961)).

&A = CreateArray(CreateArray("John", 1952), CreateArray("Jane", 1957), CreateArray⇒
("Henry", 1928), CreateArray("Frank", 1961));
                
&A.Substitute("Henry", CreateArray("Hamilton", 1971));

See Also

Array class: Find method, Replace method.

Unshift

Syntax

Unshift(paramlist)

Where paramlist is an arbitrary-length list of values in the form:

value1 [, value2] ...

Description

The Unshift method adds the given elements to the start of the array. Any following elements are moved up to indexes that are larger by the number of values moved. Flattening and Promotion are used to change the dimension of the supplied parameters to be one less than that of the given array.

Parameters

paramlist

Specifies values to be added to the start of the array.

Returns

None.

Example

The following code changes &A to be ("x", "Y", "a", "B", "c").

&A = CreateArray("a", "B", "c");
                
&A.Unshift("x", "Y");

See Also

Array class: Pop method, Push method, Replace method, Shift method, Using Flattening and Promotion .

Array Class Properties

In this section, we discuss the array class properties.

Dimension

Description

The Dimension property is the number of "Array" type names from the declaration of the array, also called subarrays. This property returns a number.

This property is read-only.

Example

The following example sets &DIM to 2.

Local Array of Array of Number &AAN;
                
&DIM = &AAN.Dimension;

Len

Description

The Len property is the current number of elements in the array. This property can be updated. Setting it to a negative value results in an error.

If this property is set to a smaller (nonnegative) number than its current value, the array is truncated to that length, discarding any elements whose indexes are larger than the given new length.

If this property is set to a number larger than its current value, the array is extended to the new length. Any new elements are set to a default value based on the element type of the array.

This property is read-write.

Example

The following is a test of whether an array is empty:

If &ARR.Len = 0 then /* &ARR is empty. */ End-If;