String functions

  • 15 minutes

You can use some built-in functions to work with strings, like on text and code data types. For example, you can use string functions if you want to remove characters from a text value or you want to replace characters in that text. AL supports a number of string functions, but it also supports the same functions that are available as the .NET string class.

You don't need .NET Interoperability to use these functions; they are built into AL language.

Screenshot of support for .NET string functions.

The string functions are:

  • StrPos and IndexOf

  • CopyStr and Substring

  • SelectStr and Split

  • InsStr

  • StrLen and MaxStrLen

  • LowerCase, UpperCase, ToLower, and ToUpper

  • IncStr

StrPos and IndexOf functions

With the StrPos function, you can find the position of a substring within a string. If the substring is found, the StrPos function will return the integer position. Therefore, if the return value is larger than zero, the substring exists.

Position := StrPos(Text, Substring);

The following example uses the StrPos function to determine the first position of the l character in the MyLongString variable.

var 
    MyLongString: Text[50];    
begin
    MyLongString := 'HelloWorldOfManyManyCharacters';

    Message('%1', StrPos(MyLongString, 'l'));  // Results in 3
end;

Another way of getting the position of a substring is by using the .IndexOf function.

Position := Text.IndexOf(Substring,[StartPosition]);

The same example can be rewritten with IndexOf.

var 
    MyLongString: Text[50];    
begin
    MyLongString := 'HelloWorldOfManyManyCharacters';

    Message('%1', MyLongString.IndexOf('l'));  // Results in 3
end;

CopyStr and Substring functions

With the CopyStr function, you can copy a substring from text or code. The function has three parameters, where the last one is optional.

NewString := CopyStr(Text, StartIndex, [Length]);

The code in the following example will return a substring starting on the fifth character. It will return 10 characters. If you don't specify a length, it will return all characters until the end of the text.

var
    MyLongString: Text[50];
    newString: Text[10];
begin
    MyLongString := 'HelloWorldOfManyManyCharacters';

    newString := CopyStr(MyLongString, 5, 10);

    Message('%1', newString);  // Results in 'oWorldOfMa'
end;

A .NET version called Substring can also be used.

newString := MyLongString.Substring(5, 10);

If using Substring, you should be aware of an important difference. If the length parameter is larger than the available number of characters in the string, you'll get an error with the Substring function. With the CopyStr function, it won't generate an error but will return a string with the available characters.

SelectStr and Split functions

The SelectStr function returns a string from comma-separated text. In the following example, the SelectStr function gets the second string from the comma-separated text.

 var
    MyLongString: Text[50];
    newString: Text;
begin
    MyLongString := 'This,is a comma,separated,string';

    newString := SelectStr(2, MyLongString);

    Message('%1', newString);  // Results in 'is a comma'
end;

You can also use a .NET version function called Split. Though similar to the SelectStr function, the Split function doesn't work entirely the same. It accepts a parameter where you can specify which character(s) that you want to split on. The Split function returns a List of [Text] function, where you can specify the index of the element that you want to retrieve.

var  
    MyLongString: Text[50];
    newString: Text;
begin
    MyLongString := 'This,is a comma,separated,string';

    newString := MyLongString.Split(',').Get(2);
    
    Message('%1', newString);  // Results in 'is a comma'
end;

The Split function can split on multiple characters. If you modify the example to also split on a blank space, you will get the following result.

var
    MyLongString: Text[50];
    newString: Text;
begin
    MyLongString := 'This,is a comma,separated,string';

    newString := MyLongString.Split(',',' ').Get(2);
    
    Message('%1', newString);  // Results in 'is'
end;

InsStr function

The InsStr function will insert a string to a certain position in an existing string.

var
    MyLongString: Text[50];
    newString: Text;
begin
    MyLongString := 'Press ENTER to continue.';

    newString := InsStr(MyLongString, 'or ESC ', 13);

    Message('%1', newString);  // Results in 'Press ENTER or ESC to continue.'
end;

StrLen and MaxStrLen functions

The StrLen and MaxStrLen functions are used to determine the length of text fields and the maximum length of the text field. If you have a variable of type Text[50], the MaxStrLen will be 50, even though the content has only 10 characters. The StrLen will return 10.

These functions are used frequently in combination with the CopyStr function to get the maximum characters out of a string.

var
    MyLongString: Text[50];
    newString: Text[10];
begin
    MyLongString := GetLongString();

    Message('STRLEN: %1', StrLen(MyLongString)); // Results in 30 
    Message('MAXSTRLEN: %1', MaxStrLen(MyLongString)); // Results in 50 

    newString := CopyStr(MyLongString, 5, MaxStrLen(newString));

    Message('%1', newString);  // Results in 'oWorldOfMa'
end;

LowerCase, UpperCase, ToLower, and ToUpper functions

If you want to change the case of a text variable, you can use the LowerCase and UpperCase functions or the ToLower and ToUpper .NET functions.

var
    MyLongString: Text[50];
begin
    MyLongString := 'HelloWorldOfManyManyCharacters';

    Message('UPPERCASE: %1', UpperCase(MyLongString));  
    // Results in 'HELLOWORLDOFMANYMANYCHARACTERS'
    Message('LOWERCASE: %1', LowerCase(MyLongString));  
    // Results in 'helloworldofmanymanycharacters'     

    Message('UPPERCASE: %1', MyLongString.ToUpper());  
    // Results in 'HELLOWORLDOFMANYMANYCHARACTERS'
    Message('LOWERCASE: %1', MyLongString.ToLower());  
    // Results in 'helloworldofmanymanycharacters'    
end;

IncStr function

The IncStr function is used to increment a number within a string. If that number is negative, it will be decreased by one.

If this string contains more than one number, the only number that is changed is the number closest to the end of the string.

var
    text000: Text;
    text001: Text;
begin
    text000 := 'Account no. 99 does not balance.';
    text001 := 'Account no. 2342 shows a total of $-452.';

    Message(IncStr(text000));
    // Results in: 'Account no. 100 does not balance.'

    Message(IncStr(text001));
    // Results in: 'Account no. 2342 shows a total of $-453.'
end;

Other .NET string functions

AL supports some string functions from the .NET string class:

  • Contains - Checks if a string contains a character or substring.

  • EndsWith - Checks if a string ends with a specific value.

  • IndexOf - Gets the first index of a character or string. Returns zero if none is found.

  • IndexOfAny - Gets the first index of any of the characters. Returns zero if none is found.

  • LastIndexOf - Gets the last index of a character or string. Returns zero if none is found.

  • PadLeft - Right-aligns the characters in the instance by padding them on the left for a specified total length. You can specify which character is used for padding.

  • PadRight - Left-aligns the characters in the instance by padding them on the right for a specified total length. You can specify which character is used for padding.

  • Remove - Removes a substring from a text.

  • Replace - Replaces a substring from a text.

  • Split - Splits text on one or more characters.

  • StartsWith - Checks if a string starts with a specific value.

  • Substring - Returns a part of the string, starting on a specific index with a certain length.

  • ToLower - This function will change all characters to lowercase.

  • ToUpper - This function will change all characters to uppercase.

  • Trim - Removes all leading and trailing blank spaces.

  • TrimEnd - Removes all trailing occurrences of a set of characters.

  • TrimStart - Removes all leading occurrences of a set of characters.