The IDL_String class contains static methods that are available for all IDL strings. In addition, because IDL_String is a subclass of IDL_Variable, all of the IDL_Variable methods are also available.

Superclasses


IDL_Variable

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.

Examples


IDL_String::CapWords


The IDL_String::CapWords method capitalizes the beginning letter of all words within the string.

Examples


Create a sentence and print the result of CapWords on that sentence:

str = "hello fellow IDL user."
PRINT, str.CapWords( )

IDL prints:

Hello Fellow IDL User.

Pass in a character for the space argument, and include the optional keywords:

str = "helloNfellowniDLNuser."
PRINT, str.CapWords('n', /FOLD_CASE, /IGNORE_FIRST)

IDL prints:

helloNFellownIDLNUser.

Syntax


Result = var.CapWords( [Char] [, /FOLD_CASE] [, /IGNORE_FIRST] )

Return Value


A string with a value containing capitalized characters as specified by the given argument or keywords. If var is an array then Result is a string array of the same dimensions.

Arguments


Char

A string containing the character used to separate words. The default is a single space character.

Keywords


FOLD_CASE

Set this keyword to ignore case when searching for the Char character (only needed if Char is a letter A-Z or a-z).

IGNORE_FIRST

Set this keyword to ignore the capitalization of the first character.

IDL_String::CharAt


The IDL_String::CharAt method returns a character from the string.

Examples


Create a string and print the result given an index:

str = "IDL"
 
; Print the character at each index.
FOR i=0, str.StrLen( )-1 DO PRINT, str.CharAt(i)

IDL prints:

I
D
L

Syntax


Result = var.CharAt( Index )

Return Value


A string containing the character found at the given index. If var is an array then Result is a string array of the same dimensions.

Arguments


Index

The index of the character to return.

Keywords


None.

IDL_String::Compress


The IDL_String::Compress method removes all spaces and tabs within a string. This is equivalent to calling STRCOMPRESS with the REMOVE_ALL keyword.

Examples


Create a string with spaces:

str = " I D L is C o o l ! "
PRINT,  str.Strlen( )
newstr = str.Compress()
 
; Print the new string and its length.
PRINT, newstr, newstr.Strlen( )

IDL prints:

20
IDLisCool!
10

Syntax


Result = var.Compress( )

Return Value


The string with all white space removed. If var is an array then the result is a string array of the same dimensions.

Arguments


None.

Keywords


None.

IDL_String::Contains


The IDL_String::Contains method determines whether the string contains a given substring.

Examples


Determine whether each element of a string array contains a specific substring:

str = ['code.pro', 'image.jpg', 'file.txt']
PRINT, str.Contains('.pro')

IDL prints:

1  0  0

Syntax


Result = var.Contains( Substring, /FOLD_CASE )

Return Value


The result is a boolean value 1 (true) if the string contains the substring, or 0 otherwise. If var is an array then Result is a byte array of the same dimensions.

Arguments


Substring

The string to compare against.

Keywords


FOLD_CASE

Set this keyword to ignore case when doing comparisons.

IDL_String::Decrypt


The IDL_String::Decrypt method decrypts a string using the private key from a public/private key pair in the RSA asymmetric cryptosystem. See the Encrypt method below for details on the encryption method. You can use IDL to generate key pairs using the RSA_PRIVATE_KEY and RSA_PUBLIC_KEY functions.

Examples


clearText = 'xyzzy'
privateKey = RSA_PRIVATE_KEY(2048)
publicKey = RSA_PUBLIC_KEY(privateKey)
encrypted = clearText.Encrypt(publicKey)
decrypted = encrypted.Decrypt(privateKey)
print, decrypted

IDL prints:

xyzzy

Syntax


Result = var.Decrypt( PrivateKey )

Return Value


A string containing the decrypted value. If var is an array then Result is a string array of the same dimensions, where each string has been decrypted with the private key.

Arguments


PrivateKey

A scalar string or string array containing the private key to be used for decryption. PrivateKey should be an RSA Private Key (PKCS#1) in the PEM format:

-----BEGIN RSA PRIVATE KEY-----
MIIBOQIBAAJBAPOXacw2mXRlHhP8xBfwm+7GPKnPb6lqDfWdo/HWRj8qmezUMa28
0n7s1LUBWkbJ7l13vcZCyfaDsL7FEqIHqwsCAw...
-----END RSA PRIVATE KEY-----

If PrivateKey is a scalar string then all of the lines should be joined together with newline (ASCII code 10) characters. PrivateKey can also be specified as a string array containing the individual lines.

Keywords


None

IDL_String::Dup


The IDL_String::Dup method duplicates a scalar string and returns either another scalar string or an array.

Examples


IDL> a = '*'
IDL> print, a.Dup(10)
**********

 

IDL> b = a.Dup([6,5,2])
IDL> b.dim
    5            2
IDL> print, b
****** ****** ****** ****** ******
****** ****** ****** ****** ******

 

Syntax


Result = var.Dup( Dim )

Return Value


Returns either a scalar string (if Dim is a scalar), or a string array of one less dimension than Dim, where Dim[0] indicates the number of copies of var in each element.

Arguments


Dim

A scalar expression or a vector of up to eight elements. If Dim is a scalar equal to zero, then a scalar null string is returned, or if Dim is an array with Dim[0] = 0, then an array of null strings is returned.

Keywords


None

IDL_String::Encrypt


The IDL_String::Encrypt method encrypts the string using the RSA asymmetric cryptosystem, which requires a public key to encrypt and a private key to decrypt. As denoted by their names, the public key is shared with others, while the private key should be kept secret. You can use IDL to generate key pairs using the RSA_PRIVATE_KEY and RSA_PUBLIC_KEY functions.

The key size that was used when creating the public/private key pair determines the maximum string length that may be encrypted. Specifically, one character may be encrypted for every eight bits in the key. Additionally, IDL uses secure PKCS#1 OAEP padding, which further reduces the maximum string length by 42 characters. Typical key sizes and corresponding string lengths are listed below:

Key Size (bits)

Maximum String Length (bytes)

512 22
1024 86
2048 214
4096 470
8192 982

The maximum string length is given by (key size / 8) – 42.

Note: The National Institute of Standards and Technology (NIST) recommends a minimum RSA key size of 2048 bits.

Examples


clearText = 'xyzzy'
privateKey = RSA_PRIVATE_KEY(2048)
publicKey = RSA_PUBLIC_KEY(privateKey)
encrypted = clearText.Encrypt(publicKey)
print, encrypted

IDL prints:

A8GLhi0HzRiDGcg1RdPVl0YVm60oL5TjzDXpKIezxW4BuD8Z5N6Y7AJ+9eaL691...

Note: Because of the built-in randomness of RSA, calling the Encrypt method again on the same string will give a different result for each call.

Syntax


Result = var.Encrypt( PublicKey )

Return Value


A string containing the encrypted value. If var is an array then Result is a string array of the same dimensions, where each string has been encrypted with the public key.

Arguments


PublicKey

A scalar string or string array containing the public key to be used for encryption. PublicKey should be an X.509 SubjectPublicKeyInfo/OpenSSL key in the PEM format:

-----BEGIN PUBLIC KEY-----
MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAPOXacw2mXRlHhP8xBfwm+7GPKnPb6lq
DfWdo/HWRj8qmezUMa280n7s1LUBWkbJ7l13vcZCy...
-----END PUBLIC KEY-----

If PublicKey is a scalar string then all of the lines should be joined together with newline (ASCII code 10) characters. PublicKey can also be specified as a string array containing the individual lines.

Keywords


None

IDL_String::EndsWith


The IDL_String::EndsWith method determines whether the string ends with a given string.

Examples


Create a sentence and print the result of EndsWith on that sentence:

str = "hello fellow IDL user..."
 
; Check if the string ends with 3 periods.
PRINT, str.EndsWith('...')

IDL prints:

1

Syntax


Result = var.EndsWith( String [, /FOLD_CASE] )

Return Value


A boolean value of 0 (false) or 1 (true). If var is an array then Result is a byte array of the same dimensions.

Arguments


String

The string to compare against the end of the string variable.

Keywords


FOLD_CASE

Set this keyword to ignore case when doing comparisons.

IDL_String::Extract


The IDL_String::Extract method extracts the first substring that matches a regular expression.

Examples


Create a sentence and extract text out of it:

str = "Hello fellow IDL user."
PRINT, str.Extract('f[a-z]{5}')

IDL prints:

fellow

Syntax


Result = var.Extract( RegEx [, /FOLD_CASE] [, /SUBEXPR] )

Return Value


A string containing the extracted text. If var is an array then Result is a string array of the same dimensions.

Arguments


RegEx

A string giving the regular expression to match against. See Regular Expressions for details.

Keywords


FOLD_CASE

Set this keyword to ignore case when doing comparisons.

SUBEXPR

By default, IDL_STRING::Extract only returns a single string containing the overall match (or a string array if your variable was an array). Setting SUBEXPR causes it to return an array containing the overall match as well as any subexpression matches. A subexpression is any part of a regular expression written within parentheses. For example, the regular expression "abc+" has no sub-expressions while the regular expression "(a)(b)(c+)" has 3 subexpressions. For the regular expression "(a)(b)(c+)", the result will therefore be a 4-element vector: one for the overall match and three more for the subexpressions. If a subexpression participated in the match several times, the reported substring is the last one that matched.

Note: If your variable is an array then the result will be an array of one higher dimension, where the first dimension contains the sub expressions. For example, if var was a [10, 5] string array, and you use the regular expression "(a)(b)(c+)", then the result will be a [4, 10, 5] string array.

IDL_String::IndexOf


The IDL_String::IndexOf method returns the index of a character or sub-string within the string.

Examples


Create a string array with some data:

str = ["iaa", "aIa", "aai", "aaa"]
 
; Find the indexes for the letter i.
PRINT, str.IndexOf('i', /FOLD_CASE)

IDL prints:

0           1           2          -1

Syntax


Result = var.IndexOf( Substring [, Start] [, /FOLD_CASE] )

Return Value


An integer giving the index of the first match of the substring. If the substring is not found then -1 is returned. If var is an array then the result is an integer array of the same dimensions.

Arguments


Substring

A string giving the character or substring to search for.

Start

An optional index at which to start searching. If Start is beyond the string's length then -1 is returned.

Keywords


FOLD_CASE

Set this keyword to ignore case when doing comparisons.

IDL_String::Insert


The IDL_String::Insert method inserts text at a specified index within the string.

Examples


Create a sentence and print the result after insert:

str = "Hello IDL user."
 
; Insert at index 5.
PRINT, str.Insert(" fellow", 5)

IDL prints:

Hello fellow IDL user.

Extend the sentence and use the FILL keyword:

; The FILL keyword will add the space for us.
str = str.Insert("How are you?", 16, FILL=' ')
PRINT, str

IDL prints:

Hello IDL user. How are you?

Syntax


Result = var.Insert( String [, Index] [, FILL_CHARACTER=character] )

Return Value


The new string. If var is an array then Result is a string array of the same dimensions.

Arguments


String

If only the string argument is given, the method will insert the string at the end.

Index

An integer giving the index at which to insert the string.

Note: By default, if the index is not a valid index within var then the string will not be inserted; however, you can use the FILL keyword to insert fill characters to allow the new string to be inserted.

Keywords


FILL_CHARACTER

Set this keyword to a single string character that is used to fill empty space if the supplied index is outside of the string's length.

IDL_String::Join


The IDL_String::Join method collapses a one-dimensional string array into a single merged string or a multi-dimensional string array into an array where the first dimension has been merged.

Examples


Create a sentence to split:

str = ["Hello", "fellow", "IDL", "user."]
 
; Join the string array into a single string.
PRINT, str.Join('-')

IDL prints:

Hello-fellow-IDL-user.

Syntax


Result = var.Join( [Delimiter] )

Return Value


The merged string. If var is a multi-dimensional string array then Result is a string array of one less dimension since the first dimension has been collapsed.

Arguments


Delimiter

An optional separator string to use between the joined strings. If Delimiter is not specified, an empty string is used.

Keywords


None.

IDL_String::LastIndexOf


The IDL_String::LastIndexOf method returns the last index of a given substring within the string.

Examples


Create a string array with some data:

str = ["Apples", "Oranges", "Bananas", "Kiwis"]
 
; Find the last indexes for the letter a.
PRINT, str.LastIndexOf('a', /FOLD_CASE)

IDL prints:

0           2           5          -1

Syntax


Result = var.LastIndexOf( Substring [, /FOLD_CASE] )

Return Value


An integer giving the index of the last match of the substring. If the substring is not found then -1 is returned. If var is an array then the result is an integer array of the same dimensions.

Arguments


Substring

The character or string to search for.

Keywords


FOLD_CASE

Set this keyword to ignore case when doing comparisons.

 

IDL_String::Matches


The IDL_String::Matches method determines whether the string matches a regular expression.

Example


Use a regular expression to determine if a string contains a valid integer number:

str = ['123', '-123', ' 4 ', '123abc']
; line begin + optional whitespace + optional negative sign
; + some digits + optional whitespace + line end
result = str.Matches('^ *-?[0-9]+ *$')
PRINT, result

IDL prints:

1 1 1 0

Syntax


Result = var.Matches( RegEx, /FOLD_CASE )

Return Value


A boolean value of 1 if the given string matches the string, or 0 otherwise. If var is an array then the result is a byte array of the same dimensions.

Arguments


RegEx

A string giving the regular expression to be used for matching. See Regular Expressions for details.

Keywords


FOLD_CASE

Set this keyword to ignore case when doing comparisons.

IDL_String::Remove


The IDL_String::Remove method removes part of a string given the start and end index.

Examples


Create a string and remove a section from it:

str = 'An example IDL string'
PRINT, str.Remove(2, 9)

IDL prints:

An IDL string

Create a string and remove the last 4 characters:

str = 'myfilename.pro'
PRINT, str.Remove(-4)

IDL prints:

myfilename

Syntax


Result = var.Remove( StartIndex [, EndIndex] )

Return Value


A new string containing the original string, minus the part that was removed. If var is an array then the result is a string array of the same dimensions.

Arguments


StartIndex

An integer giving the starting position. If StartIndex is negative then it represents an index from the end. If StartIndex is beyond the end then nothing is removed.

EndIndex

An integer giving the ending position. This includes the character at that position. If EndIndex is negative then it represents an index from the end. If not specified or beyond the end then EndIndex will be set to the string length – 1.

Keywords


None.

IDL_String::Replace


The IDL_String::Replace method replaces any occurrences of text within the string with new text.

Examples


IDL> str = "Hello fellow IDL user."
IDL> print, str.Replace('fellow', 'friendly')
Hello friendly IDL user.
 
IDL> str = '.......'
IDL> print, str.replace('.', '*', 3)
***....
 
IDL> str = '.......'
IDL> print, str.replace('.', '*', -3)
....***

Syntax


Result = var.Replace( OldText, NewText [, Count] [, /FOLD_CASE] )

Return Value


A string variable containing the new string. If var is an array then the result is a string array of the same dimensions.

Arguments


OldText

Set this argument to the text you want to replace within the variable.

NewText

Set this argument to the text you want to be inserted in place of OldText.

Count

Set this optional argument to the number of occurrences to replace. By default all matches of OldText are replaced. If Count is negative, then the replacements are done starting from the end of the string.

Keywords


FOLD_CASE

Set this keyword to ignore case when doing comparisons.

IDL_String::Reverse


The IDL_String::Reverse method reverses the string.

Examples


Create a string to perform a reverse on:

str = "Racecar"
 
; Print  using reverse.
PRINT, str.Reverse( )

IDL prints:

racecaR

Syntax


Result = var.Reverse( )

Return Value


The new string. If var is an array then the result is a string array of the same dimensions.

Arguments


None.

Keywords


None.

IDL_String::Split


The IDL_String::Split method splits the string into substrings according to a specified regular expression.

Examples


Create a sentence to split:

str = "Hello fellow IDL user."
 
; Split using spaces and print the first element.
var = str.Split(' ')
PRINT, var[0]

IDL prints:

Hello

Note that unlike the STRSPLIT function, the Split method preserves all null characters. For example:

IDL> a = '/var/tmp/'
IDL> b = a.Split('/')
IDL> HELP, b
B               STRING    = Array[4]
IDL> PRINT, '   "' + b + '"'
  ""  "var"  "tmp"  ""

This behavior enables you to exactly reconstruct the original input string:

IDL> PRINT, b.Join('/')
/var/tmp/

Syntax


Result = var.Split( RegEx [, /FOLD_CASE] )

Return Value


A string array with values after the split.

Arguments


RegEx

A string giving the regular expression for where to perform the split. See Regular Expressions for details.

Keywords


FOLD_CASE

Set this keyword to ignore case when doing comparisons.

IDL_String::StartsWith


The IDL_String::StartsWith method determines whether the string starts with the supplied string.

Examples


Create a sentence to use StartWith on:

str = "Hello fellow IDL user."
 
; Print the result of StartsWith
PRINT, str.StartsWith('h')
 
; Perform the same with /FOLD_CASE
PRINT, str.StartsWith('h', /FOLD_CASE)

IDL prints:

0
1

Syntax


Result = var.StartsWith( String [, /FOLD_CASE] )

Return Value


A boolean value of 1 (true) or 0 (false). If var is an array then the result is a byte array of the same dimensions.

Arguments


String

The string to check against the beginning of the variable.

Keywords


FOLD_CASE

Set this keyword to ignore case when doing comparisons.

IDL_String::Strlen


The IDL_String::Strlen method determines the string length.

Examples


Create a sentence and check its length with Strlen:

str = "Hello fellow IDL user."
 
; Print the length of the string
PRINT, str.Strlen( )
 
; Now split the string and print the lengths
PRINT, (str.Split(' ')).Strlen()

IDL prints:

22
5   6   3   5

Syntax


Result = var.StrLen( )

Return Value


The length of the string. If var is an array then the result is an integer array of the same dimensions.

Arguments


None.

Keywords


None.

IDL_String::Substring


The IDL_String::Substring method returns a portion of the string given the start and end index.

Examples


Create a string and return only a portion of it:

str = 'An-IDL-string'
PRINT, str.Substring(3, 5)

IDL prints:

IDL

Now just supply the start index, and return the characters from that index to the end:

str = 'An-IDL-string'
PRINT, str.Substring(3)

IDL prints:

IDL-string

Finally, use a negative index to return characters from the end:

str = 'myfilename.pro'
PRINT, str.Substring(-3)

IDL prints:

pro

Syntax


Result = var.Substring( StartIndex [, EndIndex] )

Return Value


A string containing the specified substring. If var is an array then the result is a string array of the same dimensions.

Arguments


StartIndex

An integer giving the starting position. If StartIndex is negative then it represents an index from the end. If StartIndex is beyond the end then an empty string is returned.

EndIndex

An integer giving the ending position. This includes the character at that position. If EndIndex is negative then it represents an index from the end. If not specified or beyond the end then EndIndex will be set to the string length – 1. If EndIndex is less than StartIndex then an empty string is returned.

Keywords


None

IDL_String::ToByte


The IDL_String::ToByte method converts the string to a byte array.

Examples


Create a string and convert it to a byte array:

str = 'IDL'
 
; Print the byte values for each character
PRINT, str.ToByte( )
 
; Same thing but for a multi-dimensional array
PRINT, (['IDL', 'is', 'fun!']).ToByte()

IDL prints:

73   68  76
 
73   68  76   0
105 115   0   0
102 117 110  33

Syntax


Result = var.ToByte( )

Return Value


An array of byte values representing the characters of the string. If var is an array then the result is a byte array of one-higher dimension. The first dimension will have a length equal to the longest string in the array.

Arguments


None.

Keywords


None.

IDL_String::ToLower


The IDL_String::ToLower method converts the string to all lowercase characters.

Example


str = "Hello Fellow IDL User."
PRINT, str.ToLower( )

IDL prints:

hello fellow idl user.

Syntax


Result = var.ToLower( )

Return Value


A string with all characters converted to lowercase. If var is an array then the result is a string array of the same dimensions.

Arguments


None.

Keywords


None.

IDL_String::ToUpper


The IDL_String::ToUpper method converts the string to all uppercase characters.

Examples


str = "Hello Fellow IDL User."
PRINT, str.ToUpper( )

IDL prints:

HELLO FELLOW IDL USER.

Syntax


Result = var.ToUpper( )

Return Value


A string with all characters converted to uppercase. If var is an array then the result is a string array of the same dimensions.

Arguments


None.

Keywords


None.

IDL_String::Trim


The IDL_String::Trim method removes any leading and trailing spaces or tabs from the string. This is equivalent to calling STRTRIM with Flag = 2.

Examples


Create a string with spaces before and after text:

str = " IDL is Cool! "
PRINT,  str.Strlen( )
trim_str = str.Trim()
 
; Print the trimmed string and its length
PRINT, trim_str, trim_str.Strlen( )

IDL prints:

14
IDL is Cool!
12

Syntax


Result = var.Trim( )

Return Value


The string with leading and trailing spaces and tabs removed. If var is an array then the result is a string array of the same dimensions.

Arguments


None.

Keywords


None.

Version History


8.4

Introduced

8.8.3

Added Encrypt and Decrypt methods

9.1 Added Count argument to Replace

See Also


Static Methods and Attributes, Variable Attributes, IDL_Integer, IDL_Number, IDL_Pointer, IDL_Variable