Chapter 25 Caché Function Collection $LENGTH Function

Returns the number of characters in the string or substring with delimiters.

Outline

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

parameter

expression target string. It can be a numeric value, string literal, variable name, or any valid expression that can be parsed as a string.
delimiter Optional-A string that divides individual substrings in the target string. It can be a variable name, numeric value, string literal or any valid expression that can be parsed into a string.

description

$LENGTHReturn the number of characters in the specified string or the number of delimited substrings in the specified string according to the parameters used. Please note that length counts the number of characters; both 8-bit characters and 16-bit wide (Unicode) characters are treated as one character.

$LENGTH（expression）Returns the number of characters in the string. If the expression is an empty string, $LENGTH0 is returned. If the expression is a numeric expression, convert it to canonical form before determining its length. If expression is a string numeric expression, no conversion is performed. If expression is a $DOUBLEvalue INF, -INFor NAN, the returned length is 3, 4, and 3, respectively.

This syntax can be used with a $EXTRACTfunction that finds a substring by position and returns the value of the substring.

$LENGTH（expression，delimiter）Returns the number of substrings in the string. $LENGTHReturns the number of substrings separated from each other by the specified delimiter. This number is always equal to the number of delimiters in the string plus one.

This syntax can be used with a $PIECEfunction that finds a substring by delimiter and returns the value of the substring.

If the delimiter is an empty string, $LENGTH0 is returned. If the delimiter is any other valid string literal, and the string is an empty string, then $LENGTH1 is returned.

Encoding string

Caché supports strings containing internal codes. Because of this encoding, it $LENGTHshould not be used to determine the data content of the string.

$LENGTHIt should not be used to use $LISTBUILDor $LISTcreate List structure strings. Because the Caché List string is encoded, the length returned does not meaningfully indicate the number of characters in the list element. The only exception is $LISTthe one-parameter form and the two-parameter form, which use the encoded Caché List string as input, but output a single List element value as a standard string. You can use $LISTLENGTHfunctions to determine the number of substrings (list elements) in the encoded list string.
$LENGTHDoes not apply to bit strings. Since the Caché bit string is encoded, the length returned does not meaningfully indicate the number of bits in the bit string. You can use a $BITCOUNTfunction, which returns the number of bits in a string.
$LENGTHDoes not apply to JSON strings. The value assigned by setting the variable as a JSON object or JSON array is an object reference. Therefore, the length of the variable value will be the length of the object reference, which has nothing to do with the length of the data encoded in the JSON string.

Surrogate pair

$LENGTHThe surrogate pair cannot be recognized. The surrogate pair is used to represent certain Chinese characters and supports the Japanese JIS2004 standard. You can use $WISWIDEfunctions to determine whether the string contains surrogate pairs. $WLENGTHThe function can identify and correctly parse the surrogate pair. $LENGTHAnd $WLENGTHthe same in other areas. However, since it $LENGTHis usually $WLENGTHfaster, it $LENGTHis preferable for all situations where it is unlikely to encounter a surrogate pair .

Example

In the example below, both $LENGTHfunctions return 4, which is the number of characters in the string.

/// d ##class(PHA.TEST.Function).LENGTH()
ClassMethod LENGTH()
{
    
    
	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 "此示例需要Caché的Unicode安装"}
}

DHC-APP>d ##class(PHA.TEST.Function).LENGTH()
 
4 characters in: test
4 characters in: τεστ

In the example below, the first one $LENGTHreturns 5. This is the length of 74000, the canonical version of the specified number. The second one $LENGTHreturns 8, which is “+007.4e4”the length of the string .

/// d ##class(PHA.TEST.Function).LENGTH1()
ClassMethod LENGTH1()
{
    
    
   WRITE !,$LENGTH(+007.4e4)
   WRITE !,$LENGTH("+007.4e4")
}

DHC-APP> d ##class(PHA.TEST.Function).LENGTH1()
 
5
8

In the example below, the number of characters in the first WRITEreturn 11var1(including space characters of course). The second one WRITEreturns 2, which is the var1number of substrings in the substring using space characters as the substring delimiter .

/// d ##class(PHA.TEST.Function).LENGTH2()
ClassMethod LENGTH2()
{
    
    
	SET var1="HELLO WORLD"
	WRITE !,$LENGTH(var1)
	WRITE !,$LENGTH(var1," ")
}

DHC-APP>d ##class(PHA.TEST.Function).LENGTH2()
 
11
2

The following example returns 3, the number of substrings in the string, $separated by the dollar sign ( ) character.

DHC-APP>SET STR="ABC$DEF$EFG",DELIM="$"
 
DHC-APP>WRITE $LENGTH(STR,DELIM)
3

If the specified delimiter is not found in the string, it $LENGTHreturns 1 because the only substring is the string itself.

The following example returns 0 because the tested string is an empty string.

DHC-APP>SET Nstring = ""
 
DHC-APP>WRITE $LENGTH(Nstring)
0

The following example shows the value returned when the separator or its string is an empty string.

/// d ##class(PHA.TEST.Function).LENGTH3()
ClassMethod LENGTH3()
{
    
    
	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
}

DHC-APP>d ##class(PHA.TEST.Function).LENGTH3()
 
1
1
0
0