ifStringOps

Implemented by

Supported methods

ifStringOps provides various methods for manipulating string objects. Some of these duplicate functionality also available in the global string functions.

Note that the ifStringOps string indices start at 0; they do not start at 1 like global string functions.

SetString(s as String, len as Integer) as Void

Description

Sets the roString object to the specified first set of characters of the provided string.

The ifString interface includes a similar function, ifString.SetString(), which does not take a length parameter.

Parameters

AppendString(s as String, len as Integer) as Void

Description

Appends the specified first set of characters of the provided string to the end of the roString object.

The AppendString() function modifies the object on which it is called, which can result in unexpected results if called on a literal string constant rather than a string object. Consider the following example:

x = "one"
print type(x) ' prints "String"
x.AppendString("two", 3)
print x ' will print "one" not "onetwo"

y = box("one")
print type(y) ' prints "roString"
y.AppendString("two", 3)
print y ' will print "onetwo"

The third line does not appear to do an append, but it is working as designed since the append happens to the temporary boxed object. x="string" sets x to the intrinsic type, vs. y=box("string"), which works as expected.

Parameters

Len() as Integer

Description

Returns the number of characters in the string.

Return Value

Number of characters.

Left(len as Integer) as String

Description

Returns a string consisting of the first len characters of the string.

Parameters

Return Value

The string generated by the method.

Right(len as Integer) as String

Description

Returns a string consisting of the last len characters of the string.

Parameters

Return Value

The string generated by the method.

Mid(start_index as Integer) as String

Description

Returns a string consisting of the last characters of the string, starting at the zero-based start_index.

Parameters

Return Value

The string generated by the method.

Mid(start_index as Integer, num_chars as Integer) as String

Description

Returns a string consisting of num_chars characters of the string, starting at the zero-based start_index. If there are fewer than num_chars in the string after start_index, returns the remaining characters in the string.

