Murl Engine Lua Addon API  Version 1.0 beta
Murl.String

A string class.

The string class contains an array of byte characters which can store an 8 bit encoded string or an UTF-8 encoded string. The array of characters is zero terminated.
A C string is a pointer to an array of byte characters which is zero-terminated.
This class is based on the NTL String container, see http://www.ultimatepp.org


Table members

Functions


Murl.String.new()

Construct an empty string.

Murl.String new()

Returns
Murl.String

Murl.String.new(charCode, length)

Construct and fill a string with a given character and length.

Murl.String new(Char charCode, Integer length)

Parameters
charCodeThe character code to fill.
lengthThe number of bytes to fill.
Returns
Murl.String

Murl.String.new(str)

Construct using a given string.

Murl.String new(String str)

Parameters
strThe original string.
Returns
Murl.String

Murl.String.new(str, length)

Construct a copy of a given string and length. Verify (assert in debug build) 'length' against the length of 'str'. Any trailing zero bytes from str[length-1] downwards will be trimmed, and length will be decreased accordingly. This is equivalent to using the constructor form String(str, length, true)

Murl.String new(String str, Integer length)

Parameters
strThe string to copy.
lengthThe number of bytes to copy.
Returns
Murl.String

Murl.String.new(str, length, trimTrailingDelimiters)

Construct a copy of a given string and length. If trimTrailingDelimiters is true, any trailing zero bytes from str[length-1] downwards will be trimmed, and length will be decreased accordingly. Otherwise, the given string is copied 'as-is', and any trailing zero bytes will be included in the number returned by GetLength().

Murl.String new(String str, Integer length, Boolean trimTrailingDelimiters)

Parameters
strThe string to copy.
lengthThe number of bytes to copy.
trimTrailingDelimitersIf true, trailing zero bytes are trimmed.
Returns
Murl.String


Methods


Clear()

Clear the string and remove the underlying storage.

Clear()


Shrink()

Shrink the string so that the underlying storage is only as large as necessary.

Shrink()


Reserve(count)

Reserve additional storage space.

Boolean Reserve(Integer count)

Parameters
countThe number of additional bytes to reserve.
Returns
Boolean true if successful.

CutAt(pos)

Cut the string on a given position. Verify (assert in debug build) 'pos' against the string length.

Boolean CutAt(Integer pos)

Parameters
posThe position to cut the string.
Returns
Boolean true if successful.

Trim()

Trim white spaces from left and right.

String Trim()

Returns
String The trimmed string.

TrimLeft()

Trim white spaces from left.

String TrimLeft()

Returns
String The trimmed string.

TrimRight()

Trim white spaces from right.

String TrimRight()

Returns
String The trimmed string.

ToLowerUTF8()

Get the lower case string including UTF-8 characters.

String ToLowerUTF8()

Returns
String The lower case UTF-8 string.

ToUpperUTF8()

Get the upper case string including UTF-8 characters.

String ToUpperUTF8()

Returns
String The upper case UTF-8 string.

GetLengthUTF8()

Count the number of UTF-8 characters.

Integer GetLengthUTF8()

Returns
Integer The number of UTF-8 characters.

GetUTF8Char(pos)

Get a UTF-8 character at a specified position. Verify (assert in debug build) 'pos' against the string length.

String GetUTF8Char(Integer pos)

Parameters
posThe byte position to get the character from.
Returns
String The UTF-8 character at the specified position, or an empty string if the position is out of range.

GetUTF8Chars()

Get the UTF-8 characters.

Murl.Array.String GetUTF8Chars()

Returns
Murl.Array.String The UTF-8 characters string array.

GetWChars()

Get the wide-characters.

Murl.Array.WChar GetWChars()

Returns
Murl.Array.WChar The wide-characters array, if the conversion fails the characters array is empty.

GetWChars(wcharArray)

Get the wide-characters and success status.

Boolean, Murl.Array.WChar GetWChars(Murl.Array.WChar wcharArray)

Parameters
wcharArrayThe wide-characters array return value.
Returns
Boolean true if successful, if conversion fails the wcharArray contains the already converted characters and false is returned.
Murl.Array.WChar wcharArray The wide-characters array return value.

GetUTF16Chars()

Get the UTF-16 characters.

Murl.Array.UInt16 GetUTF16Chars()

Returns
Murl.Array.UInt16 The UTF-16 characters array, if the conversion fails the characters array is empty.

GetUTF16Chars(utf16Array)

Get the UTF-16 characters and success status.

Boolean, Murl.Array.UInt16 GetUTF16Chars(Murl.Array.UInt16 utf16Array)

