sort_text_array_index_characters

The function sort_text_array_index_characters sorts the indices of a text array based on the elements in the array.

sort_text_array_index_characters ( input;output;number of elements to sort )

The function sort_text_array_index_characters is of type BOOL, and has three parameters:

1. input; ARRAY of type TEXT. This array contains the elements that must be sorted.
2. output; ARRAY of type NUMBER. This array will receive the sorted index.
3. number of elements to sort; NUMBER. This is the number of elements in the array, which must be sorted starting from the first element. This can either be a number or a NUMBER variable or expression.

Return values

The function sort_text_array_index_characters will return TRUE if the array was sorted successfully, and FALSE if 'number of elements to sort' is negative or 0.

If the sort_text_array_index_characters function fails the output array is unmodified.

The input array is not modified by the function.

The output array will receive the sorted index from the input array.

If the output array is larger than the number of sorted elements, those elements outside the sorted range are left unmodified.

The sort_text_array_index_characters function will perform a culture-neutral alphabetical sort on the text elements using Unicode codepoints.

Note

Any word processor instructions in the text elements are included in the sort, and sort before regular characters.

Example

ARRAY TEXT input[4]
ARRAY NUMBER index[4]
NUMBER i

ASSIGN input[1] := "c"		
ASSIGN input[2] := "d"
ASSIGN input[3] := "a"
ASSIGN input[4] := "b"

IF sort_text_array_index_characters (input; indices; 4) THEN
  FOR i FROM 1 UPTO 4 DO
#
@(i) @(input [ index[i] ])
#
  OD
ELSE
#
Failed to sort the input.
#
  STOP
FI

A sorted list is produced by using the sorted index stored in the output array to read the values from the input array. Also note that here the fact that the sort_text_array_index_characters is a function of type BOOL. BOOL is used to implement error handling. If the sort succeeds the return value of the function will be TRUE, the IF statement becomes TRUE, and the THEN part is executed. If the return is FALSE the ELSE part of the IF statement is executed.

This example produces the same result as the example included with the sort_text_array_characters function.