String Functions

Basic String functions:

1) string_compare(str1,str2) returns long
2) string_concat(str1,str2,{,….})
3) string_downcase(str)
4) string_filter(str,string_filter)
5) string_filter_out(str,string_filter_out)
6) string_index(str1,str2) returns long
7) string_lenght(str) returns long
8) string_replace(str, find, replace)
9) string_replace_first(str,find,replace)
10) string string_representation(dml_object input_object)
11) string_rindex(str, char) returns long
12) string_substring(str, start, length)
13) string_upcase(str)

Trimming/Padding
14) string_lpad(str, len{,p})
15) string_lrepad(str, len{,p})
16) string_lrtrim(str)
17) string_ltrim(str)
18) string_pad(str, len{,p})
19) string_repad(str, len{,p})
20) string_trim(str)

Decimal Related
21) decimal_lpad (str, len {,padchar })
22) decimal_lrepad(str, len{,padchar })
23) decimal_strip(str)

Miscellaneous String functions

24) char_string(char) returns string
25) string_char(str, pos) returns long
26) is_blank(str) returns long
27) is_bzero(str) returns long
28) make_byte_flags(s) returns unsigned char[256]
29) re_get_match(str, re) returns string
30) re_index(str, re) returns long
31) re_replace(str, re, new) returns string
32) re_replace_first(str, re, new) returns string
33) string_from_hex(hexstr{, may_be_odd_sized}) returns string
34) string_to_hex(str) returns string
35) test_characters_all(s, flags) returns long
36) test_characters_any(s, flags) returns long
37) Unicode_char_string(char) returns unicode string
38) url_decode_escapes(str)

Ab-Initio : Inbuilt String Functions() 1

 39) url_encode_escapes(str)

Basic String functions:

1) string_compare
Returns a number, representing the result of comparing two strings.

Syntax
long string_compare(string str1, string str2)

Arguments
str1 The first of two strings
str2 The second of two strings

Note:
The string_compare function returns the following after comparing the lexicographic order of
str1 and str2:

-1 if the first argument is less than the second

0 if the arguments are equal
1 if the first argument is more than the second
NULL if either of the arguments evaluates to NULL

Examples
string_compare("abcd", "abcd") 0
string_compare("aaaa", "bbbb") -1
string_compare("bbbb", "aaaa") 1
string_compare("aaaa", "a") 1
string_compare("AAAA", "aaaa") -1
string_compare((ebcdic string(4))"AAAA",(ebcdic string(4))"aaa" 1

2) string_concat
Returns the concatenation of multiple string arguments.

Syntax
string string_concat(string str1, string str2 [ , string str3 ... ] )

Arguments
str1 The string that will appear first in the concatenated result
str2 The string that will be concatenated to the previous string

Notes:
--There must be at least two and no more than 10 strings.
--The function returns NULL if any of the arguments is NULL.

Ab-Initio : Inbuilt String Functions() 2

Examples
string_concat("abcd", "efgh") "abcdefgh"
string_concat("John", " ", "Smith") "John Smith"
string_concat("xyz", "") "xyz"
string_concat(U"abc", U"\u0091" U"abc\u0091"

3) string_downcase
Returns a string with any uppercase letters converted to lowercase.

Syntax
string string_downcase(string str)

Argument
str A string

Note:
The function returns NULL if the argument is NULL.

Example
string_downcase("abcXYZ") "abcxyz"

4) string_filter
Returns the characters of one string that also appear in another string.

Syntax
string string_filter(string str1, string str2)

Arguments
str1 The string to be filtered
str2 The string containing the characters to keep

Note:
The function returns NULL if either of the arguments is NULL.

Examples
string_filter("AXBYCZ", "ABCDEF") "ABC"
string_filter("023#46#13", "0123456789") "0234613"

5) string_filter_out
Returns the characters of one string that do not appear in another string.

Syntax
string string_filter_out(string str1, string str2)

Arguments

Ab-Initio : Inbuilt String Functions() 3

str1 The string to be filtered
str2 The string containing the characters to drop