Parameters
utf16ArrayThe UTF-16 characters array return value.
Returns
Boolean true if successful, if conversion fails the utf16Array contains the already converted characters and false is returned.
Murl.Array.UInt16 utf16Array The UTF-16 characters array return value.

GetUTF32Chars()

Get the UTF-32 characters.

Murl.Array.UInt32 GetUTF32Chars()

Returns
Murl.Array.UInt32 The UTF-32 characters array, if the conversion fails the characters array is empty.

GetUTF32Chars(utf32Array)

Get the UTF-32 characters and success status.

Boolean, Murl.Array.UInt32 GetUTF32Chars(Murl.Array.UInt32 utf32Array)

Parameters
utf32ArrayThe UTF-32 characters array return value.
Returns
Boolean true if successful, if conversion fails the utf32Array contains the already converted characters and false is returned.
Murl.Array.UInt32 utf32Array The UTF-32 characters array return value.

SetWChars(wcharArray)

Set UTF-8 characters from a wide-character string.

Boolean SetWChars(Murl.Array.WChar wcharArray)

Parameters
wcharArrayThe wide-characters array.
Returns
Boolean true if successful, if conversion fails this String contains the already converted characters and false is returned.

SetUTF16Chars(utf16Array)

Set UTF-8 characters from an UTF16 string.

Boolean SetUTF16Chars(Murl.Array.UInt16 utf16Array)

Parameters
utf16ArrayThe UTF-16 characters array.
Returns
Boolean true if successful, if conversion fails this String contains the already converted characters and false is returned.

SetUTF32Chars(utf32Array)

Set UTF-8 characters from an UTF32 string.

Boolean SetUTF32Chars(Murl.Array.UInt32 utf32Array)

Parameters
utf32ArrayThe UTF-32 characters array.
Returns
Boolean true if successful, if conversion fails this String contains the already converted characters and false is returned.

Cat()

Get a reference of the string.

String Cat()

Returns
String The string reference.

Cat(charCode)

Append a character.

String Cat(Char charCode)

Parameters
charCodeThe character code to append.
Returns
String The string itself.

Cat(charCode, count)

Append characters.

String Cat(Char charCode, Integer count)

Parameters
charCodeThe character code to append.
countThe number of characters to append.
Returns
String The string itself.

Cat(str)

Append a string.

String Cat(String str)

Parameters
strThe string to append.
Returns
String The string itself.

Cat(str, length)

Append from a given string and length.

String Cat(String str, Integer length)

Parameters
strThe string to append.
lengthThe number of bytes to copy.
Returns
String The string itself.

Cat(stringArray)

Append all strings from an string array.

String Cat(Murl.Array.String stringArray)

Parameters
stringArrayThe string array to append.
Returns
String The string itself.

RemoveLastUTF8()

Remove the last character from the string including UTF-8.

Boolean RemoveLastUTF8()

Returns
Boolean true if successful, false is string is empty.

GetChar(pos)

Get a character at a specified position. Verify (assert in debug build) 'pos' against the string length.

Char GetChar(Integer pos)

Parameters
posThe byte position to get the character from.
Returns
Char The character at the specified position, or 0 if the position is out of range.

Set(pos, charCode)

Set a character. Verify (assert in debug build) 'pos' against the string length.

Boolean Set(Integer pos, Char charCode)

Parameters
posThe byte position.
charCodeThe character code to set.
Returns
Boolean true if successful.

Set(str)

Set to a given string.

Set(String str)

Parameters
strThe string to set.

Set(str, length)

Set to a given C string and length. Any trailing zero bytes from str[length-1] downwards will be trimmed, and length will be decreased accordingly. This is equivalent to calling Set(str, length, true).

Set(String str, Integer length)

Parameters
strThe string to copy.
lengthThe number of bytes to copy.

Set(str, length, trimTrailingDelimiters)

Set to a given C string and length. If trimTrailingDelimiters is true, any trailing zero bytes from str[length-1] downwards will be trimmed, and length will be decreased accordingly. Otherwise, the given C string is copied 'as-is', and any trailing zero bytes will be included in the number returned by GetLength().

Set(String str, Integer length, Boolean trimTrailingDelimiters)

Parameters
strThe string to copy.
trimTrailingDelimitersIf true, trailing zero bytes are trimmed.
lengthThe number of bytes to copy.

Insert(pos, charCode)

Insert a character.

Boolean Insert(Integer pos, Char charCode)

Parameters
posThe byte position to insert.
charCodeThe character code to insert.
Returns
Boolean true if successful.

Insert(pos, str)

Insert a string.

Boolean Insert(Integer pos, String str)

Parameters
posThe byte position to insert.
strThe string to insert.
Returns
Boolean true if successful.

Insert(pos, str, count)

Insert a C string & length.

Boolean Insert(Integer pos, String str, Integer count)

