String CR

 String CRLF

 Error E_Truncation

 String LF

 Integer OldEncoding

 String TAB

 Dynamic Ascii(
            Dynamic value )

Converts an ASCII value to a String, or converts a String to an ASCII value.

Parameters:

value

-

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.

Returns:

If an Integer from 0 to 255 is specified, a String consisting of a single character is returned. If an Integer outside this range is specified, Undefined is returned on UNIX platforms. If a String is specified, an Integer corresponding to the ASCII value of the first character in the String is returned.
Note: in double-byte localizations of Livelink, this function can be used with double-byte characters. If an Integer value between 255 and 65535 is specified, a double-byte character is returned. If the first character of a String parameter is a double-byte character, the Integer that is returned will represent both bytes of the character.

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.

Parameters:

aString

-

A String whose length in bytes is returned.

Returns:

An Integer specifying number of bytes used to represent aString in computer memory.

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 output of the example is:

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().

Parameters:

aString	-	A String to search.
searchChars	-	A String containing the characters for which to search.

Returns:

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

 

 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.

Parameters:

aString	-	The String for which a C-String is returned.
quoteChar	-	The quote character to escape; either a single (') or double (") quote. Double quote (") is the default.

Returns:

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"'

 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().

Parameters:

aString

-

The String for which a capitalized version is returned.

Returns:

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

 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.

Parameters:

values	-	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.
appendString	-	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 ("").

Returns:

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+

 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.

Parameters:

aString	-	Specifies a String in which to search.
ch	-	Specifies a String whose first character is to be located.

Returns:

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 = ?

 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().

Parameters:

string1	-	The first String to compare.
string2	-	The second String to compare.
chars	-	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.

Returns:

Result	Reason
<0	string1 is less than string2.
0	string1 is identical to string2.
>0	string1 is greater than string2.

 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().

Parameters:

string1	-	The first String to compare.
string2	-	the second String to compare.

Returns:

Result	Reason
<0	string1 is less than string2.
0	string1 is identical to string2.
>0	string1 is greater than string2.

 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.

Parameters:

string1	-	The first String to compare.
string2	-	The second String to compare.
chars	-	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.

Returns:

Result	Reason
<0	string1 is less than string2.
0	string1 is identical to string2.
>0	string1 is greater than string2.

 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().

Parameters:

string1	-	The first String to compare.
string2	-	The second String to compare.

Returns:

Result	Reason
<0	string1 is less than string2.
0	string1 is identical to string2.
>0	string1 is greater than string2.

 String Collapse(
             String aString )

Removes all spaces and tabs from a String.

Parameters:

aString

-

The String for which a spaceless and tabless version is returned.

Returns:

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?

 String Compress(
             String aString )

Converts all sequences of one or more spaces or horizontal tabs to a single space character.

Parameters:

aString

-

The String for which a compressed version is returned.

Returns:

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

 String Decode(
            String aString,
           [Integer keyToEncode],
           [Integer version] )

Converts a String encoded by Str.Encode() back to ASCII text.

Parameters:

aString	-	An encoded String returned by the Str.Encode function.
keyToEncode	-	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.
version	-	Specifies an optional version of the internal encoding algorithm used. Currently, Str.OldEncoding is the only meaningful value for this parameter.

Returns:

The String originally passed to the Str.Encode function.

 String EOL()

Deprecated.

Returns a line feed character.

Use System.EOL().

Returns:

A String containing the line feed character.

 

 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.

Parameters:

aString	-	A String for which delimited elements are returned.
delimiter	-	A String whose first character delimits the elements of aString.

Returns:

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'}

 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.

Parameters:

aString	-	The String for which an encoded version is returned.
keyToEncode	-	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.
version	-	An optional version of the internal encoding algorithm used. Currently, Str.OldEncoding is the only meaningful value for this parameter.

Returns:

An encoded version of the input String.

 

 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.

Parameters:

filename

-

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.

Returns:

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

***

 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.

Parameters:

format	-	The format String for which a substituted version is returned.
arg<1>	-	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.
arg<2>	-
arg<n>	-

Returns:

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.

 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.

Parameters:

aString

-

A Base64-encoded String to decode.

Returns:

The decoded contents of the specified String.

 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.

Parameters:

aString	-	Specifies the String on which to operate.
maxLength	-	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.

Returns:

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.

 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.

Parameters:

newValue

-

Specifies an optional Boolean which, if present, sets international sorting mode. If present, TRUE indicates that sorting mode should be international.

Returns:

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.

 

 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.

Parameters:

values	-	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.
joinString	-	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 ("").

Returns:

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

 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().

Parameters:

searchInStr	-	A String to search.
searchForStr	-	A String for which to search.

Returns:

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.

 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().

Parameters:

searchInStr	-	The String to search.
searchForStr	-	The String for which to search.

Returns:

An Integer specifying the position (from 1 to n) of the first character of searchForStr within searchInStr if searchInStr contains searchForStr; Undefined otherwise.

 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.

Parameters:

aString

-

The String for which a lowercase version is returned.

Returns:

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

 String Quote(
           String aString,
          [String quote] )

This function adds either single or double quotation marks to the specified String.

Parameters:

aString	-	Specifies the String on which to operate.
quote	-	a String containing the quotation marks (either single or double) to add. The default is a single quote.

Returns:

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"

 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.

Parameters:

aString	-	The String to search.
ch	-	Specifies a String whose first character will be located from the right of aString. This is usually a single character.

Returns:

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' ) = ?

 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.

Parameters:

aString	-	A String which is searched.
find	-	A String for which to search.
replace	-	A String which replaces find when found in aString.

Returns:

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.

 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.

Parameters:

aString	-	A String to search.
find	-	The String for which to search.
replace	-	The String which replaces find.

Returns:

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.

 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.

Parameters:

length	-	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.
value	-	A String whose first character is repeated length times in the resulting String.

Returns:

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 !!!!!!!!

 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.

Parameters:

aString

-

A string to convert.

Returns:

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

 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().

Parameters:

aString	-	A String in which to search.
searchChars	-	A String containing the characters for which to search.

Returns:

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

 

 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.

Parameters:

value

-

A value of any type to be converted to a SQL friendly string.

Returns:

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, 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}}".

 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.