Note:
The function returns NULL if either of the arguments is NULL.

Examples
string_filter_out("AXBYCZ", "ABCDEF") "XYZ"
string_filter_out("Apt. #2", ".#,%") "Apt 2"

6) string_index
Returns the index of the first character of the first occurrence of a string within another string.

Syntax
long string_index(string str, string seek)

Arguments
str A string
Seek A string to be found in str

Details
The string_index function returns:
--0 if the string seek does not occur in str
--1 if seek is zero-length
--NULL if either of the arguments evaluates to NULL

Note: Strings are indexed starting at 1.

Examples
string_index("abcdefgh eieio", "e" 5
string_index("John Smith", ":") 0
string_index(U"abcdefghi", U"def") 4
string_index("rstuvwxyz", "abc") 0
string_index("qwerty", "") 1

7) string_length
Returns the length of a string.

Syntax
long string_length(string str)

Argument
str A string
Note: The function returns NULL if str is NULL.

Examples

Ab-Initio : Inbuilt String Functions() 4

 string_length("") 0
string_length("abc") 3
string_length("abc ") 6

8) string_replace
Returns a string after replacing one substring with another.

Syntax
string string_replace(string str, string seek, string new)

Arguments
Str A string containing seek
Seek A string to replace
New A replacement string

Details
The string_replace function replaces each non overlapping occurrence of seek in str with new
and returns the resulting string. If seek is zero-length, the function inserts new before each
character and after the last, and returns the resulting string.

Examples
string_replace("a man a plan a canal", "an", "ew")
"a mew a plew a cewal"
string_replace("a man a plan a canal", "ship", "boat")
"a man a plan a canal"
string_replace("abcde", "", "*") "*a*b*c*d*e*"
string_replace(U"ab", U"b", U"\u0099") U"a\u0099"

9) string_replace_first
Returns a string after replacing the first occurrence of one substring with another. If seek is
zero-length, the function inserts new before the first character of str.

Syntax
string string_replace_first(string str, string seek, string new)

Arguments
str A string containing seek
seek A string to replace
new A replacement string

Example
string_replace_first("a man a plan a canal", "an", "ew")
"a mew a plan a canal"

Ab-Initio : Inbuilt String Functions() 5

 10) string_representation
Returns the text form of the object supplied. The returned text form is the same text form as is
produced by m_dump or by the logging mechanism.

Syntax
string string_representation(dml_object input_object)

Argument
input_object A single object of any type, or a combination of objects of different types

Examples
Here is a simple example:

--string_representation(123) "123"

Here is a more complicated example:

string_representation([record x 23 s "hi there" y 92])
 “[record\n x 23\n s \"hi there\"\n y 92]”

11) string_rindex
Returns the index of the first character of the last occurrence of a string within another string.

Syntax
long string_rindex(string str, string seek)

Arguments
Str A string containing a string you want to find
seek The string to find

Note: The string_rindex function returns:

-The index of the first character of the last occurrence of str, if str occurs in seek
-0 if the string seek does not occur in str
-1 plus the length of str if seek is zero-length
-NULL if either of the arguments is NULL
Strings are indexed starting at 1.

Examples
string_rindex("abcdefgh eieio", "e") 12
string_rindex("John Smith", "&") 0
string_rindex("abcdefghi", "def") 4
string_rindex("rstuvwxyz", "abc") 0
string_rindex("qwerty", "") 7

Ab-Initio : Inbuilt String Functions() 6

12) string_substring
Returns a substring of a string. The substring can be a specific length and can begin at a
specific character.

Syntax
string string_substring(string str, int start, int length)

Arguments
str A string
start The index of the first character of the substring
length The number of characters in the substring

Notes: Specify the substring by specifying the index of the first character (start) and the length
of the substring.
--If start is less than 1, the function uses 1 as the value start.
--If length is less than 1, the function uses 0 as the value of length.
--If start is greater than the length of the string, the function returns "".
--If length is greater than the length of the string, the function returns just the available
characters.
Strings are indexed starting at 1.

