Returns the number of characters in an expression that can fit within a specified field width.
||A string expression.
||An integer expression that specifies field width.
||Optional A numeric expression that specifies the pitch value to use for full-width characters. The default is 2. Other permissible values are 1, 1.25, and 1.5.
is a DSM-J function available in ObjectScript. $ZPOSITION
returns the number of characters in expression
that can fit within the field
value. The pitch
value determines the width to use for full-width characters. All other characters receive a default width of 1 and are considered to be half-width. Because half-width characters count as 1, field
also expresses the number of half-width characters that fit in field
adds the widths of the characters in the expression
one at a time until the cumulative width equals the value of field
or until there are no more characters in expression
. The result is thus the number of characters that will fit within the specified field
value including any fractional part of a character that would not completely fit.
$ZPOSITION can be abbreviated as $ZP in DSM-J mode. This abbreviation cannot be used in InterSystems IRIS mode.
In the following example, assume that the variable string
contains two half-width characters followed by a full-width character.
In the above example, the first two characters in string
fit in the specified field width with one left over. The third character in string
, a full-width character with a width of 1.5 (determined by the pitch argument), would not completely fit, although two thirds (1/1.5) of the character would fit. The fractional part of the result indicates that fact.
In the following example, string
is now a string that contains a full-width character followed by two half-width characters. The result returned is 2.5:
The results are now different. This is because the first two characters, which have a combined width of 2.5, would completely fit with .5 left over. Even so, only half of the third character (.5/1) would fit.
Finally, if string
is a string that contains three half-width characters then all three characters would completely (and exactly) fit, and the result would be 3: