The Str package provides services for manipulating Strings. The major functionalities offered in the Str Package are the following:
String CR
Carriage return character constant.
String CRLF
Carriage return, linefeed constant.
Error E_Truncation
String truncation error constant.
String LF
Linefeed character constant.
Integer OldEncoding
Old encoding algorithm constant. When specified as the optional third parameter to Encode() and Decode(), these functions will use the old encoding algorithm (for backward compatibility only).
String TAB
Tab character constant.
Dynamic Ascii( Dynamic value )
Converts an ASCII value to a String, or converts a String to an ASCII value.
Here is a short example:
String aString = Str.Ascii( 65 ) + Str.Ascii( 94 ) + Str.Ascii( 77 ) Echo( aString ) Integer aNumber = Str.Ascii( aString ) Echo( aNumber )
The output of the example is:
A^M 65
Integer ByteLength( String aString)
Returns the length of aString in bytes rather than length in characters. These numbers will only be different on multibyte systems.
Assume you have a 3 character string called aString on a double byte system: echo('The command length( aString ) returns ' , length( aString), '.' ) echo('The command Str.ByteLength( aString ) returns ', Str.ByteLength( aString ), '.' )
The command length( aString ) returns 3. The command Str.ByteLength( aString ) returns 6.
Integer CSpn( String aString, String searchChars )
Returns the length of the longest initial segment of aString that consists of characters not in searchChars. See Str.Spn().
The following table summarizes the result of the Str.CSpn function for various Strings:
String CString( String aString, [String quoteChar] )
Returns a C-escaped version of the specified String. Newlines (\n), carriage returns (\r), tabs (\t), backslashes (\\), and quotes (\' or \") are escaped. quoteChar allows customization of the quote-escaping used.
Echo( Str.CString( '''Tis an example of: "Str.CString"' ) ) Echo( Str.CString( '''Tis an example of: "Str.CString"', "'" ) )
The output of the example is (note that the difference in the outermost enclosing quotes is due to output through Str.ValueToString()):
"'Tis an example of: \"Str.CString\"" '\'Tis an example of: "Str.CString"'
String Capitalize( String aString )
Returns a new String which is a capatalized version of aString.. The first letter of each word will be converted to uppercase, while following letters of each word will be converted to lowercase. See Str.Upper().
String s = 'Call the FBI.' Echo( '"', s, '"->"', Str.Capitalize( s ), '"' )
"Call the FBI."->"Call The Fbi."
String Catenate( List values, [String appendString] )
Returns a String which is a concatenation of each element of values, appending appendString after each element if it is specified. See Str.Elements() for performing the opposite function.
Remember that appendString is as a separator, but instead it is appended to each value, including the last value. Here is a short example:
String s = Str.Catenate( { 'a', 'b', 'c', 1, Date.Now() }, '+' ) Echo( s )
a+b+c+1+Mon Aug 24 17:04:46 1998+
Integer Chr( String aString, String ch )
Returns the index of the first occurrence, from left to right, of the first character of ch within the aString.
This function is most often used with a single character String specification for ch. If the ch is longer than one character, all characters other than the first character are ignored. See Str.RChr() to search from the end of the String.
Note that Chr() is case-sensitive. Here is a short example:
String s = 'abcdefg' Echo( "Str.Chr( 'abcdefg' ) for f = ", Str.Chr( s, 'f' ), ", k = ", Str.Chr( s, 'k' ), ", F = ", Str.Chr( s, 'F' ) )
Str.Chr( 'abcdefg' ) for f = 6, k = ?, F = ?
Integer Cmp( String string1, String string2, [Integer chars] )
Performs a case-sensitive ASCII value comparison of string1 to string2. Str.Cmp() is the OScript equivalent of C's strcmp() and strncmp(). See Str.CmpI() and Str.CmpBE().
Integer CmpBE( String string1, String string2 )
Performs a case-sensitive ASCII value comparison of string1 to string2, where the longer String is compared against the shorter as padded with trailing blanks ("Blank Extended") to make the strings equal in length. Note that this Blank Extension is only internal to the comparison, and does not alter string1 or strin2. See Str.Cmp() and Str.CmpIBE().
Integer CmpI( String string1, String string2, [Integer chars] )
Performs a case-insensitive ASCII value comparison of string1 to string2. Str.CmpI() is the case-insensitive version of Str.Cmp(). See Str.CmpIBE() as well.
Integer CmpIBE( String string1, String string2 )
Performs a case-insensitive ASCII value comparison of string1 to string2, where the shorter String is padded with trailing blanks ("Blank Extended") to make the strings equal in length. Note that this Blank Extension is only internal, and neither string1 nor string2 are affected. See Str.CmpI() and Str.CmpBE().
String Collapse( String aString )
Removes all spaces and tabs from a String.
String myString = 'Hi. How is' + Str.Tab() + 'Joe?' Echo( myString ) Echo( Str.Collapse ( myString ) )
Hi. How is Joe? Hi.HowisJoe?
String Compress( String aString )
Converts all sequences of one or more spaces or horizontal tabs to a single space character.
String zString zString = ' Abc ' + Str.Tab() + ' Def ' + ' Ghi' Echo( zString ) zString = Str.Compress( zString ) Echo( zString )
Abc Def Ghi Abc Def Ghi
String Decode( String aString, [Integer keyToEncode], [Integer version] )
Converts a String encoded by Str.Encode() back to ASCII text.
String EOL()
Deprecated.
Returns a line feed character.
Use System.EOL().
List Elements( String aString, String delimiter )
Extracts the segments of aString delimited by the first character of delimiter and returns the segments as elements in a List. The order of the elements within the list reflects their occurrence in the String. See Str.Catenate() for performing the opposite function.
List thelist = Str.Elements( 'a:b:c', ':' ) Echo( thelist )
{'a','b','c'}
String Encode( String aString, [Integer keyToEncode], [Integer version] )
Encodes/encrypts a String. An encoded String can be converted back to its original value with Str.Decode() using the same keyToEncode and version used to encode it.
String FileToString( String filename )
Returns the contents of a text file as a String. When Str.FileToString is called, operating system-specific line termination is converted to Str.CR line termination.
String fileString = Str.FileToString( 'c:\winnt\setuplog.txt' ) Echo( fileString )
Information: Setup configured the system to place a 139 MB pagefile on drive C:. ***
String Format( String format, [Dynamic arg<1>], [Dynamic arg<2>], [Dynamic arg<n>] )
This function returns a String formatted such that each included substitution indicator (%1...%9) is replaced by the corresponding substitution argument. Str.Format() is the OScript equivalent of the C language's sprintf() and printf(). However, numbers are used as format symbols instead of type identifiers since OScript is dynamically typed and numbers allow for alterations in substitution order as required for internationalization.
Note that Str.ValueToString(), not Str.String(), is called on all arguments which are not of type String. Here is an example:
Echo( Str.Format( "%4 has %1 %2, not %3 %2.", 2, "children", Str.String( 2.3 ), "Dinosaur Jr." ) )
Dinosaur Jr. has 2 children, not 2.3 children.
String FromBase64( String aString )
Decodes a String which was encoded using Base64. Base64 is a standard encoding for MIME content, described in RFC 1341. The encoded String consists only of printable ASCII characters, making it useful for exchanging data across networks and between platforms.
List Hyphenate( String aString, Integer maxLength )
Breaks a String into multiple segments, each of which is no longer than the number of characters specified in maxLength.
Note that in current implementations, the hyphens generated by Hyphenate() are counted outside of the String length, and thus Hyphenate may returns a segment which is one character longer than maxLength, and this character will be the generated hyphen. An example of this is:
Echo( Str.Hyphenate( "significantly", 8 ) )
Which produces:
{'signific-','antly'}
Here is a more typical example of Str.Hyphenate():
String sentence = "This sentence is disgustingly verbose, and it requires significant curtailing." List lines = Str.Hyphenate( sentence, 10 ) String line Echo( sentence ) Echo( lines ) for line in lines Echo( line ) end
This sentence is disgustingly verbose, and it requires significant curtailing. {'This','sentence','is','disgust-','ingly','verbose,','and it','requires','signific-','ant','curtail-','ing.'} This sentence is disgust- ingly verbose, and it requires signific- ant curtail- ing.
Boolean IntlSort( [Boolean newValue] )
Returns and optionally sets the international sorting mode. If international sorting is turned on, extended characters will sort properly, since international sorting accounts for multi-byte characters.
String Join( List values, [String joinString] )
Returns a String which is a concatenation of each element of values, inserting joinString between consecutive elements if it is specified. See Str.Elements() for performing the opposite function.
Remember that joinString is as a separator, and will not be included after the last value. Here is a short example:
a+b+c+1+Mon Aug 24 17:04:46 1998
Integer Locate( String searchInStr, String searchForStr )
Performs a case-sensitive search for the first occurrence of searchForStr within searchInStr. For a case-insensitive search, see Str.LocateI().
Integer LocateI( String searchInStr, String searchForStr )
Performs a case-insensitive search for the first occurrence of searchForStr within searchInStr. LocateI() ends in "I" due to the case-insensitivity; for a case-sensitive version, see Str.Locate().
String Lower( String aString )
Converts all alphabetic characters in the specified String to lowercase characters. See Str.Upper(), as well as Str.Capitalize().
Note that this function does not work with non-ASCII characters.
String s = 'Call the FBI.' Echo( '"', s, '"->"', Str.Lower( s ), '"' )
"Call the FBI."->"call the fbi."
String Quote( String aString, [String quote] )
This function adds either single or double quotation marks to the specified String.
String stringOne = "She can't remember" Echo( stringOne ) Echo( Str.Quote( stringOne ) ) Echo( Str.Quote( stringOne, '"' ) )
She can't remember 'She can''t remember' "She can't remember"
Integer RChr( String aString, String ch )
Locates the rightmost occurrence of the first character of ch within aString. See Str.Chr() for searching from the beginning of the String.
Echo( "Str.RChr( 'abcde', 'e' ) = ", Str.RChr( "abcde", "e" ) ) Echo( "Str.RChr( 'abcde', 'f' ) = ", Str.RChr( "abcde", "f" ) )
Str.RChr( 'abcde', 'e' ) = 5 Str.RChr( 'abcde', 'f' ) = ?
String Replace( String aString, String find, String replace )
Performs a single case-sensitive search and replace operation on a String. For a thorough search and replace see Str.ReplaceAll(). The Str.Replace function executes faster than the Pattern.Change function when searching for and replacing simple Strings.
String replaceString = 'A good apple is available.' Echo( replaceString ) Echo( Str.Replace( replaceString, 'a', 'b' ) )
A good apple is available. A good bpple is available.
String ReplaceAll( String aString, String find, String replace )
Performs an exhaustive case-sensitive search and replace on a String, returning a new String copy with all instances of the String find replaced with replace. Str.Replace() only replaces the first occurrence.
String s = "Even exercising weekly is energizing." Echo( s ) Echo( Str.ReplaceAll( s, "e", "3" ) )
Even exercising weekly is energizing. Ev3n 3x3rcising w33kly is 3n3rgizing.
String Set( Dynamic length, String value )
Returns a String of the specified length consisting solely of the first character in the specified String. This function is useful for creating formatted columns of text.
Echo( Str.Set( 8, "*" ), " Important Message ", Str.Set( 8, "!" ) )
******** Important Message !!!!!!!!
String SJis2Jis( String aString )
Converts a Shift-JIS String to JIS format. Livelink processes Japanese text as Shift-JIS internally, but JIS is often a more useful format for exchanging textual data across networks and between platforms.
A string to convert.
Integer Spn( String aString, String searchChars )
Determines the length of the maximum initial segment of aString that consists solely of characters that are in searchChars. See Str.CSpn().
The following table demonstrates the use and output of Str.Spn() for various Strings:
String SQLString( Dynamic value )
Converts the specified value to a String that can be used in a SQL statement. Unlike Str.String(), passing in a String value will return a different String. If an Error is specified, the message associated with that Error is returned.
Note that Str.SQLString() is meant for producing SQL usable strings. Cases where the value is being converted to a String for internal use such as storage or transmission, then Str.ValueToString() should be used instead. Also, cases where a user-presentable string is required, Str.String() should be used instead. Here is an example demonstrating the difference between Str.SQLString(), Str.String and Str.ValueToString() on several common data types:
List values = { "2 o'clock", 1, 27.8, Date.Now(), {'a', 'b', 'c'}, {12, 3.14, 18008675309}, { {1,2,3}, {4,5,6} } } Dynamic val for val in values Echo( 'Str.SQLString() is "', \ Str.SQLString( val ), \ '" while Str.String() is "',\ Str.String( val ), \ '" and Str.ValueToString() is "', \ Str.ValueToString( val ), \ '".' ) end
Str.SQLString() is "'2 o''clock'" while Str.String() is "2 o'clock" and Str.ValueToString() is "'2 o\'clock'". Str.SQLString() is "1" while Str.String() is "1" and Str.ValueToString() is "1". Str.SQLString() is "27.8" while Str.String() is "27.8" and Str.ValueToString() is "G27.8". Str.SQLString() is "Thu May 10 11:33:12 2012" while Str.String() is "Thu May 10 11:33:12 2012" and Str.ValueToString() is "D/2012/5/10:11:33:12". Str.SQLString() is "('a','b','c')" while Str.String() is "{'a','b','c'}" and Str.ValueToString() is "{'a','b','c'}". Str.SQLString() is "(12,3.14,18008675309)" while Str.String() is "{12,G3.14,L18008675309}" and Str.ValueToString() is "{12,G3.14,L18008675309}". Str.SQLString() is "((1,2,3),(4,5,6))" while Str.String() is "{{1,2,3},{4,5,6}}" and Str.ValueToString() is "{{1,2,3},{4,5,6}}".
String String( Dynamic value, [Boolean displayString] )
Converts the specified value to a presentable String. If a String value is specified, that same String value is returned. If an Error is specified, the message associated with that Error is returned.
Note that Str.String() is meant for producing presentable, or "display-friendly", String representations of a value. Cases where the value is being converted to a String for internal use such as storage or transmission, then Str.ValueToString() should be used instead. Here is an example demonstrating the difference between Str.String() and Str.ValueToString() on several common data types:
List values = { "A String", 1, 27.8, Date.Now() } Dynamic val for val in values Echo( 'Str.String() is "', \ Str.String( val ), \ '" while Str.ValueToString() is "', \ Str.ValueToString( val ), \ '".' ) end
Str.String() is "A String" while Str.ValueToString() is "'A String'". Str.String() is "1" while Str.ValueToString() is "1". Str.String() is "27.8" while Str.ValueToString() is "G27.8". Str.String() is "Wed Aug 26 19:46:23 1998" while Str.ValueToString() is "D/1998/8/26:19:46:23".
Integer StringToInteger( String aString )
Converts a String to an Integer. See Str.StringToReal() to convert a String containing a numerical value into a Real.
Here is an example testing various Strings.
List values = { '222.2345', '333', ' 898', '222 ', ' -27 ', ' - 27', ' +33 ' } String s for s in values Echo( 'Str.StringToInteger( "', s, '" ) = "', Str.StringToInteger( s ), '".' ) end
Str.StringToInteger( "222.2345" ) = "?". Str.StringToInteger( "333" ) = "333". Str.StringToInteger( " 898" ) = "898". Str.StringToInteger( "222 " ) = "222". Str.StringToInteger( " -27 " ) = "-27". Str.StringToInteger( " - 27" ) = "?". Str.StringToInteger( " +33 " ) = "33".
Real StringToReal( String aString )
Converts the specified String to a Real. See Str.StringToInteger() to convert a String containing a numerical value into an Integer.
Here is an example demonstrating the flexibility of Str.StringToReal():
List values = { '222.2345', ' -27 ', ' - 27', ' +33 ', ' 4.2e-7 ', '4.2e -7', '4.2E+7', '.004' } String s for s in values Echo( 'Str.StringToReal( "', s, '" ) = "', Str.StringToReal( s ), '".' ) end
Str.StringToReal( "222.2345" ) = "222.2345". Str.StringToReal( " -27 " ) = "-27". Str.StringToReal( " - 27" ) = "?". Str.StringToReal( " +33 " ) = "33". Str.StringToReal( " 4.2e-7 " ) = "4.2e-007". Str.StringToReal( "4.2e -7" ) = "?". Str.StringToReal( "4.2E+7" ) = "42000000". Str.StringToReal( ".004" ) = "0.004".
Dynamic StringToValue( String aString )
Converts a String resulting from the Str.ValueToString() back to a value of its original type. Strings for aString other than those created with ValueToString() can yield unpredictable results.
String Strip( String aString, String stripChars )
Removes all occurrences of the specified characters from a String.
String s = "No! I'm without space or punctuation." Echo( s ) Echo( Str.Strip( s, "! .'" ) )
No! I'm without space or punctuation. NoImwithoutspaceorpunctuation
String Substitute( String aString, Dynamic substitutions )
This function replaces tokens in aString with values from substitutions.
{ tokenName, value }
Str.Format() is easier to use for performing simple String substitution. Substitute() is only used when values are drawn directly from a RecArray or List, usually as the result of data processing or some query. Here is a short example:
String s = "The items are %1%, %two%, and %THREE%" List values = { { "1", "cats" }, \ { "two", "cows" }, \ { "three", Str.String( Date.Now() ) } } Echo( 'Str.Substitute( "', s, '" ) = "', Str.Substitute( s, values ), '".' )
Str.Substitute( "The items are %1%, %two%, and %THREE%" ) = "The items are cats, cows, and Tue Aug 25 21:24:37 1998".
String Tab()
This function returns a tab character. Using the Str.Tab function is preferable to using Str.Ascii() to generate a tab character, allowing the script to be run on a machine that does not use the ASCII character set.
String ToBase64( String aString )
Encodes the specified String using the Base64 encoding. Base64 is a standard encoding for MIME content, described in RFC 1341. The encoded String consists only of printable ASCII characters, making it useful for exchanging data across networks and between platforms.
String Trim( String aString )
Removes all leading and trailing white space from the specified String. White space is defined as any combination of spaces, form feeds, new lines, carriage returns, and horizontal or vertical tabs.
See Str.Collapse() for a function which removes internal spaces as well. Here is a short example:
String s = " " + Str.Tab() + "This is a sentence. " + Str.CRLF + Str.CRLF Echo( 'Str.Trim( "', s, '" ) = "', Str.Trim( s ), '".' )
Str.Trim( " This is a sentence. " ) = "This is a sentence.".
String Upper( String aString )
Converts all alphabetic characters in the specified String to uppercase. See Str.Lower(), as well as Str.Capitalize()
String s = 'Call the FBI.' Echo( '"', s, '"->"', Str.Upper( s ), '"' )
"Call the FBI."->"CALL THE FBI."
String ValueToString( Dynamic value )
Converts a value of any type to a String. The data type of the original value is retained in the String representation so that the resulting String can be converted back to a value of its original type with Str.StringToValue().
Note that ValueToString() differs from Str.String() in that it textually serializes values, while Str.String() converts values to a user-presentable format. The output of ValueToString() can be stored in a file, or sent across a socket, and be reconstituted at a different time or location.