%SPLIT (Split String into Substrings)

%SPLIT(string {: separators })

%SPLIT splits a string into an array of substrings. It returns a temporary array of the substrings.

%SPLIT can be used in calculation statements wherever an array can be used except:
  • SORTA
  • %ELEM
  • %LOOKUP
  • %SUBARR

The first operand is the string to be split. It can be alphanumeric, graphic, or UCS-2.

The second operand is the list of characters that indicate the end of each substring. It is optional. It must have the same type and CCSID as the first operand. If it is not specified, %SPLIT defaults to splitting at blanks. If the length of the second operand is greater than 1, any of the characters in the second operand indicate the end of each substring. For example, %SPLIT('abc.def-ghi' : '.-') has two separator characters, '.', and '-', so it returns an array with three elements: ('abc','def','ghi').

Separator characters at the beginning and end of the string are ignored. For example, %SPLIT('..abc.def..' : '.') returns an array with two elements: ('abc','def').

If a separator character follows another separator character, it is ignored. For example, %SPLIT('abc..def' : '.') returns an array with two elements: ('abc','def').

If the length of the separators operand is zero, the result is a single element with the value of the string operand. For example, if sep has a length of zero, %SPLIT('a.b.c' : sep) returns an array with one element: ('a.b.c').

If the string has a length of zero, or if all the characters in the string are one of the separator characters, %SPLIT returns zero elements.

Examples of %SPLIT

  • In the following example, %SPLIT has only one parameter, so the string is split at blanks. 
    
   DCL-S array VARCHAR(10) DIM(10);

   array = %SPLIT('Monday Tuesday Wednesday');
   // array(1) = "Monday"
   // array(2) = "Tuesday"
   // array(3) = "Wednesday"
  • In the following example, %SPLIT has two parameters. The second parameter has two characters, period (.) and blank. The string is split when either of the characters in the second parameter is found. 
    
   DCL-S array VARCHAR(10) DIM(10);

   array = %SPLIT('Today is Monday. Tomorrow is Tuesday.' : '. ');
   // array(1) = "Today"
   // array(2) = "is"
   // array(3) = "Monday"
   // array(4) = "Tomorrow"
   // array(5) = "is"
   // array(6) = "Tuesday"
  • In the following example, the FOR-EACH operation is used to process the temporary arrays returned by %SPLIT.
    1. The string is first split into sentences, splitting at the characters used to end a sentence.
    2. The string is then split into phrases, splitting at commas, colons, and semi-colons.
    3. Each phrase is then split into words, splitting at blanks. 
    
   DCL-S sentence VARCHAR(10000);
   DCL-S phrase VARCHAR(10000);
   DCL-S word VARCHAR(10000);
   DCL-S string VARCHAR(10000);

   FOR-EACH sentence in %SPLIT(string : '.!?');    //  1 
      ...
      FOR-EACH phrase in %SPLIT(sentence : ',;:'); //  2 
         ...
         FOR-EACH word in %SPLIT(phrase);          //  3 
            ...
         ENDFOR;
      ENDFOR;
   ENDFOR;
  • In the following example, the RPG programmer does not want extra separators to be ignored by %SPLIT.
    • The string normally contains three names, separated by commas: 'Mary,Jane,Smith'.
    • If there is no middle name, there are two commas together: 'Mary,,Smith'.
    1. To ensure that all commas act as separators, the %SCANRPL built-in function is used to change the commas to '*,*': 'Mary*,*Jane*,*Smith' and 'Mary*,**,*Smith'. (Note that a complete program would ensure that the '*' character does not appear in the string.)
    2. The comma is specified as the separator character.
    3. %TRIM is used to trim the leading and trailing '*' characters from the names.
    In the example, the comments following each statement show the result of the statement for the two values
    • 'Mary,Jane,Smith'
    • 'Mary,,Smith'. 
    
   DCL-S string VARCHAR(100);
   DCL-S string2 VARCHAR(100);
   DCL-S names VARCHAR(100) DIM(3);

   string2 = %SCANRPL (',' : '*,*' : string); //  1 
   // string2 = "Mary*,*Jane*,*Smith"
   //           "Mary*,**,*Smith"
   names = %SPLIT (string2 : ',');            //  2 
   // names =
   //     Mary* | *Jane* | *Smith
   //     Mary* | **     | *Smith
   names = %TRIM (names : '*');               //  3 
   // names =
   //     Mary  | Jane   | Smith
   //     Mary  |        | Smith