Examples
string_substring("John Smith", 8, 5) "ith"
string_substring("abcdefgh", 4, 3) "def"
string_substring("qqqqqqqq", 9, 3) ""
string_substring("abcdefgh", 3, 12) "cdefgh"
string_substring("abcdefgh", -3, 4) "abcd"

13) string_upcase
Returns a string with any lowercase letters converted to uppercase.

Syntax
string string_upcase(string str)

Argument
str A string

Example
string_upcase("abcXYZ") "ABCXYZ"

14) string_lpad

Ab-Initio : Inbuilt String Functions() 7

Returns a string padded with a specified character to a specified length.

Syntax
string string_lpad(string str, int len [ , string pad_char] )

Arguments
Str A string
len A length in number of characters
pad_char A single character. If you do not supply pad_char, the value of
pad_char is blank.

Examples
string_lpad("abc", 5) " abc"
string_lpad("abc", 5, "#") "##abc"
string_lpad("abcdefgh", 5, "#") "abcdefgh"
string_lpad(U"ab", 3, U"\u0099") U"\u0099ab"

15) string_lrepad
Returns a string trimmed of leading blanks and left-padded with a specified character to a
specified length.

Syntax
string string_lrepad(string str, int len [ , string pad_char ] )

Arguments
Str A string
len A length in number of characters
pad_char A single character. If you do not supply pad_char, the value of
pad_char is blank.

Note:
The string_lrepad function:
--Trims str of any leading blanks.
--Pads str on the left with the character pad_char to len length.
--If trimming results in a string of len or more characters, the function returns str unmodified.
--returns NULL if any of the arguments is NULL.

Examples
string_lrepad("abc", 5) "abc"
string_lrepad(" abc ", 5, "#") "##abc"
string_lrepad("abcdefgh", 5, "#") "abcdefgh"

16) string_lrtrim
Returns a string trimmed of leading and trailing blank characters.

Ab-Initio : Inbuilt String Functions() 8

Syntax
string string_lrtrim(string str)

Argument
str A string

Note: The function returns NULL if the argument is NULL.

Examples
string_lrtrim(" abc ") "abc"
string_lrtrim("John") "John"

17) string_ltrim
Returns a string trimmed of leading blank characters.

Syntax
string string_ltrim(string str)

Argument
str A string

Note: The function returns NULL if the argument is NULL.

Examples
string_ltrim(" abc") "abc"
string_ltrim("John") "John"
string_ltrim(U"\u2000Joe") U"Joe

18) string_pad
Returns a right-padded string.

Syntax
string string_pad(string str, int len [ , string pad_char ] )

Arguments
Str A string
Len A length in number of characters
pad_char A single character. If you do not supply pad_char, the value of pad_char
is blank.

Details
The string_pad function pads str on the right with the character pad_char to make the string len
length. If str is already len or more characters long, the function returns str unmodified.

Ab-Initio : Inbuilt String Functions() 9

Examples
string_pad("abc", 5) "abc"
string_pad("abc", 5, "#") "abc##"
string_pad("abcdefgh", 5, "#") "abcdefgh"

19) string_repad
Returns a string trimmed of any leading and trailing blank characters and then right-padded
with a specified character to a specified length.

Syntax
string string_repad(string str, int len [ , string pad_char ] )

Arguments
Str A string
len A length in number of characters
pad_char A single character. If you do not supply pad_char, the value of pad_char is
blank.

Note: The function returns NULL if any of the arguments is NULL.

Examples
string_repad("abc", 5) "abc"
string_repad(" abc ", 5, "#") "abc##"
string_repad("abcdefgh", 5, "#") "abcdefgh

20) string_trim
Returns a string trimmed of trailing blank characters.

Syntax
string string_trim(string str)

Argument
str A string

Notes: The function returns NULL if the argument is NULL.

Examples
string_trim("abc") "abc"
string_trim("John") "John"
string_trim(U"\u2000Joe") U"\u2000Joe"
string_trim(U"Joe\u2000") U"Joe"

Ab-Initio : Inbuilt String Functions() 10