Parameters
posThe byte position to insert.
strThe C string to insert.
countThe number of bytes to insert.
Returns
Boolean true if successful.

Remove(pos, count)

Remove character(s). Verify (assert in debug build) 'pos' and 'count' against the string length.

Boolean Remove(Integer pos, Integer count)

Parameters
posThe byte position to remove.
countThe number of characters to remove.
Returns
Boolean true if successful.

RemoveChar(character)

Remove all occurrences of a character.

Integer RemoveChar(Char character)

Parameters
characterThe character to remove.
Returns
Integer The number of characters removed.

AppendUtf32(utf32CharCode)

Append one UTF-32 character.

Boolean AppendUtf32(Integer utf32CharCode)

Parameters
utf32CharCodeThe UTF-32 character code to append.
Returns
Boolean true if successful.

AppendUtf32(utf32CharCode, count)

Append UTF-32 characters.

Boolean AppendUtf32(Integer utf32CharCode, Integer count)

Parameters
utf32CharCodeThe UTF-32 character code to append.
countThe number of characters to append.
Returns
Boolean true if successful.

Mid(from)

Get a substring copy.

String Mid(Integer from)

Parameters
fromThe byte position to start.
Returns
String The substring.

Mid(from, count)

Get a substring copy.

String Mid(Integer from, Integer count)

Parameters
fromThe byte position to start.
countthe number of bytes to copy.
Returns
String The substring.

Mid(startDelimiter, endDelimiter, isStartOptional, isEndOptional)

Get a substring copy using delimiters.

String Mid(String startDelimiter, String endDelimiter, Boolean isStartOptional, Boolean isEndOptional)

Parameters
startDelimiterThe start delimiter string.
endDelimiterThe end delimiter string.
isStartOptionalfalse if start delimiter is required to be found.
isEndOptionalfalse if end delimiter is required to be found.
Returns
String The substring, or an empty string is a required limiter is not found.

Right(count)

Get a substring from the right.

String Right(Integer count)

Parameters
countNumber of bytes to copy.
Returns
String The substring.

Left(count)

Get a substring from the left.

String Left(Integer count)

Parameters
countNumber of bytes to copy.
Returns
String The substring.

Replace(find, findLen, replace, replaceLen)

Find any occurrence of a C string & length and replace each occurrence by a C string & length.

Integer Replace(String find, Integer findLen, String replace, Integer replaceLen)

Parameters
findThe C string to find.
findLenThe number of bytes to find.
replaceThe C string to replace.
replaceLenThe number of bytes to replace.
Returns
Integer The number of replaced occurrences.

Replace(find, replace)

Find any occurrence of a string and replace each occurrence by a string.

Integer Replace(String find, String replace)

Parameters
findThe string to find.
replaceThe string to replace.
Returns
Integer The number of replaced occurrences.

Find(length, str, from)

Find a C string & length. Verify (assert in debug build) 'from' against the string length.

Integer Find(Integer length, String str, Integer from)

Parameters
lengthThe number of bytes to find.
strThe C string to find.
fromThe byte position to start.
Returns
Integer The byte position of the string or -1 if not found.

Find(charCode, from)

Find a character. Verify (assert in debug build) 'from' against the string length.

Integer Find(Char charCode, Integer from)

Parameters
charCodeThe character to find.
fromThe byte position to start.
Returns
Integer The byte position of the character or -1 if not found.

Find(str, from)

Find a C string.

Integer Find(String str, Integer from)

Parameters
strThe C string to find.
fromThe byte position to start.
Returns
Integer The byte position of the string or -1 if not found.

ReverseFind(length, str, from)

Find a C string & length from right to left at position. Verify (assert in debug build) 'from' against the string length.

Integer ReverseFind(Integer length, String str, Integer from)

Parameters
lengthThe number of bytes to find.
strThe C string to find.
fromThe byte position to start.
Returns
Integer The byte position of the character or -1 if not found.

ReverseFind(charCode)

Find a character from right to left.

Integer ReverseFind(Char charCode)

Parameters
charCodeThe character to find.
Returns
Integer The byte position of the character or -1 if not found.

ReverseFind(charCode, from)

Find a character from right to left. Verify (assert in debug build) 'from' against the string length.

Integer ReverseFind(Char charCode, Integer from)

Parameters
charCodeThe character to find.
fromThe byte position to start.
Returns
Integer The byte position of the character or -1 if not found.

ReverseFind(str)

Find a C string from right to left.

Integer ReverseFind(String str)

Parameters
strThe C string to find.
Returns
Integer The byte position of the string or -1 if not found.

ReverseFind(str, from)

Find a C string from right to left at position.

Integer ReverseFind(String str, Integer from)

