Str() vs. LTransform() vs. LIMSString()

Each of one of these beauties has their benefits and uses.  Knowing which one is best to use in a given situation can make the difference in your code you might be looking for.

Str() simply converts a numeric expression to a string and is very similar to LTransform(), but uses length and decimal specifications instead of mask like LTransform().  Its very useful when all you are juggling is numbers that need to be formatted as strings.  It looks like this:

Str(Numeric Expression, Length, Decimals)

I'm not going to explain what Numeric Expression means.  It should be obvious.  Length, though isth e length of the string to return, including the decimal point, digits and sign.  A value of -1 specifies that only the significant whole digits to the left of the decimal point are returned and suppresses any right padding.  Decimal places, however, are still returned as specified in Decimals.  If Length is not specified, the length returned is the actual length of the Numeric Expression.

Decimals is the number of decimal places in the return value.  A value of -1 specifies that only the significant digits to the right of the decimal point are returned.  The number of whole digits in the return value, however, are still determined by the Length argument.  If Decimals is not specified, the decimals returned is the actual decimals (if used) of the Numeric Expression.

The Str() function employs rounding.   If Length is less than the number of decimal digits required for the decimal portion of the returned string, the return value is rounded to the available number of decimal places.If Length is specified, but Decimals is omitted (no decimal places), the return value is rounded to an integer.


LTransform() is a little different.  It too can be used to just handle numbers but its more flexible than that.  It can convert any value into a formatted string.  It can format character, date, logical, and numeric values and   format the data for output to the screen or the printer.  The formatting is defined in the parameters.  It looks like this:

Ltransform(Value, Picture)

The usefulness of LTransform() is its ability to present data more cleanly or in a format without using clumsy lengths of concatenation or to perform transformations on data for presentation, like uppercasing all characters, specifying a comma position, or just enclosing negative numbers in a parenthesis.  The Picture parameter is formatted as follows:

Function string:  A picture function string that specifies formatting rules for the return value as a whole, rather than to particular character positions.  The function string consists of the @ character, followed by one or more additional characters as listed below.  If a function string is present, the @ character must be the leftmost character of the picture string, and the function string must not contain spaces.  A function string can be specified alone or with a template string.  If both are present, the function string must precede the template string, and the two must be separated by a single space.
Function                 Action
B                     Displays numbers left-justified
C                     Displays CR after positive numbers
D                     Displays date in SET DATE format
E                      Displays date in British format
R                     Non-template characters are inserted
X                     Displays DB after negative numbers
Z                     Displays zeros as blanks
(                      Encloses negative numbers in parentheses
!                      Converts alphabetic characters to uppercase

Template string:  A picture template string specifies formatting rules on a character by character basis.  The template string consists of a series of characters, some with a special meaning, as shown below.  Each position in the template string corresponds to a position in the Value.  Because Ltransform() uses a template, it can insert formatting characters such commas, dollar signs, and parentheses.Characters in the template string that have no assigned meaning are copied into the return value.  If the @R picture function is used, these characters are inserted between characters of the return value; otherwise, they overwrite the corresponding characters of the return value.  A template string can be specified alone or with a function string.  If both are present, the function string must precede the template string, and the two must be separated by a single space.

Template                     Action
A,N,X,9,#                      Displays digits for any data type
L                                    Displays logicals as "T" or "F"
Y                                   Displays logicals as "Y" or "N"
!                                     Converts an alphabetic character to uppercase
$                                    Displays a dollar sign in place of a leading space in a numeric
*                                    Displays an asterisk in place of a leading space in a numeric
.                                     Specifies a decimal point position
,                                     Specifies a comma position


LIMSString() is probably the most flexible of the three.  It can return any input except an array or object as a string.  Arrays can be handled if you break them down to values, such as Array[1] or Array[1,1].