21) decimal_lpad
Returns a decimal string of at least the specified length, by discarding invalid decimal
characters, and then left-padding if necessary. It is useful if you want to convert a very long
space-padded decimal to a shorter zero-padded decimal.

Syntax
string decimal_lpad(string str, int len [ , string pad_char] )

Arguments
Str A string. If str contains a minus sign, the function moves the minus sign to
the left of any padding, or to the left of the first digit.
len A length in number of characters.
pad_char A single character. If you do not specify pad_char, its value defaults to 0
(zero).

Note:
The function returns NULL if any of the arguments is NULL.

Examples
decimal_lpad("-42", 5) "-0042"
decimal_lpad("junk42junk37",5) "00042"
decimal_lpad("42", 5, "#") "###42"
decimal_lpad("0042 ", 5, "#") "#0042"
decimal_lpad("42, 4) "0042" ( represents a space)

22) decimal_lrepad
Returns a decimal string trimmed of any leading zeros and left-padded with a specified
character to a specified length.

Syntax
string decimal_lrepad(string str, int len [ , string pad_char] )

Arguments
Str A string. The function ignores non-numeric characters. If str contains a
minus sign, the function moves the minus sign to the left of any padding
len A length in number of characters.
pad_char A single character. If you do not specify pad_char, it defaults to 0 (zero).

Details
The decimal_lrepad function trims str of any leading zeros and pads it on the left with enough
occurrences of character pad_char to make the resulting string have length len.

Examples
decimal_lrepad("42", 5) "00042"
decimal_lrepad("-42", 5) "-0042"
decimal_lrepad("42", 5, "#") "###42"

Ab-Initio : Inbuilt String Functions() 11

decimal_lrepad("0042", 5, "#") "###42"

NOTE: The function returns the same value for the third and fourth examples, because
decimal_lrepad trims leading zeros.

23) decimal_strip
Returns a decimal from a string that has been trimmed of leading zeros and non-numeric
characters.

Syntax
decimal decimal_strip(string str)

Argument
str A string.

The function returns NULL if the argument is NULL.

Examples
decimal_strip("-0042 ") "-42"
decimal_strip("42abc") "42"
decimal_strip("+$42") "42"
decimal_strip("garbage") "0"
decimal_strip((decimal(10.4))"0123456.90") "123456.90"

24) char_string
Returns a 1-character native string that corresponds to the specified character code

Syntax
string char_string(int char_code)

Argument
char_code The specified character code

Example
char_string(97)  "a"

25) string_char
Returns the character code of a specific character in a string.

Syntax
long string_char(string str, int index)

Ab-Initio : Inbuilt String Functions() 12

Arguments
Str A string
Index The index of a character in str

Details
The string_char function returns:
The character code of the specified character; this code is in the character set used by str.
NULL if index is out of bounds, or if either of the arguments evaluates to NULL.
Strings are indexed starting at 1.

Examples
string_char("a", 1) 97
string_char((ebcdic string(1))"a", 1) 129
string_char("xyz", 4) NULL

26) is_blank
Tests whether a string contains only blank characters.

Syntax
long is_blank(string str)

Argument
str A string to test

Details
The is_blank function returns:
- 1 if str contains only blank characters, or is a zero-length string
- 0 if str contains one or more characters and at least one of the characters is not blank
- NULL if str is NULL

Examples
is_blank("") 1
is_blank("abc") 0
is_blank("") 1
is_blank(".") 0

27) is_bzero
Tests whether an object is composed of all binary zero bytes.

Syntax
long is_bzero(dml_object object_to_test)

Argument
object_to_test An object to test. The object can be of any DML type.

Ab-Initio : Inbuilt String Functions() 13

Details
The is_bzero function returns:
- 1 if object_to_test contains only binary zero bytes, or is a zero-length string
- 0 if object_to_test contains any non-zero bytes
- NULL if object_to_test is NULL

Examples
is_bzero("") 1
is_bzero([ record x 0 y 0 ]) 1
is_bzero("0") 0
is_bzero(1000) 0
is_bzero("abc") 0