Parameters
strThe C string to find.
fromThe byte position to start.
Returns
Integer The byte position of the string or -1 if not found.

FindFirstOf(length, str, from)

Find first character from a character set C string & length. Verify (assert in debug build) 'from' against the string length.

Integer FindFirstOf(Integer length, String str, Integer from)

Parameters
lengthThe number of bytes in the C string.
strThe character set C string.
fromThe byte position to start.
Returns
Integer The byte position of a matching character or -1 if not found.

FindFirstOf(str, from)

Find first character from a character set C string.

Integer FindFirstOf(String str, Integer from)

Parameters
strThe character set C string.
fromThe byte position to start.
Returns
Integer The byte position of a matching character or -1 if not found.

FindFirstNotOf(length, str, from)

Find the first character not matching any of the characters in a given set. Verify (assert in debug build) 'from' against the string length.

Integer FindFirstNotOf(Integer length, String str, Integer from)

Parameters
lengthThe number of bytes in the given C string character set.
strThe character set C string.
fromThe byte position to start.
Returns
Integer The byte position of the first non-matching character or -1 if not found.

FindFirstNotOf(str, from)

Find the first character not matching any of the characters in a given set.

Integer FindFirstNotOf(String str, Integer from)

Parameters
strThe character set C string.
fromThe byte position to start.
Returns
Integer The byte position of a matching character or -1 if not found.

StartsWith(str)

Check if the start matches a string.

Boolean StartsWith(String str)

Parameters
strThe string to match.
Returns
Boolean true if the start matches the string.

StartsWith(str, length)

Check if the start matches a C string & length.

Boolean StartsWith(String str, Integer length)

Parameters
strThe C string to match.
lengthThe number of bytes to match.
Returns
Boolean true if the start matches the string.

EndsWith(str)

Check if the end matches a string.

Boolean EndsWith(String str)

Parameters
strThe string to match.
Returns
Boolean true if the end matches the string.

EndsWith(str, length)

Check if the end matches a C string & length.

Boolean EndsWith(String str, Integer length)

Parameters
strThe C string to match.
lengthThe number of bytes to match.
Returns
Boolean true if the end matches the string.

Compare(str)

Compare a string.

Integer Compare(String str)

Parameters
strThe string to compare.
Returns
Integer return -1 if lower, 0 if equal, 1 if greater.

IsEqual(str)

Check if a string is equal.

Boolean IsEqual(String str)

Parameters
strThe string to compare.
Returns
Boolean return true if equal.

GetHashValue()

Calculate the string hash value.

Integer GetHashValue()

Returns
Integer The hash value.

GetAlloc()

Get the number of allocated bytes for characters, excluding the zero terminator.

Integer GetAlloc()

Returns
Integer The number of allocated bytes for characters.

GetLength()

Get number of byte characters.

Integer GetLength()

Returns
Integer The number of byte characters.

IsEmpty()

Check if the string is empty.

Boolean IsEmpty()

Returns
Boolean true if the string is empty.

ToString()

Get a const reference of the string. Convenience method for Lua scripting support.

String ToString()

Returns
String The string reference.

Begin()

Get the pointer to the first character.

String Begin()

Returns
String The read-only pointer to the first character.

End()

Get the pointer to the end of the string.

String End()

Returns
String The read-only pointer to end of the string.

Last()

Get the pointer to the last character.

String Last()

Returns
String The read-only pointer to the last character.

Swap(other)

Exchange the content of the string with a given second one.

String Swap(String other)

Parameters
otherThe second string.
Returns
String other The second string.


Metamethods


The length operator

The length operator is denoted by the unary prefix operator #.

Returns
GetLength()

The tostring operator

Converts the object content to a string in a reasonable format.

Returns
ToString()

The array subscript operator.

The array operator. Verify (assert in debug build) 'pos' against the string length.

Parameters
posThe character byte position.
Returns
Char = Murl.String [Integer pos]

The addition operator.

Addition operator for character and string.

Returns
String = Char + String

The addition operator.

Addition operator for Double and string.

Returns
String = String + Number

The addition operator.

Addition operator for string and character.

Returns
String = String + Char

The addition operator.

Addition operator for string and string.

Returns
String = String + String

The addition operator.

Addition operator for Bool and string.

Returns
String = String + Boolean

The addition operator.

Addition operator for Color and string.

Returns
String = String + Murl.Color

The addition operator.

Addition operator for Time and string.

Returns
String = String + Murl.System.Time

The less than operator.

Less than operator for string and string.

Returns
Boolean = String < String

The less than or equal operator.

Less than or equal to operator for string and string.

Returns
Boolean = String <= String

The equal to operator.

Equal to comparison operator for string and string.

Returns
Boolean = String == String