s.Left(len) is equivalent to s.Mid(0, len)<br />s.Right(len) is equivalent to s.Mid(s.Len() - len.

Parameters

Instr(substring as String) as Integer

Description

Returns the zero-based index of the first occurrence of substring in the string. If the substring does not occur in the string, this method returns -1

Parameters

Return Value

The index of the first instance of the substring within the string.

Replace(fromStr As String, toStr As String) As String

Description

Returns a copy of the string with all instances of fromStr replaced with toStr. If fromStr is empty the return value is the same as the source string.

Parameters

Return Value

A copy of the string with all the instances

Example

print "a-b-c".Replace("-", "/")

' result is "a/b/c"

Instr(start_index as Integer, substring as String) as Integer

Description

Returns the zero-based index of the first occurrence of substring in the string, starting at the specified zero-based start_index. If the substring does not occur in the string after start_index, returns -1

Parameters

Return Value

The index of the first instance of the substring within the string, based on the specified starting position.

Trim() as String

Description

Returns the string with any leading and trailing whitespace characters (space, TAB, LF, CR, VT, FF, NO-BREAK SPACE, et al) removed.

Return Value

The trimmed string.

ToInt() as Integer

Description

Returns the value of the string interpreted as a decimal number.

Return Value

The decimal number representation of the string.

ToFloat() as Float

Description

Returns the value of the string interpreted as a floating point number.

Return Value

The floating point number representation of the string.

Tokenize(delim as String) as Object

Description

Splits the string into separate substrings separated by a single delimiter character.

Parameters

Return Value

An roList containing the each of the substrings. The delimiters are not returned.

Split(separator as String) as Object

Description

Splits the input string using the separator string as a delimiter. An empty separator string indicates to split the string by character.

Parameters

Return Value

An array of the split token strings (not including the delimiter).

Examples

a = "".Split("")

'creates the array equivalent to
a = []

a = "123".Split("")

'creates the array equivalent to
a = ["1", "2", "3"]

a = "123".Split("/")

'creates the array equivalent to
a = ["123"]

a = "/123/".Split("/")

'creates the array equivalent to
a = ["", "123", ""]

a = "one, two, three".Split(", ")

'creates the array equivalent to
a = ["one", "two", "three"]

GetEntityEncode() as String

Description

Returns the string with the following characters replaced with their corresponding HTML entity encoding sequences below:

Character	Replaced with
" (double quote)	"
' (single quote)	'
<	&lt;
>	&gt;
&	&amp;

=======

Return Value

The encoded string.

Escape() as String

Description

URL encodes the specified string per RFC 3986 and returns the encoded string. Non-ASCII characters are encoded as UTF-8 escape sequences. This functionality is essentially the same as roUrlTransfer.Escape, but without the overhead of creating a roUrlTransfer object.

Use the EncodeUri or EncodeUriComponent methods instead.

Return Value

The URL-encoded version of the specified string.

Example

s = "@&=+/#!*"
t = s.Escape()
print """" + t + """"
REM "%40%26%3D%2B%2F%23%21%2A"

' escaped characters are encoded as UTF-8 sequences
s = Chr(&h2022)
t = s.Escape()
print """" + t + """"
REM "%E2%80%A2"

Unescape() as String

Description

URL decodes the specified string per RFC 3986 and returns the decoded string.

The functionality is essentially the same as roUrlTransfer. Unescape, but without the overhead of creating a roUrlTransfer object.

If the escaped string includes invalid escape sequences, the decode will fail and an empty string will be returned.

Consider using the DecodeUri or DecodeUriComponent method instead.

Return Value

The URL-decoded string.

Example

t = "%3B%3F%3A%24%2C%28%29"
s = t.Unescape()
print """" + s + """"
REM ";?:$,()"

EncodeUri() as String

Description

Encodes the specified string with escape sequences for reserved Uniform Resource Identifier (URI) characters. Non-ASCII characters are encoded as UTF-8 escape sequences.

Return Value

The provided string encoded as a Uniform Resource Identifier (URI).

Example

s = "http://roku.com/my test.asp?first=jane&last=doe"
t = s.EncodeUri()
print """" + t + """"
REM "http://roku.com/my%20test.asp?first=jane&last=doe"

DecodeUri() as String

Description

Decodes the specified string with escape sequences for reserved Uniform Resource Identifier (URI) characters. If the escaped string includes invalid escape sequences, the decode will fail and an empty string will be returned.

Return Value

An unencoded version of the provided encoded Uniform Resource Identifier (URI).

Example

t = "http://roku.com/my%20test.asp?first=jane&last=doe"
s = t.DecodeUri()
print """" + s + """"
REM "http://roku.com/my test.asp?first=jane&last=doe"

EncodeUriComponent() as String

Description

Encodes the specified string with escape sequences for reserved Uniform Resource Identifier (URI) component characters.

Return Value

The provided string encoded as a Uniform Resource Identifier (URI).

Example

s = "http://roku.com/my test.asp?first=jane&last=doe"
t = s.EncodeUriComponent()
print """" + t + """"
REM "http%3A%2F%2Froku.com%2Fmy%20test.asp%3Ffirst%3Djane%26last%3Ddoe"

DecodeUriComponent() as String

Description

Decodes the specified string with escape sequences for reserved Uniform Resource Identifier (URI) component characters. If the escaped string includes invalid escape sequences, the decode will fail and an empty string will be returned.

Return Value

An unencoded version of the provided encoded Uniform Resource Identifier (URI).

Example

t = "http%3A%2F%2Froku.com%2Fmy%20test.asp%3Ffirst%3Djane%26last%3Ddoe"
s = t.DecodeUriComponent()
print """" + s + """"
REM "http://roku.com/my test.asp?first=jane&last=doe"

StartsWith(matchString as String) As Boolean

Checks whether the string starts with the substring specified in matchString, starting at the beginning of the string (position 0).

Return Value

A flag indicating whether a matching substring was found.

Example

s = "Roku Rocks"
? s.StartsWith("Roku") ' => true
? s.StartsWith("roku") ' => false

StartsWith(matchString as String, matchPos as Integer) As Boolean

Checks whether the string starts with the substring specified in matchString, starting at the matchPos parameter (0-based character offset).

Return Value

A flag indicating whether a matching substring was found.

Example

s = "Roku Rocks"
? s.StartsWith("Rocks", 5) ' => true
? s.StartsWith("Roku", 5)  ' => false

EndsWith(matchString as String) As Boolean

Checks whether the string ends with the substring specified in matchString, starting at the end of the string.

Return Value

A flag indicating whether a matching substring was found.

Example

s = "Roku Rocks"
? s.EndsWith("Rocks") ' => true
? s.EndsWith("roku") ' => false

EndsWith(matchString as String, length as Integer) As Boolean

Checks whether the string ends with the substring specified in matchString, starting at the position specified in the length parameter.

Return Value

A flag indicating whether a matching substring was found.

Example

s = "Roku Rocks"
? s.EndsWith("Roku", 4) ' => true

Format(...) As String

Description

Returns a format conversion using the specified printf-like format string and matching dynamic parameters.

The parameters must match the format string's placeholders in count and expected data type or an error may occur.

Return Value

The formatted string.

Support

Format support (the ifStringOps interface) is implemented by the following type:

• roString (String)

Examples

Mixed

'* example of mixed parameters
s = "Roku" + " " + "rocks!"
print "The length of '%s' is %d.".Format(s, s.Len())
'=> "The length of 'Roku rocks!' is 11."

Integer (Decimal)

'* example of decimal integers
print "%d * %d = %d".Format(-13, 21, -13 * 21)
'=> "-13 * 21 = -273"

'* example of decimal integers with left-side 0-padding
print "%04d-%02d-%02d".Format(17, 3, 99)
'=> "0017-03-99"

Integer (Hexadecimal)

'* example of hexadecimal integer with left-side 0-padding
print "%07x".Format(&hFACE1)
'=> "00face1"

'* example of using a dynamic field width parameter
'* (left-side blank padding by default)
print "%*X".Format(6, &hFACE1)
'=> " FACE1"

'* example of using a dynamic field width parameter,
'* left-aligned to put the blank padding on the right
print "%-*X".Format(6, &hFACE1)
'=> "FACE1 "

'* example of using a dynamic field width parameter,
'* with left-side 0-padding
print "%0*x".Format(8, &hFACE1)
'=> "000face1"

Floating Point

'* example of floating point formatting
pi = 3.1415 : r = 2.5
print "r=%4.2f => c=%4.2f".Format(r, 2 * pi * r)
'=> "r=2.50 => c=15.71"

String

'* example plain string formatting
print "%s, %s".Format("Fields", "Sally")
'=> "Fields, Sally"

'* example of string formatting with field widths
'* first is left-aligned / right-padded, second is left-padded by default
print "[%-3s:%3s]".Format("A", "B")
'=> "[A  :  B]"

Character

'* example of character formatting
print "(%c%c%c)".Format(&h7B, 64, &h7D)
'=> "({@})"

Arg(Strings...) As String

Description

Replaces occurrences of %N in this string (where N is "1".."9") with the corresponding argument from the parameter strings.. The arguments are not positional: the first of the string replaces the %N with the lowest N (all of them), the second of the strings the %N with the next-lowest N, and so on.

All occurrences of %N are replaced with the parameter, and the same value of %N can occur multiple times.

A maximum of 6 parameters may be specified per call.

If a parameter is specified, but no placeholders exist, a warning is output to the debug console.

If the number of placeholders is greater than the number of parameters, those placeholders are not modified.

Return Value

The resulting string after all eligible placeholder replacements have been made.

Examples

title = "Princess"
name = "Leia"
salutation = "Hello %1 %2!".Arg(title, name)
print salutation
' =>
' Hello Princess Leia!

s = "%2 and %4 (or %4 and %2)".Arg("first", "second")
print s
' =>
' first and second (or second and first)

first_name = "Jack"
last_name = "Reacher"
listing = "%2, %1".Arg(first_name, last_name)
print listing
' =>
' Reacher, Jack

text = "a=%3 b=%1 c=%2"
text = text.Arg("banana")
print text
' =>
' a=%3 b=banana c=%2

text = text.Arg("cherry")
print text
' =>
' a=%3 b=banana c=cherry

text = text.Arg("apple")
print text
' =>
' a=apple b=banana c=cherry

text = text.Arg("durian")
' => warning
' WARNING: roString.Arg: unused parameters
print text
' =>
' a=apple b=banana c=cherry