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 console.

Tip: Once an IDL string is created, you can use any of the IDL_String methods on that variable.

Examples

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

B = STRING(A)

Syntax

Result = STRING( Expression1, ..., Expressionn [, AM_PM=[string, string]] [, DAYS_OF_WEEK=string_array{7 names}] [, FORMAT=value] [, /IMPLIED_PRINT] [, MONTHS=string_array{12 names}] [, /PRINT] )

Return Value

Returns a string value or array of the same dimensions as Expression.

Note: If Expression includes complex numbers, STRING returns strings of the format (real, complex) unless FORMAT is specified.

Note: If Expression is a byte array and the FORMAT keyword is not specified, then the bytes will automatically be concatenated into a scalar string using the corresponding ASCII values. See Differences Between STRING and PRINT for details.

Note: If Expression is a byte array that contains a null (zero) value, the resulting string will be truncated at that position.

Note: If multiple expressions are provided, the result will be a string array with the same dimensions as the last expression, where all of the previous expressions are concatenated together. However, if 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 it is preferable to use the FORMAT keyword.

Arguments

Expressionn

The expressions to be converted to string type.

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 Formatted Input/Output.

IMPLIED_PRINT

Set this keyword to format the result using the same formatting rules as Implied Print.

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 processing for byte data 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.

IDL_String Methods

  • CapWords: Capitalize any words contained within the string.
  • CharAt: Returns the character at the supplied index.
  • Compress: Removes all white space.
  • Contains: Returns true if the string contains a given substring.
  • Decrypt: Decrypts the string using the RSA asymmetric cryptosystem.
  • Dup: Duplicates a scalar string.
  • Encrypt: Encrypts the string using the RSA asymmetric cryptosystem.
  • EndsWith: Returns true if the string ends with the given string.
  • Extract: Returns part of the string using a regular expression.
  • IndexOf: Returns the index of a character or substring.
  • Insert: Inserts another string.
  • Join: Combines multiple strings into a single string.
  • LastIndexOf: Returns the last index of a character or substring.
  • Matches: Returns true if the string matches a regular expression.
  • Remove: Remove part of a string.
  • Replace: Replaces text within the string.
  • Reverse: Reverse a string.
  • Split: Split into substrings using a regular expression.
  • StartsWith: Returns true if the string starts with the given string.
  • Strlen: Returns the string length.
  • Substring: Returns part of a string.
  • ToByte: Converts to a byte array.
  • ToLower: Convert all characters to lowercase.
  • ToUpper: Convert all characters to uppercase.
  • Trim: Removes leading and trailing white space.

Version History

Original

Introduced

See Also

String Operations, String Processing, IDL_String, BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, PRINT/PRINTF, UINT, ULONG, ULONG64