String Functions

This section describes functions that relates to manipulating string values in the APL.

Warning!

The String functions cannot operate on null arguments.

The following functions for String described here are:


String Concatenation

Strings are concatenated with the arithmetic '+' operator:

string str1 = string str2 + string str3 ...

strEndsWith

Returns true if str ends with substr , otherwise false.

boolean strEndsWith
 ( string  str , 
 string  substr )
ParameterDescription

str

String to examine

substr

String to look for

Returns

true or false


strEqualsIgnoreCase

Compares two strings and returns true if they are equal, and false if they are not. This comparison ignores case.

boolean strEqualsIgnoreCase
 ( string  str1 , 
 string  str2  )
ParameterDescription

str1

A string to compare

str2

Another string to compare

Returns

true or false


strIndexOf

Returns the first position where substr can be found in str . If substr is not found, -1 is returned. The position starts to count from 0 (zero), which is the first character.

int strIndexOf 
( string str , 
string substr, 
int startIndex ) //Optional
ParameterDescription

str

String to examine

substr

String to look for

startIndex

Index where to start the string search. If startIndex is not specified, the string is searched from the beginning.

Returns

The position of the first character of substr within str . If not found, -1 is returned.

strLastIndexOf

Returns the last position where  substr can be found in  str . If  substr is not found, -1 is returned. The position starts to count from 0 (zero), which is the first character.

int strLastIndexOf
 ( string  str , 
 string  substr, int startIndex  ) //Optional
ParameterDescription

str

String to examine

substr

String to look for

startIndex

Index where to start the string search. If startIndex is not specified, the string is searched from the beginning.

Returns

The position of the last character of substr within str . If not found, -1 is returned.


strInsert

Inserts a string into another at a specific position, and returns the result string.

string strInsert
 ( string  str1 ,
 int  position ,
 string  str2  )
ParameterDescription

str1

The string that str2 is inserted into

str2

The string to insert

position

Position where str2 will be inserted. Position 0 (zero) indicates prior to the first character of str1 .

Returns

The result string. Note, the str1 and str2 are not modified.


strLength

Returns the number of characters in a string.

int strLength( string  str  )
ParameterDescription

str

String to examine

Returns

The number of characters in the string


strREContains

Returns true if a string contains a substring, else false. The function is case sensitive.

boolean strREContains
 ( string  str ,
 string  regexp  )
ParameterDescription

str

String to examine

regexp

The substring to look for. Regular expressions are allowed.

Returns

true or false

Note!

Regular expressions according to Java syntax applies. For further information, see https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html

Warning!

Using nonconstant regular expressions may consume large amounts of memory and should therefore be avoided. 


strREIndexOf

Returns the first position where a regular expression can be found in a string. If the regular expression is not found, -1 is returned. The position starts to count from 0 (zero), which is the first character.

int strREIndexOf
 ( string  str ,
 string  regexp  )
ParameterDescription

str

String to examine

regexp

Regular expression to be used when examining str , using case sensitive and contains (not matches).

Returns

The position of the first character of regexp within str . If not found, -1 is returned.

Example - Using strREIndexOf

strREIndexOf( "Hello There!", "[Tt]he" ) // Returns 6

Note!

Regular expressions according to Java syntax applies. For further information, see https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html.

Warning!

Using nonconstant regular expressions may consume large amounts of memory and should therefore be avoided. 


strREMatches

Returns true if the first stated string matches the content of the second string completely. The function is case sensitive.

boolean strREMatches
 ( string  str ,
 string  regexp  )
ParameterDescription

str

The first string

regexp

The second string. Regular expressions are allowed

Returns

true or false

Example - Using strREMatches

strREMatches( "abc", "ab." )

Will return true.

strREMatches( "abc", "a..c" )

Will return false.

strREMatches( "abc", "a[a-z]c" )

Will return true.

strREMatches( "abc", "a[A-Z]c" )

Will return false.

strREMatches( numberString, "[0-9]*" )

Will check that the variable numberString only contain digits. It will return true for "123" and false for "123F".

Note!

Regular expressions according to Java syntax applies. For further information, please refer to https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html.

Warning!

Using nonconstant regular expressions may consume large amounts of memory and should therefore be avoided. 


strREReplaceAll

Replaces existing substrings within a string with new values.

string strREReplaceAll
 ( string  str ,
 string  old ,
 string  new  )
ParameterDescription

str

String to change

old

The substring to replace. Regular expressions are allowed.

new

The new substring to replace the old. If an empty string is entered, the old will be removed without inserting any new value.

Returns

The result string

Example - Using strREReplaceAll

string strREReplaceAll
 ( "flower", "low", "orm" )

This call will change the string "flower" to the string "low". If the new parameter was left empty ("orm" in this case), the resulting string would have been "fer".

Note!

Regular expressions according to Java syntax applies. For further information, please refer to  https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html.

Warning!

Using nonconstant regular expressions may consume large amounts of memory and should therefore be avoided. 


strReplaceChars

Replaces characters in a string at a given position with another string and returns the new string. If str2 is longer than str1 , then the resulting string will be expanded to fit the complete str2 .

string strReplaceChars
 ( string  str1 ,
 int  position ,
 string  str2  )
ParameterDescription

str1

The base string

position

Position where str2 will start replacement in str1 . Position 0 (zero) indicates prior to the first character of str1 .

str2

String to use for replacement

Returns

The result string. Note, the str1 and str2 are not modified.

Example - Using strReplaceChars

The following example returns the string: Hi Walter

strReplaceChars("Hi Sister", 3, "Walt");


strSplit

Splits a string where a given regular expression is matched into a list of strings. The function will try to match the regular expression and split the string as many times as possible.

list<string> strSplit
 ( string  str ,
 string  regex  )
ParameterDescription

str

The base string

regex

The regular expression which is to be used to split elements

Returns

A list of strings

This function would typically be used for splitting strings of values that are comma separated, colon separated, or similar. The list returned will present the substrings in the order they occur in the original string.

Example - Using strSplit

strSplit("one,two,three", ",");

Will return the following list:

one
two
three


strSplit("name:date:time", ":");

Will return the following list:

name
date
time


strSplit("person a person b person c", "person ");

Will return the following list:

a
b
c


strStartsWith

Returns true if str starts with substr , otherwise false.

boolean strStartsWith
 ( string  str ,
 string  substr  )
ParameterDescription

str

String to examine

substr

String to look for

Returns

true or false


strSubstring

Returns a substring from a given string. The extracted substring is from position start to end .

string strSubstring
 ( string  str ,
 int  start ,
 int  end  )



ParameterDescription

str

The base string

start

Position where to start the substring extraction. Position 0 (zero) points to the first character of str .

end

Position where to end the extraction. That is, the index of the letter after the last letter in the substring.

Returns

The substring

Example - Using strSubstring

The following call returns the string "the".

strSubstring("hi there", 3, 6);


strToLower

Turns all letters in a string to lower-case.

string strToLower( string  str  )
ParameterDescription

str

The base string

Returns

The result string. Note, the str is not modified.


strToUpper

Turns all letters in a string to capital letters.

string strToUpper( string  str  )
ParameterDescription

str

The base string

Returns

The result string. Note, the str is not modified.


strTrim

Removes leading and trailing spaces from a string and returns the result.

string strTrim( string  str  )
ParameterDescription

str

The base string

Returns

The result string. Note, the str is not modified.