Routines (alphabetical) > Routines: S > STRING

STRING

The STRING function returns its arguments converted to string type. It is similar to the PRINT procedure, except that its output is placed in a string rather than being output to the terminal. The case in which a single expression of type byte is specified without the FORMAT keyword is special—see the Differences Between STRING and PRINT for details.

Note: Applying the STRING function to a byte array containing a null (zero) value will result in the resulting string being truncated at that position.

Syntax

Result = STRING( Expression₁, ..., Expression_n [, AM_PM=[string, string]] [, DAYS_OF_WEEK=string_array{7 names}] [, FORMAT=value] [, MONTHS=string_array{12 names}] [, /PRINT] )

Return Value

Returns a string value or array of the same dimensions as the result of the Expression. If Expression includes complex numbers, STRING returns strings of the format (real, complex).

Arguments

Expression_n

The expressions to be converted to string type.

Note: If you supply a comma-separated list of expressions without specifying a FORMAT, and the combined length of the expressions is greater than the current width of your tty or command log window, STRING will create a string array with one element for each expression, rather than concatenating all expressions into a single string. In this case, you can either specify a FORMAT, or use the string concatenation operator, “+”.

Keywords

AM_PM

Supplies a string array of 2 names to be used for the names of the AM and PM string when processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the FORMAT keyword.

DAYS_OF_WEEK

Supplies a string array of 7 names to be used for the names of the days of the week when processing explicitly formatted dates (CDWA, CDwA, and CdwA format codes) with the FORMAT keyword.

FORMAT

A format string to be used in formatting the expressions. See Using Explicitly Formatted Input/Output.

MONTHS

Supplies a string array of 12 names to be used for the names of the months when processing explicitly formatted dates (CMOA, CMoA, and CmoA format codes) with the FORMAT keyword.

PRINT

Set this keyword to specify that any special case processing should be ignored and that STRING should behave exactly as the PRINT procedure would.

Differences Between STRING and PRINT

The behavior of STRING differs from the behavior of the PRINT procedure in the following ways (unless the PRINT keyword is set):

When called with a single non-byte argument and no format specification, STRING returns a result that has the same dimensions as the original argument. For example, the statement:

HELP, STRING(INDGEN(5))

gives the result:

<Expression> STRING = Array[5]

while:

HELP, STRING(INDGEN(5), /PRINT)

results in:

<Expression> STRING =' 0 1 2 3 4'

If called with a single argument of byte type and the FORMAT keyword is not used, STRING simply stores the unmodified values of each byte element in the result. This result is a string containing the byte values from the original argument. Thus, the result has one less dimension than the original argument. For example, a 2-dimensional byte array becomes a vector of strings, a byte vector becomes a scalar string. However, a byte scalar also becomes a string scalar. For example, the statement:

PRINT, STRING([72B, 101B, 108B, 108B, 111B])

produces the output Hello because the argument to STRING, is a byte vector. Its first element is a 72B which is the ASCII code for “H”, the second is 101B which is an ASCII “e”, and so forth.

If both the FORMAT and PRINT keywords are not present and STRING is called with more than one argument, and the last argument is a scalar string starting with the characters “$(” or “(”, this final argument is taken to be the format specification, just as if it had been specified via the FORMAT keyword. This feature is maintained for compatibility with version 1 of VMS IDL.

Examples

To convert the contents of variable A to string type and store the result in variable B, enter:

B = STRING(A)

Version History

Original

Introduced