Previous section   Next section

$LENGTH

Returns the number of characters or delimited substrings in a string.

Synopsis

$LENGTH(expression,delimiter)
$L(expression,delimiter)

Parameters

expression The target string. It can be a numeric value, a string literal, a variable name, or any valid expression that resolves to a string.
delimiter Optional — A string that demarcates separate substrings in the target string. It can be a variable name, a numeric value, a string literal, or any valid expression that resolves to a string.

Description

$LENGTH returns the number of characters in a specified string or the number of delimited substrings in a specified string, depending on the parameters used. Note that length counts the number of characters; an 8-bit character and a 16-bit wide (Unicode) character are both counted as one character. For further details, refer to Unicode in Using ObjectScript.
  • $LENGTH(expression) returns the number of characters in the string. If the expression is a null string, $LENGTH returns a 0. If expression is a numeric expression, it is converted to canonical form before determining its length. If expression is a string numeric expression, no conversion is performed. If expression is the $DOUBLE values INF, -INF, or NAN, the lengths returned are 3, 4, and 3, respectively.
    This syntax can be used with the $EXTRACT function, which locates a substring by position and returns the substring value.
  • $LENGTH(expression,delimiter) returns the number of substrings within the string. $LENGTH returns the number of substrings separated from one another by the indicated delimiter. This number is always equal to the number of delimiters in the string, plus one.
    This syntax can be used with the $PIECE function, which locates a substring by a delimiter and returns the substring value.
    If the delimiter is the null string, $LENGTH returns a 0. If the delimiter is any other valid string literal and the string is a null string, $LENGTH returns a 1.

Encoded Strings

InterSystems IRIS supports strings that contain internal encoding. Because of this encoding, $LENGTH should not be used to determine the data content of a string.
  • $LENGTH should not be used for a List structure string created using $LISTBUILD or $LIST. Because an InterSystems IRIS List string is encoded, the length returned does not meaningfully indicate the number of characters in the list elements. The sole exception is the one-argument and two-argument forms of $LIST, which take an encoded InterSystems IRIS List string as input, but outputs a single List element value as a standard character string. You can use the $LISTLENGTH function to determine the number of substrings (list elements) in an encoded list string.
  • $LENGTH should not be used for a bit string. Because an InterSystems IRIS bit string is encoded, the length returned does not meaningfully indicate the number of bits in the bit string. You can use the $BITCOUNT function, which returns the number of bits in the string.
  • $LENGTH should not be used for a JSON string. The value assigned by setting a variable to a JSON object or a JSON array is an object reference. Therefore the length of that variable value would be the length of the object reference, which has no connection to the length of the data encoded in the JSON string.

Surrogate Pairs

$LENGTH does not recognize surrogate pairs. Surrogate pairs are used to represent some Chinese characters and to support the Japanese JIS2004 standard. You can use the $WISWIDE function to determine if a string contains a surrogate pair. The $WLENGTH function recognizes and correctly parses surrogate pairs. $LENGTH and $WLENGTH are otherwise identical. However, because $LENGTH is generally faster than $WLENGTH, $LENGTH is preferable for all cases where a surrogate pair is not likely to be encountered.

Examples

In the following example, both $LENGTH functions return 4, the number of characters in the string.
   SET roman="test"
   WRITE !,$LENGTH(roman)," characters in: ",roman
   SET greek=$CHAR(964,949,963,964)
   WRITE !,$LENGTH(greek)," characters in: ",greek
In the following example, the first $LENGTH returns 5. This is the length of 74000, the canonical version of the specified number. The second $LENGTH returns 8, the length of the string “+007.4e4”.
   WRITE !,$LENGTH(+007.4e4)
   WRITE !,$LENGTH("+007.4e4")
In the following example, the first WRITE returns 11 the number of characters in var1 (including, of course, the space character). The second WRITE returns 2, the number of substrings in var1 using the space character as the substring delimiter.
   SET var1="HELLO WORLD"
   WRITE !,$LENGTH(var1)
   WRITE !,$LENGTH(var1," ")
The following example returns 3, the number of substrings within the string, as delimited by the dollar sign ($) character.
   SET STR="ABC$DEF$EFG",DELIM="$"
   WRITE $LENGTH(STR,DELIM)
If the specified delimiter is not found in the string $LENGTH returns 1, because the only substring is the string itself.
The following example returns a 0 because the string tested is the null string.
   SET Nstring = ""
   WRITE $LENGTH(Nstring)
The following example shows the values returned when a delimiter or its string is the null string.
   SET String = "ABC"
   SET Nstring = ""
   SET Delim = "$"
   SET Ndelim = ""
   WRITE !,$LENGTH(String,Delim)   ; returns 1
   WRITE !,$LENGTH(Nstring,Delim)  ; returns 1
   WRITE !,$LENGTH(String,Ndelim)  ; returns 0
   WRITE !,$LENGTH(Nstring,Ndelim) ; returns 0

See Also

Previous section   Next section