Caché ObjectScript Reference
$LENGTH
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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 on Caché Unicode support, refer to Unicode in Using Caché ObjectScript.
Encoded Strings
Caché supports strings that contain internal encoding. Because of this encoding, $LENGTH should not be used to determine the data content of a 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.
   IF $SYSTEM.Version.IsUnicode() {
   SET roman="test"
   WRITE !,$LENGTH(roman)," characters in: ",roman
   SET greek=$CHAR(964,949,963,964)
   WRITE !,$LENGTH(greek)," characters in: ",greek
   }
   ELSE {WRITE "This example requires a Unicode installation of Caché"}
 
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