| |
OScript API/Built-in Package Index |
The Str package provides services for manipulating Strings. The major functionalities offered in the Str Package are the following:
Carriage return character constant.
Carriage return, linefeed constant.
String truncation error constant.
Maximum number of arguments the Format method can have.
Linefeed character constant.
Old encoding algorithm constant.
Tab character constant.
Converts a string of ASCII characters into UTF-8.
Converts an ASCII value to a String, or converts a String to an ASCII value.
Returns the length of the aString in bytes. If the string contains any characters with codepoints greater than 127, this number will be greater than the value returned by Length().
Converts the first letter of all words in aString to uppercase and all other letters to lowercase.
Concatenates each element of values into a String, optionally adding the specified appendString after each element.
Locates the first occurrence, from left to right, of the first character of ch within_ aString_.
Performs a case-sensitive ASCII value comparison of string1 to string2.
Performs a case-sensitive ASCII value comparison of string1 to string2, where the shorter String is padded with trailing blanks ("Blank Extended") in the comparison to make the strings equal in length.
Performs a case-insensitive ASCII value comparison of string1 to string2.
Performs a case-insensitive ASCII value comparison of string1 to string2, where the shorter String is padded with trailing blanks ("Blank Extended") in the comparison to make the strings equal in length.
Removes all spaces and horizontal tabs from the specified String.
Converts all sequences of one or more spaces or horizontal tabs to a single space character.
Perform a one-way encryption on the input value
Returns the length of the maximum initial segment of aString that consists solely of characters that are not in searchChars.
Returns a C-escaped version of the specified String.
Converts a String encoded by the Str.Encode() back to ASCII text.
Extracts each segment of aString delimited by the first character of delimiter and returns the segments as elements in a List.
Returns an encoded version of the specified String.
Use System.EOL().
Returns the contents of a text file as a String.
Returns a String formatted such that each included substitution indicator (%1...%9) is replaced by the corresponding argument.
Returns a formatted string using the format string, formatString, and argument list, argList
Decodes a String which was encoded using Base64
Converts the initial character of a string to its Unicode codepoint. Returns Undefined if the string is empty.
Breaks a String into multiple segments, each of which is no longer than the number of characters specified in maxLength.
Returns and optionally sets the international sorting mode.
Returns TRUE if inputString contains non-ASCII UTF8 characters, else FALSE
Concatenates each element of values into a String like Str.Catenate(), but doesn't append the delimiting string after the final element in the list.
Escape a string for use in Javascript.
Performs a case-sensitive search for the first occurrence of searchForStr within searchInStr.
Performs a case-insensitive search for the first occurrence of searchForStr within searchInStr.
Converts all alphabetic characters in the specified String to lowercase characters.
Adds either single or double quotation marks to the specified String.
Locates the rightmost occurrence of the first character of string2 within string1.
Performs a case-sensitive search and replace operation on a String once. Returns undefined if the string to be replaced can't be found.
Performs a thorough case-sensitive search and replace operations on a String.
Returns a String of the specified length consisting solely of the first character in the specified String, as is useful for creating formatted columns of text.
Converts a Shift-JIS String to JIS format.
Converts a Shift-JIS String to UTF-8 format.
Determines the length of the maximum initial segment of aString that consists solely of characters in searchChars.
Converts the value to a string, similar to Str.String(), but returns a string that's designed to be included as part of an SQL statement.
Converts the specified value to a user-displayable String.
Converts the specified String to an Integer.
Converts the specified String to a Long.
Converts the specified String to a real number.
Converts a String resulting from Str.ValueToString() back to a value of its original type.
Removes all occurrences of the specified characters from a String.
Returns a String with tokens in aString replaced with values from substitutions.
Returns a tab character.
Encodes the specified String using the Base64 encoding
Converts a Unicode codepoint to a string containing the corresponding character.
Removes leading and trailing white space from the specified String.
Converts all alphabetic characters in the specified String to uppercase.
Converts a UTF-8 String to ASCII format.
Converts a UTF-8 String to Shift-JIS format.
Converts a value of any type to a String as for storage or transmission.
Carriage return character constant.
Carriage return, linefeed constant.
String truncation error constant.
Maximum number of arguments the Format method can have.
Linefeed character constant.
Old encoding algorithm constant. When specified as the optional third parameter to Str.Encode() and Str.Decode(), these functions will use the old encoding algorithm (for backward compatibility only).
Tab character constant.
Converts a string of ASCII characters into a UTF-8 string.
An ASCII string.
A UTF-8 string value, where each character of the input is encoded in UTF-8 format.
Converts an ASCII value to a String, or converts a String to an ASCII value. Use Str.ToUnicode() and Str.FromUnicode() instead.
Specifies either an Integer or a String. If an Integer is specified, it is converted to a one-character String corresponding to the specified ASCII value. If a String is specified, the first character of the String is converted to an Integer corresponding to the ASCII value of that character.
If an Integer is specified, a String consisting of its Big-Endian representation, with leading 0 bytes removed. If a String is specified, its initial character's internal representation is converted to an Integer and returned.
For Integer values from 0 to 127, this function safely converts between ASCII values and their corresponding characters. For values larger than 127, care must be taken that the Integer's representation corresponds to a valid UTF-8 encoding.
This method has been deprecated in favour of Str.ToUnicode() and Str.FromUnicode(), which convert to and from Unicode codepoints, and don't have the risk of generating invalid encodings.
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 ) // 50089 == 0xc3a9, so this will give us the character whose UTF-8 encoding is c3 a9. // In binary, c3 a9 == 11000011 10101001, so it encodes codepoint 0b000011101001, or 233. // 'é' corresponds to unicode codepoint 233. The binary representation of 233 is 0b000011101001, // which means its UTF-8 binary representation is 11000011 10101001, or the bytes c3 a9. // 0xc3a9 = 50089, which is the value that Str.Ascii will return. Integer anotherNumber = Str.Ascii( 'é' ) echo( anotherNumber ) // 1416151977 = 0x5468c3a9. 0x54 = 'T', 0x68 = 'h', and 0xc3a9 is 'é', as described above. // This means that Str.Ascii will actually produce a string containing the word 'Thé' String anotherString = Str.Ascii( 1416151977 ) echo( anotherString )
The output of the example is:
A^M 65 50089 Thé
Returns the length of aString in bytes rather than length in characters. If the string contains any characters with codepoints greater than 127, this number will be greater than the number of characters, as returned by Length().
A String whose length in bytes is returned.
An Integer specifying number of bytes used to represent aString in computer memory.
In UTF-8, the character '∈' and 'ℝ' are both encoded using three bytes, while 'x' only takes one byte.
String aString = "x∈ℝ" echo('The command length( aString ) returns ' , length( aString), '.' ) echo('The command Str.ByteLength( aString ) returns ', Str.ByteLength( aString ), '.' )
The output of the example is:
The command length( aString ) returns 3. The command Str.ByteLength( aString ) returns 7.
Returns a new String which is a capitalized 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().
Warning: This function does not work with non-ASCII characters.
The String for which a capitalized version is returned.
A copy of aString, but with the first letter of each word capitalized and all other letters in lowercase.
Here is a short example:
String s = 'Call the FBI.' Echo( '"', s, '"->"', Str.Capitalize( s ), '"' )
The output of the example is:
"Call the FBI."->"Call The Fbi."
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, and Str.Join() for version which places appendString only between elements, rather than after every element.
A List containing the values to concatenate. If any element of values is not of type String, a String representation of the value is appended to the resulting String.
Specifies an optional String to be appended after each element of the List in the return value. If not specified, the default value is the empty String ("").
A String concatenation, if successful; Undefined otherwise.
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 )
The output of the example is:
a+b+c+1+Mon Aug 24 17:04:46 1998+
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.
Specifies a String in which to search.
Specifies a String whose first character is to be located.
An Integer specifying the character position (from 1 to n) of the first character of ch if it is found within aString; Undefined otherwise.
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' ) )
The output of the example is:
Str.Chr( 'abcdefg' ) for f = 6, k = ?, F = ?
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().
The first String to compare.
The second String to compare.
Specifies an optional positive Integer indicating the maximum number of characters of string1 and string2 to compare. If not specified, both strings are compared in their entirety, or until a non-matching character is found.
|
Result |
Reason |
|
<0 |
string1 is less than string2. |
|
0 |
string1 is identical to string2. |
|
>0 |
string1 is greater than 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 string2. See Str.Cmp() and Str.CmpIBE().
The first String to compare.
the second String to compare.
|
Result |
Reason |
|
<0 |
string1 is less than string2. |
|
0 |
string1 is identical to string2. |
|
>0 |
string1 is greater than string2. |
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.
Warning: This method does not handle non-ASCII (codepoints 0-127) characters correctly.
The first String to compare.
The second String to compare.
Specifies an optional positive Integer indicating the maximum number of characters of string1 and string2 to compare. If not included, both strings are compared in their entirety, or until a non-matching character is found.
|
Result |
Reason |
|
<0 |
string1 is less than string2. |
|
0 |
string1 is identical to string2. |
|
>0 |
string1 is greater than 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().
Warning: This method does not handle non-ASCII (codepoints 0-127) characters correctly.
The first String to compare.
The second String to compare.
|
Result |
Reason |
|
<0 |
string1 is less than string2. |
|
0 |
string1 is identical to string2. |
|
>0 |
string1 is greater than string2. |
Removes all spaces and tabs from a String.
The String for which a spaceless and tabless version is returned.
A String, identical to the specified String, but with all spaces and horizontal tabs removed.
Here is a short example:
String myString = 'Hi. How is' + Str.Tab() + 'Joe?' Echo( myString ) Echo( Str.Collapse ( myString ) )
The output of the example is:
Hi. How is Joe? Hi.HowisJoe?
Converts all sequences of one or more spaces or horizontal tabs to a single space character.
The String for which a compressed version is returned.
A String, identical to the specified String, but with all sequences of one or more spaces or horizontal tabs converted to a single space character.
Here is a short example:
String zString zString = ' Abc ' + Str.Tab() + ' Def ' + ' Ghi' Echo( zString ) zString = Str.Compress( zString ) Echo( zString )
The output of the example is:
Abc Def Ghi Abc Def Ghi
Uses crypt() to perform a one-way encryption on the input value.
Input string value.
Cryptographic salt. If this parameter is not specified, then the default value of "LL" will be used.
If the parameter is specified, then the first two characters will be used as salt. If the length is less than two characters, a value derived from the current system time will be used instead.
The encrypted string.
Here is a short example:
String input = "Encrypt this string." Echo( Str.CryptOneWay( input, "XX" ) ) Echo( Str.CryptOneWay( input, "" ) ) Echo( Str.CryptOneWay( input ) )
The output of the example is:
XXxCrtyZzkcyzxD6dtmWn q6c/TaG3A4cu7noiYjqE0 LLJK71juBu0VdtDSLZoGR
Returns the length of the longest initial segment of aString that consists of characters not in searchChars. See Str.Spn().
A String to search.
A String containing the characters for which to search.
An Integer indicating the length of the segment of aString that contains no characters found in searchChars. If the first character of aString is a character in searchChars, the Integer value 0 is returned.
The following table summarizes the result of the Str.CSpn function for various Strings:
|
aString |
searchChars |
Returns |
Reason |
|
"floor" |
"or" |
2 |
"f" and "l" are not in the String "or". |
|
"bookcase" |
"olm" |
1 |
"b" is not in "olm" but character 2 ("o") is. |
|
"apricot" |
"j" |
7 |
"j" is not in "apricot". |
Returns a C-escaped version of the specified String. Newlines (\n), carriage returns (\r), tabs (\t), backslashes (\), and quotes (\' or \") are escaped.
Unicode characters will be escaped using universal character names: 16-bit character values will be escaped in hexadecimal format as \uHHHH, and 32-bit character values as \UHHHHHHHH.
quoteChar allows customization of the quote-escaping used.
The String for which a C-String is returned.
The quote character to escape; either a single (') or double (") quote. Double quote (") is the default.
A C-escaped version of the specified String.
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"'
Converts a String encoded by Str.Encode() back to ASCII text.
An encoded String returned by the Str.Encode() function.
An optional Integer corresponding to the keyToEncode value passed to the Str.Encode() function when the String was encoded. This parameter is only used if version is equal to Str.OldEncoding.
Specifies an optional version of the internal encoding algorithm used. Currently, Str.OldEncoding is the only meaningful value for this parameter.
The String originally passed to the Str.Encode() function.
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.
A String for which delimited elements are returned.
A String whose first character delimits the elements of aString.
A List containing String elements that consist of the delimited String segments of aString. The delimiter is not included in the returned List of elements.
Here is a short example:
List thelist = Str.Elements( 'a:b:c', ':' ) Echo( thelist )
The output of the example is:
{'a','b','c'}
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.
The String for which an encoded version is returned.
An optional Integer encoding key. This value is significant only in that the same value must be specified to decode the String. This parameter is ignored if version is not equal to Str.OldEncoding.
An optional version of the internal encoding algorithm used. Currently, Str.OldEncoding is the only meaningful value for this parameter.
An encoded version of the input String.
Returns a line feed character. Use System.EOL().
A String containing the line feed character.
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.
A String indicating the name of the file to convert, which should be the full file path if the file is not in the current working directory.
A String containing the contents of the file, or if the file does not exist or cannot be read as text, Undefined.
Here is a short example:
String fileString = Str.FileToString( 'c:\winnt\setuplog.txt' ) Echo( fileString )
The output of the example is:
Information: Setup configured the system to place a 139 MB pagefile on drive C:. ***
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.
The numbers can be wrapped in parentheses. This is necessary to access more than 9 substitution indicators.
The format String for which a substituted version is returned.
Each arg specifies a String indicating the substitution to be made for the corresponding substitution indicator. For example, if arg1 = 'Arnold', the String 'Arnold' will replace %1 each time it is located in format.
A String identical to format, but with the substitutions made, if successful; Undefined otherwise.
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." ) )
The output of the example is:
Dinosaur Jr. has 2 children, not 2.3 children.
Returns a formatted string using the format string, formatString, and argument list, argList. This method is identical to Str.Format() except the arguments for the format string are contained in a List.
The format String for which a substituted version is returned.
A list containing the arguments for the format string.
A String identical to formatString, but with the substitutions made, if successful; Undefined otherwise.
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.
A Base64-encoded String to decode.
The decoded contents of the specified String.
Converts the initial character of a UTF-8 encoded string to its Unicode codepoint. Returns Undefined if the string is empty. On characters with codepoints between 0 and 127, this function will behave identically to the deprecated Str.Ascii() method.
String containing character to convert to a unicode codepoint. If the string contains more than one character, only the first will be used.
Unicode codepoint corresponding to the first UTF-8 character in the provided string.
Integer i = Str.FromUnicode( 'é' ) echo( i ) i = Str.FromUnicode( 'a' ) echo( i )
outputs
233 97
Breaks a String into multiple segments, each of which is no longer than the number of characters specified in maxLength.
Specifies the String on which to operate.
Specifies the maximum number of characters to include in any segment, which is one minimum. Hyphenate works heuristically, that is, it attempts to break on white space, but if that cannot be done, then it breaks just after each vowel, unless no vowels are found , in which case the segment is broken at maxLength.
A List containing String elements, each representing a segment of the input String appending a hyphen character to the end of each segment.
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
The output of the example is:
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.
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.
Specifies an optional Boolean which, if present, sets international sorting mode. If present, TRUE indicates that sorting mode should be international.
A Boolean where TRUE indicates that the sort mode is international. If newValue is specified, the function returns the previous sort setting; otherwise, it returns the current setting.
Returns TRUE if inputString contains non-ASCII UTF8 characters (i.e. those with codepoints greater than 127), else FALSE.
The string to be tested.
A Boolean where TRUE indicates that inputString contains non-english UTF8 characters, otherwise FALSE.
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.
A List containing the values to concatenate. If any element of values is not of type String, a String representation of the value is appended to the resulting String.
Specifies an optional String to be inserted between elements of the List in the return value. If not specified, the default value is the empty String ("").
A String concatenation, if successful; Undefined otherwise.
Remember that joinString is as a separator, and will not be included after the last value. Here is a short example:
String s = Str.Join( { 'a', 'b', 'c', 1, Date.Now() }, '+' ) Echo( s )
The output of the example is:
a+b+c+1+Mon Aug 24 17:04:46 1998
Escape a string for use in JavaCcript
Non-alphanumeric ASCII characters are escaped using their hex code in the format \xHH.
16-bit UTF8 characters are escaped using their codepoint value in the format \uHHHH.
32-bit UTF8 characters are encoded as surrogate pairs of codepoints \uHHHH\uHHHH.
String to escape for Javascript
Quote character to delimit the string with (' or ")
The escaped string
String s = "Bob O'Connor said ""Hello"" to" + Str.CRLF + "the world." echo( Str.JString( s ) ) echo( Str.JString( s, '"' ) ) String s2 = "This is the greek character Sigma Σ" echo( Str.JString( s2 ) )
outputs
'Bob\x20O\x27Connor\x20said\x20\x22Hello\x22\x20to\x0d\x0athe\x20world\x2e' "Bob\x20O\x27Connor\x20said\x20\x22Hello\x22\x20to\x0d\x0athe\x20world\x2e" 'This\x20is\x20the\x20greek\x20character\x20Sigma\x20\u03a3'
Performs a case-sensitive search for the first occurrence of searchForStr within searchInStr. For a case-insensitive search, see Str.LocateI().
A String to search.
A String for which to search.
An Integer specifying the position (from 1 to n) of the first character of searchForStr within searchInStr if the searchInStr contains the searchForStr; Undefined otherwise.
Performs a case-insensitive search for the first occurrence of searchForStr within searchInStr. Str.LocateI() ends in "I" due to the case-insensitivity; for a case-sensitive version, see Str.Locate().
The String to search.
The String for which to search.
An Integer specifying the position (from 1 to n) of the first character of searchForStr within searchInStr if searchInStr contains searchForStr; Undefined otherwise.
Converts all alphabetic characters in the specified String to lowercase characters. See Str.Upper(), as well as Str.Capitalize().
Warning: This function does not work with non-ASCII characters.
The String for which a lowercase version is returned.
A String identical to the specified String, with all alphabetic characters in lowercase.
Here is a short example:
String s = 'Call the FBI.' Echo( '"', s, '"->"', Str.Lower( s ), '"' )
The output of the example is:
"Call the FBI."->"call the fbi."
This function adds either single or double quotation marks to the specified String.
Specifies the String on which to operate.
A String containing the quotation marks (either single or double) to add. The default is a single quote.
A String, identical to the original String, but surrounded by quotation marks, with any matching embedded quotation marks doubled.
Here is a short example:
String stringOne = "She can't remember" Echo( stringOne ) Echo( Str.Quote( stringOne ) ) Echo( Str.Quote( stringOne, '"' ) )
The output of the example is:
She can't remember 'She can''t remember' "She can't remember"
Locates the rightmost occurrence of the first character of ch within aString. See Str.Chr() for searching from the beginning of the String.
The String to search.
Specifies a String whose first character will be located from the right of aString. This is usually a single character.
An Integer specifying the character position (from 1 to n) of the last occurrence of the first character of ch within aString, if found; Undefined otherwise.
Here is a short example:
Echo( "Str.RChr( 'abcde', 'e' ) = ", Str.RChr( "abcde", "e" ) ) Echo( "Str.RChr( 'abcde', 'f' ) = ", Str.RChr( "abcde", "f" ) )
The output of the example is:
Str.RChr( 'abcde', 'e' ) = 5 Str.RChr( 'abcde', 'f' ) = ?
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.
If find can't be found in aString, Str.Replace will return Undefined.
A String which is searched.
A String for which to search.
A String which replaces find when found in aString.
A String, identical to the specified String, but with the first instance of find replaced with replace, if found; Undefined otherwise.
Here is a short example:
String replaceString = 'A good apple is available.' Echo( replaceString ) Echo( Str.Replace( replaceString, 'a', 'b' ) )
The output of the example is:
A good apple is available. A good bpple is available.
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.
A String to search.
The String for which to search.
The String which replaces find.
A String, identical to the specified String, but with all instances of find replaced with replace if found.
Here is a short example:
String s = "Even exercising weekly is energizing." Echo( s ) Echo( Str.ReplaceAll( s, "e", "3" ) )
The output of the example is:
Even exercising weekly is energizing. Ev3n 3x3rcising w33kly is 3n3rgizing.
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. The strings this function produces have a limit of 2147483648 (231) characters.
This function is not safe for use with non-ASCII characters.
Specifies either an Integer or a String. If an Integer is specified, the resulting String is length characters long. If a String is specified, the resulting String is Length( length ) characters long. If a negative integer is provided, it is treated as though a length of 0 was passed in instead.
A String whose first character is repeated length times in the resulting String.
A String of the specified length consisting solely of the first character in value.
Here is a short example:
Echo( Str.Set( 8, "*" ), " Important Message ", Str.Set( 8, "!" ) )
The output of the example is:
******** Important Message !!!!!!!!
Converts a Shift-JIS String to JIS format. Content Server 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.
A String, identical to the specified String, but converted from Shift-JIS format to JIS format. In addition, half-width (hankaku) characters are converted to full-width (zenkaku).
Converts a Shift-JIS String to UTF-8 format. Content Server processes Japanese text as Shift-JIS internally, but UTF-8 is often a more useful format for exchanging textual data across networks and between platforms.
A string to convert.
A String, identical to the specified String, but converted from Shift-JIS format to UTF-8 format.
Determines the length of the maximum initial segment of aString that consists solely of characters that are in searchChars. See Str.CSpn().
A String in which to search.
A String containing the characters for which to search.
An Integer indicating the length of the segment of aString that contains only characters found in searchChars. Returns 0 if no searchChars characters are found.
The following table demonstrates the use and output of Str.Spn() for various Strings:
|
aString |
searchChars |
Returns |
Reason |
|
"floor" |
"fo" |
1 |
"f" is in "fo", but "l" is not |
|
"bookcase" |
"bo" |
3 |
"b" and "o" are in "bo", but "k" is not |
|
"apricot" |
"j" |
0 |
"j" is not in "apricot". |
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.
A value of any type to be converted to a SQL friendly string.
A String representation of the specified value intended for inclusion in a SQL statement.
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, in 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
The output of the example is:
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}}".
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.
A value of any type to be converted to a presentable String.
If FALSE (default), a display-friendly version of value will be returned, otherwise the result is equivalent to that returned by Str.ValueToString().
A String representation of the specified value.
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
The output of the example is:
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".
Converts a String to an Integer. See Str.StringToReal() to convert a String containing a numerical value into a Real.
Specifies a String representation of an Integer. It can only contain a leading +/- sign and digits, as well as leading and/or trailing space. However any unary +/- sign should directly precede the first digit.
An Integer, if the specified String can be interpreted as an Integer; Undefined otherwise.
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
The output of the example is:
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".
Converts a String to an Long. See Str.StringToReal() to convert a String containing a numerical value into a Real.
Specifies a String representation of a Long. It can only contain a leading +/- sign and digits, as well as leading and/or trailing space. However any unary +/- sign should directly precede the first digit.
A Long, if the specified String can be interpreted as a Long; Undefined otherwise.
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.StringToLong( "', s, '" ) = "', Str.StringToLong( s ), '".' ) end
The output of the example is:
Str.StringToLong( "222.2345" ) = "?". Str.StringToLong( "333" ) = "333". Str.StringToLong( " 898" ) = "898". Str.StringToLong( "222 " ) = "222". Str.StringToLong( " -27 " ) = "-27". Str.StringToLong( " - 27" ) = "?". Str.StringToLong( " +33 " ) = "33".
Converts the specified String to a Real. See Str.StringToInteger() to convert a String containing a numerical value into an Integer.
A String representation of a Real, in basically the same format as is acceptable in the C programming language, The format is "[+-]X[.Y[e[+-]Z]]" where optional parts are bracketed, and the letters X, Y, and Z indicate any number of digits of the number, decimal, and exponent parts, respectively. It should be noted that X is optional if Y is present, and the 'e' character which prefixes the exponent part may be of any case.
The String may contain leading or trailing spaces, but no spaces within the number text block.
A Real, if the specified String can be interpreted as a real number; Undefined otherwise.
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
The output of the example is:
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".
Converts a String resulting from the Str.ValueToString() back to a value of its original type. Strings for aString other than those created with Str.ValueToString() can yield unpredictable results.
A String value returned by Str.ValueToString().
A value of the appropriate type as converted from aString.
Removes all occurrences of the specified characters from a String.
The String for which a stripped version is returned.
The characters to strip from aString. If stripChars contains multiple characters, all of these characters are removed from aString, regardless of their order.
A String, identical to aString, but with all occurrences of the characters in stripChars removed.
Here is a short example:
String s = "No! I'm without space or punctuation." Echo( s ) Echo( Str.Strip( s, "! .'" ) )
The output of the example is:
No! I'm without space or punctuation. NoImwithoutspaceorpunctuation
This function replaces tokens in aString with values from substitutions.
The string for which a substituted version will be returned. Tokens must be in the following format:
"%tokenName%"
Specifies a List, Record, or RecArray containing the values to substitute for each token. If substitutions is a List, each element must be a List in the following format:
{ tokenName, value }
If substitutions is a Record, the function substitutes the value in the field whose field name corresponds to the token name for each token.
If substitutions is a RecArray, the function substitutes the value in the field of the first Record whose field name corresponds to the token name for each token. Token comparison is not case-sensitive. Note that the substituted items must be Strings, or the substitution will resolve to an error String ("!KOSValue error string!").
A String copy of the original, but with substitutions made.
Str.Format() is easier to use for performing simple String substitution. Str.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 ), '".' )
The output of the example is:
Str.Substitute( "The items are %1%, %two%, and %THREE%" ) = "The items are cats, cows, and Tue Aug 25 21:24:37 1998".
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.
A String containing the tab character.
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.
A String to be encoded.
The encoded version of the specified String. Note that the result will be approximately 33% longer than the original String.
Converts a Unicode codepoint to a string containing the corresponding character. On codepoints between 0 and 127, this function will behave identically to the deprecated Str.Ascii() method.
Unicode codepoint
String containing character corresponding to provided Unicode codepoint.
String s = Str.ToUnicode( 233 ) echo( s ) s = Str.ToUnicode( 97 ) echo( s )
outputs
é a
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.
The String for which a trimmed version is returned.
A String, identical to the specified String, but with all leading and trailing white space removed.
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 ), '".' )
The output of the example is:
Str.Trim( " This is a sentence. " ) = "This is a sentence.".
Converts all alphabetic characters in the specified String to uppercase. See Str.Lower(), as well as Str.Capitalize()
Warning: This function does not work with non-ASCII characters.
The String for which an uppercase version is returned.
A String, identical to the specified String, but with all alphabetic characters converted to uppercase characters.
Here is a short example:
String s = 'Call the FBI.' Echo( '"', s, '"->"', Str.Upper( s ), '"' )
The output of the example is:
"Call the FBI."->"CALL THE FBI."
Converts a UTF-8 string to a String of characters. This is only valid for UTF-8 characters that can fit into a single byte (i.e. with a codepoint value less than 256).
A string to convert.
A String, identical to the specified String, but converted from UTF-8 format to ASCII format, where each character input becomes a byte of output.
Converts a UTF-8 string to a String of Shift-JIS characters.
A string to convert.
A String, identical to the specified String, but converted from UTF-8 format to Shift-JIS format.
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().
Specifies a value of any type to be converted to a String. The result from passing values of data types other than Error, Integer, Date, Boolean, Real, String, List, Assoc, or RecArray can be unpredictable.
A String representation of the specified value.
Note that Str.ValueToString() differs from Str.String() in that it textually serializes values, while Str.String() converts values to a user-presentable format. The output of Str.ValueToString() can be stored in a file, or sent across a socket, and be reconstituted at a different time or location.
| Copyright © 2023 OpenText Corporation. All rights reserved. |