Parameters:

value	-	A value of any type to be converted to a presentable String.
displayString	-	If FALSE (default), a display-friendly version of value will be returned, otherwise the result is equivalent to that returned by Str.ValueToString().

Returns:

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

 Integer StringToInteger(
                 String aString )

Converts a String to an Integer. See Str.StringToReal() to convert a String containing a numerical value into a Real.

Parameters:

aString

-

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.

Returns:

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

 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.

Parameters:

aString

-

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.

Returns:

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

 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.

Parameters:

aString

-

A String value returned by Str.ValueToString().

Returns:

A value of the appropriate type as converted from aString.

 

 String Strip(
           String aString,
           String stripChars )

Removes all occurrences of the specified characters from a String.

Parameters:

aString	-	The String for which a stripped version is returned.
stripChars	-	The characters to strip from aString. If stripChars contains multiple characters, all of these characters are removed from aString, regardless of their order.

Returns:

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

 String Substitute(
              String aString,
              Dynamic substitutions )

This function replaces tokens in aString with values from substitutions.

Parameters:

aString	-	The string for which a substituted version will be returned. Tokens must be in the following format: "%tokenName%".
substitutions	-	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!").

Returns:

A String copy of the original, but with substitutions made.

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 ), '".' )

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

 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.

Returns:

A String containing the tab character.

 

 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.

Parameters:

aString

-

A String to be encoded.

Returns:

The encoded version of the specified String. Note that the result will be approximately 33% longer than the original String.

 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.

Parameters:

aString

-

The String for which a trimmed version is returned.

Returns:

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

 String Upper(
           String aString )

Converts all alphabetic characters in the specified String to uppercase. See Str.Lower(), as well as Str.Capitalize()

Note that this function does not work with non-ASCII characters.

Parameters:

aString

-

The String for which an uppercase version is returned.

Returns:

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

 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().

Parameters:

value

-

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.

Returns:

A String representation of the specified value.

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.