STRING

The STRING data type is a variable-length, dynamically allocated character string data type, without limitation.

Syntax

STRING

Usage

The behavior of a STRING variable is similar to the VARCHAR data type. For example, as VARCHAR variables, STRING variables have significant trailing blanks (i.e. "abc " is different from "abc"). There is no size limitation, it depends on available memory.

Unlike VARCHAR, a STRING can hold a value of zero length without being NULL. For example, if you trim a string variable with the trim() method and if the original value is a set of blank characters, the result is an empty string. But testing the variable with the IS NULL operator will evaluate to FALSE. Using a VARCHAR with the CLIPPED operator would give a NULL string in this case.

STRING variables are initialized to NULL in functions, modules and globals.

The STRING data type is typically used to implement utility functions manipulating character string with unknown size. It cannot be used to store SQL character string data, because databases have rules that need a maximum size as for CHAR and VARCHAR types.

Variables declared with the STRING data type can be used to methods such as getLength() or toUpperCase():

DEFINE s STRING
LET s = "abcdef"
DISPLAY s.toUpperCase()

In STRING methods, positions and length parameters (or return values) can be expressed in bytes or characters, depending on the length semantics used in programs.

Methods

Table 1. Object methods for the STRING data type
Name	Description
append(`part` STRING) RETURNING `result` STRING	Returns a new string made by adding `part` to the end of the current string.
equals(`source` STRING) RETURNING `result` INTEGER	Returns `TRUE` if the string passed as parameters matches the current string. If one of the strings is `NULL` the method returns `FALSE`.
equalsIgnoreCase( `source` STRING ) RETURNING `result` INTEGER	Returns `TRUE` if the string passed as parameters matches the current string, ignoring character case. If one of the strings is `NULL` the method returns `FALSE`.
getCharAt(`pos` INTEGER) RETURNING `result` STRING	Returns the character at the position `pos` (starts at 1). The unit for character positions depend on the length semantics. In BLS, the method returns `NULL` if `pos` does not match a valid character-byte position in the current string.
getIndexOf( `part` STRING, `spos` INTEGER ) RETURNING `result` INTEGER	Returns the position of the substring `part` in the current string, starting from position `spos`. The unit for character positions depend on the length semantics used. Returns zero if the substring was not found. Returns -1 if string is `NULL`.
getLength() RETURNING `result` INTEGER	Returns the lenfth of the string, including trailing blanks (Note that the `LENGTH()` built-in function ignores trailing blanks). The unit for character length depend on the length semantics used.
subString( `spos` INTEGER, `epos` INTEGER ) RETURNING `result` STRING	Returns the substring starting at position `spos` and ending at `epos`. The unit for character positions depend on the length semantics used. In BLS, returns `NULL` if the positions do not delimit a valid substring in the current string.
toLowerCase() RETURNING `result` STRING	Converts the current string to lowercase. Returns `NULL` if the string is null.
toUpperCase() RETURNING `result` STRING	Converts the current string to uppercase. Returns `NULL` if the string is null.
trim() RETURNING `result` STRING	Removes white space characters from the beginning and end of the current string. Returns `NULL` if the string is null.
trimLeft() RETURNING `result` STRING	Removes white space characters from the beginning of the current string. Returns `NULL` if the string is null.
trimRight() RETURNING `result` STRING	Removes white space characters from the end of the current string. Returns `NULL` if the string is null.

MAIN
  DEFINE s STRING
  LET s = "abcdef  " -- With 2 trailing blanks!
  DISPLAY s || ": "||s.getLength() -- Displays [abcdef  : 6]
  IF s.trimRight() = "abcdef" THEN
     DISPLAY s.toUpperCase() -- Displays [ABCDEF]
  END IF
END MAIN