28) make_byte_flags
Returns a vector of flags reporting whether a character occurs in a string.

Syntax
integer (1)[ ] make_byte_flags(string str)

Argument
str A string of characters

Details
make_byte_flags is one of three interrelated DML functions that allow you to test for the
presence of characters in strings.

Call test_characters_any or test_characters_all as often as needed, passing the string you want
to test and the appropriate flags vector for the characters you are testing for.
NOTE: These functions operate only on ASCII and EBCDIC strings.

Examples
To check whether a given string str is all numeric:

let integer(1) [] numeric_flags = make_byte_flags("0123456789");

out::all_numeric(str) =
begin
out :: test_characters_all(str, numeric_flags);
end

To check whether a string str has any digits:

out::any_numeric(str) =
begin
out :: test_characters_any(str, numeric_flags);
end

29) re_get_match

Ab-Initio : Inbuilt String Functions() 14

Returns the first string that matches a regular expression.

Syntax
string re_get_match(string target_string, string pattern_expr)

Arguments
target_string An ASCII or EBCDIC string in which the function looks for a substring
that matches pattern_expr
NOTE: This function does not work on strings composed of Unicode
characters.
pattern_expr A regular expression

Details
The re_get_match function returns the first substring of target_string that matches the regular
expression pattern_expr. The function returns NULL if it finds no match.

Examples
re_get_match("man on the moon", "oo") "oo"
re_get_match("1234 Milldale Ave.", "[a-zA-Z]+") "Milldale"
re_get_match("1234 Milldale Ave.", "^[0-9]+") "1234"
re_get_match("Fourteen 35th St.", "^[0-9]+") NULL

30) re_index
Returns the index of the first character of a string matching a regular expression.

Syntax
long re_index(string target_string, string pattern_expr )

Arguments
target_string An ASCII or EBCDIC string in which the function looks for a substring
that matches pattern_expr
NOTE: This function does not work on strings composed of Unicode
characters.
pattern_expr A regular expression

Note: The function returns NULL if any of the arguments is NULL.

Examples
re_index("man on the moon", "oo") 13
re_index("1234 Milldale Ave.", "[a-zA-Z]+") 6
re_index("1234 Milldale Ave.", "^[0-9]+") 1
re_index("Fourteen 35th St.", "^[0-9]+") 0

31) re_replace
Returns a string after replacing all substrings matching a regular expression.

Ab-Initio : Inbuilt String Functions() 15

Syntax
string re_replace(string target_string, string pattern_expr, string new_string)

Arguments
target_string An ASCII or EBCDIC string in which the function looks for a
substring that matches pattern_expr
NOTE: This function does not work on strings composed of Unicode
characters.
pattern_expr A regular expression
new_string A replacement string

Note:
The function returns NULL if any of the arguments is NULL.

Examples
re_replace("man on the moon", "m[aeiou]+n", "X") "X on the X"
re_replace("a string with weird spacing", " +", " ") "a string with weird spacing"
re_replace("432 West 54th Street Suite 403", "[0-9]+", "[Number &]") "[Number 432]
West [Number 54]th Street Suite [Number 403]"
re_replace("Andy said this and that.", "[aA][nN][dD]", "\\&") "&y said this & that."

32) re_replace_first
Returns a string after replacing the first substring matching a regular expression.

Syntax
string re_replace_first(string target_string, string pattern_expr, string new_string)

Arguments
target_string An ASCII or EBCDIC string in which the function looks for a
substring that matches pattern_expr
NOTE: This function does not work on strings composed of Unicode
characters.
pattern_expr A regular expression
new_string A replacement string

Example
re_replace_first("man on the moon", "m[aeiou]+n", "X") "X on the moon"

33) string_from_hex
Returns an ASCII string from a string of hexadecimal characters.

Ab-Initio : Inbuilt String Functions() 16

Syntax
string string_from_hex(string or void in_value [, integer pad_odd_size] )

Arguments
in_value A string or a void composed of an even number of characters,
unless pad_odd_size is set to 1 or greater
pad_odd_size Set this to 1 (or any positive number greater than zero) to cause the
function to pad an in_value having an odd number of characters

Note
For in_value having an even number of characters, the function returns a single byte with the
equivalent ASCII value.

If in_value contains an odd number of characters and pad_odd_size has the value 1 or
greater, the function pairs the final odd character in in_value with an implied trailing zero.

If in_value contains an odd number of characters and pad_odd_size is not specified or is
equal to zero, the function results in error.

Examples
m_eval "string_from_hex('616263')" "abc"
m_eval "string_from_hex('6162637', 1)" "abcp"

34) string_to_hex
Returns a string of hexadecimal digits in which each pair of digits represents the raw value of
one byte of the input string (or void).

Syntax
string string_to_hex(string or void in_value)

Argument
in_value A string or void type

Notes:
The function returns the value of each source byte as a pair of characters that represents the
hexadecimal value of the source byte. For example, the ASCII character a (0x61) is returned as
the 2-digit string 61.

The size of the returned string is always an even number of characters.

The function returns NULL if the argument is NULL.

Examples
m_eval "string_to_hex('abc')" "616263"
m_eval "string_to_hex('0123')" "30313233

Ab-Initio : Inbuilt String Functions() 17

35) test_characters_all
Tests a flags vector created with the make_byte_flags function for the presence of specified
characters in ASCII and EBCDIC strings.

Syntax
long test_characters_all(string str, integer(1)[ ] flags)

Arguments
str A string to test
flags The name of a flags vector created by the make_byte_flags function

Examples
To check whether a given string str is all numeric:-

let integer(1) [] numeric_flags = make_byte_flags("0123456789");

out::all_numeric(str) =
begin
out :: test_characters_all(str, numeric_flags);
end

To check whether a string str has any digits:

out::any_numeric(str) =
begin
out :: test_characters_any(str, numeric_flags);
end

36) test_characters_any
Tests a flags vector created with the make_byte_flags function for the presence of specified
characters in ASCII and EBCDIC strings.

Syntax
long test_characters_any(string str, integer(1)[ ] flags)

Arguments
str A string to test
flags The name of a flags vector created by the make_byte_flags function

Examples
To check whether a given string str is all numeric:

let integer(1) [] numeric_flags = make_byte_flags("0123456789");

out::all_numeric(str) =

Ab-Initio : Inbuilt String Functions() 18

 begin
out :: test_characters_all(str, numeric_flags);
end

To check whether a string str has any digits:

out::any_numeric(str) =
begin
out :: test_characters_any(str, numeric_flags);
end

37) unicode_char_string
Returns the Unicode string represented by the specified character code.

Syntax
unicode string unicode_char_string(int char_code)

Argument
char_code The character code of a Unicode character

Examples
Unicode_char_string(97) ‘a’

38) url_decode_escapes
Returns a string after replacing URL hexadecimal escape sequences with the corresponding
character.

Syntax
string url_decode_escapes(string str )

Argument
str The string to be decoded

Details
The url_decode_escapes function assumes that:
The str argument is a string containing URL hexadecimal escape sequences (%xx)
The character (%) introduces a pair of hexadecimal digits to be interpreted as an ASCII
character

Example
url_decode_escapes("xyx%5a") "xyxZ"

39) url_encode_escapes
Returns a string after introducing URL hexadecimal escape sequences.

Syntax

Ab-Initio : Inbuilt String Functions() 19

string url_encode_escapes(string str)

Argument
str The string to be encoded

Details
The url_encode_escapes function replaces ASCII character codes in the str argument with the
corresponding hexadecimal escape sequence (%xx) except for the character codes that
represent the following:

Alphanumeric characters
Safe characters:
$ Dollar sign
- Hyphen
_ Underscore
+ Plus sign
. Period

Extra characters:
! Exclamation point
* Asterisk
' Single quotation mark
( Opening parenthesis
) Closing parenthesis
, Comma

Example
url_encode_escapes("{}|") "%7b%7d%7c"

Ab-Initio : Inbuilt String Functions() 20