up: STRING     index Zimbu documentation

CLASS T.string @public

summary

     

The builtin type string.

The string can be any sequence of Unicode characters, including NUL. A string cannot be modified, see varString for a mutable string.

The C implementation uses UTF-8 encoded characters. Illegal byte sequences may appear but cause an exception for some operations. Locating a character by index is slow, it requires going over the string from the start, since UTF-8 is a variable width encoding. For longer strings it is faster to use indexes on the result of toArray().

The Javascript implementation uses native strings. Illegal bytes are not possible. Locating a character by index is fast.

Obtaining the length of the string is always fast, it does not need to scan the bytes for a NUL byte, like in C.

The object methods can be also used on a string literal:

 string s = "foobar".slice(3)
 # s == "bar"
Besides the methods there is the concatenation operator:
 string s = "left" .. " and " .. "right"
 # s == "left and right"

NEW(array) @file  Create a string from the characters in array.
NEW(array, start) @file  Create a string from the characters in array starting at index start.
NEW(array, start, end) @file  Create a string from the characters in array starting at index start and ending at index end (inclusive).
$Size() int @public  Return the size of the string in characters.
$ToString() string @public  Return the string itself, a no-op. Also works on a NIL.
$ToString(formatSpec) string @public  Return a formatted version of the string.
$Compare(other) int @public  Return -1 when other sorts after this string, zero when other is equal to this string, and 1 when other sorts before this string.
$Equal(other) bool @public  Return TRUE when other is equal to this string, FALSE otherwise.
$asByteString() byteString @public  Return the string as a byteString.
$toByteString() byteString @public  Return the string as a byteString.
$toVarString() varString @public  Return the string converted to a varString.
$toArray() array<nat32> @public  Return an array with the characters of the string.
$format(arguments) string @file  Replace placeholders in the string with argument values.
$toInt() int @public  Return the digits at the start of the string converted to a number.
$toInt(default) int @public  Return the digits at the start of the string converted to a number.
$quotedToInt() int @public  Return the digits at the start of the string converted to a number, ignoring quotes.
$quotedToInt(default) int @public  Return the digits at the start of the string converted to a number, ignoring quotes.
$hexToInt() int @public  Return the hex digits at the start of the string converted to a number.
$hexToInt(default) int @public  Return the hex digits at the start of the string converted to a number.
$quotedHexToInt() int @public  Return the hex digits at the start of the string converted to a number, ignoring quotes.
$quotedHexToInt(default) int @public  Return the hex digits at the start of the string converted to a number, ignoring quotes.
$binToInt() int @public  Return the binary digits at the start of the string converted to a number.
$binToInt(default) int @public  Return the binary digits at the start of the string converted to a number.
$quotedBinToInt() int @public  Return the binary digits at the start of the string converted to a number, ignoring quotes.
$quotedBinToInt(default) int @public  Return the binary digits at the start of the string converted to a number, ignoring quotes.
$toFloat() float @public  Return the number at the start of the string converted to a float.
$toFloat(length) float @public  Return the number at the start of the string converted to a float.
$contains(s) bool @public  Return TRUE if the string contains s.
$contains(re) bool @public  Return TRUE if re matches in the string.
$find(s) int @public  Return the lowest index where string s appears.
$find(re) int @public  Return the lowest index where regexp re matches.
$find(c) int @public  Return the lowest index of the character c.
$find(s, start) int @public  Return the lowest index where the string s appears at or after start.
$find(c, start) int @public  Return the lowest index of the character c at or after start.
$findLast(s) int @public  Return the highest index where string s appears.
$findLast(c) int @public  Return the highest index of the character c.
$startsWith(s) bool @public  Return TRUE when the string starts with s.
$endsWith(s) bool @public  Return TRUE when the string ends with s.
$hash() nat @public  Return a number that is a hash value of the string.
$padLeft(minSize, pad) string @public  Return the string with padding added on the left.
$padRight(minSize, pad) string @public  Return the string with padding added on the right.
$reverse() string @public  Return the string with all characters in reverse order.
$replace(from, to) string @public  Replace the first occurrence of the from character with to.
$replace(from, to) string @public  Replace the first occurrence of from with to.
$replaceAll(from, to) string @public  Replace all occurrences of the from character with to.
$replaceAll(from, to) string @public  Replace all occurrences of from with to.
$escape() string @public  Double all backslashes and put a backslash before a double quote.
$toLower() string @public  Return a copy of the string with all characters lower-cased.
$toLowerAscii() string @public  Return a copy of the string with all ASCII characters lower-cased.
$toUpper() string @public  Return a copy of the string with all characters upper-cased.
$toUpperAscii() string @public  Return a copy of the string with all ASCII characters upper-cased.
$slice(start) string @public  Return a copy of the string, starting at index start.
$slice(start, end) string @public  Return a copy of the string, starting at index start and ending at end, inclusive.
$sliceSize(start, length) string @public  Return a copy of the string, starting at index start with up to length characters.
$sliceWrap(start) string @public  Return a copy of the string, starting at index start.
$sliceWrap(start, end) string @public  Return a copy of the string, starting at index start and ending at end, inclusive.
$sliceWrapSize(start, length) string @public  Return a copy of the string, starting at index start with up to length characters
$split() list<string> @public  Return a list with the string split at white space.
$split(sep) list<string> @public  Return a list with the string split into pieces, split at sep.
$splitAnyOf(charSet) list<string> @public  Return a list with the string split at the characters in charSet.
$trim() string @public  Return the string with leading and trailing white space removed.
$trimLeading() string @public  Return the string with leading white space removed.
$trimTrailing() string @public  Return the string with trailing white space removed.
 
 

members (alphabetically)

     

PROC NEW(array<int> array) @file

     

Create a string from the characters in array.

The array item type can be any int or nat number.

PROC NEW(array<int> array, int start) @file

     

Create a string from the characters in array starting at index start.

The array item type can be any int or nat number.

PROC NEW(array<int> array, int start, int end) @file

     

Create a string from the characters in array starting at index start and ending at index end (inclusive).

The array item type can be any int or nat number.

FUNC $Compare(string other) int @public

     

Return -1 when other sorts after this string, zero when other is equal to this string, and 1 when other sorts before this string.

When using ?.Compare() on a NIL string and other is NIL it returns zero. When other is not NIL it returns -1.

FUNC $Equal(string other) bool @public

     

Return TRUE when other is equal to this string, FALSE otherwise.

When using ?.Equal() on a NIL string and other is NIL it returns TRUE. Otherwise when other is NIL returns FALSE.

FUNC $Size() int @public

     

Return the size of the string in characters.

Note that this is different from the number of bytes if there are multi-byte characters.

The method has to go over the text to count the characters, this may be slow for a very long string.

The empty string returns zero. A NIL string also returns zero, it does not throw an E.NilAccess exception.

FUNC $ToString() string @public

     

Return the string itself, a no-op. Also works on a NIL.

FUNC $ToString(string formatSpec) string @public

     

Return a formatted version of the string.

The format must end in "s". The minimum and maximum width of the result can be specified and optionally ellipses can indicate truncated text.

Use "{min}s" to specify a minimum width. {min} is the width in decimal form. When the string is longer than the minimum it is returned unchanged. When the string is shorter spaces are inserted on the left:

 "some".ToString("6s")   # "  some"
Use a minus sign to align the text on the left, added spaces are put after the text:
 "some".ToString("-6s")   # "some  "

Use ".{max}s" to specify a maximum width. {max} is the width in decimal form. When the text is longer it is truncated:

 "something".ToString(".4s")  # "some"
Use a minus sign to keep the rightmost part of the text:
 "something".ToString(".-4s")  # "hing"

The minimum and maximum can be combined as "{min}.{max}s". This only makes sense when the minimum is larger than the maximum. The text will first be truncated to the maximum size, then filled with spaces to the minimum size:

 "something".ToString("5.4s")  # " some"
 "something".ToString("-5.4s")  # "some "
 "something".ToString("-5.-4s")  # "hing "

When the string must be truncated ellipses can be added. Use two or three dots instead of one for the maximum width. These dots will be put where the string was truncated. Use a plus sign to put ellipses at the right, no sign to put ellipses in the middle, and a minus sign to put ellipses at the left. The ellipses are included in the maximum width, thus the width must be at least 3 or 4 to make sense.

 "something great".ToString("...+8s")  # "somet..."
 "something great".ToString("..10s")  # "some..reat"
 "something great".ToString("...-8s")  # "...great"

FUNC $asByteString() byteString @public

     

Return the string as a byteString.

This does not do any conversion, it only changes the type of the object. Also works on a NIL.

Example: get the number of bytes in a string:

 int byteSize = text.asByteString().Size()

FUNC $binToInt() int @public

     

Return the binary digits at the start of the string converted to a number.

For example, "010101".binToInt() returns 21.

Ignores anything after the number.

Throws an E.BadValue exception when the string does not start with a 0 or 1.

When using ?.binToInt() on a NIL string the result is zero.

FUNC $binToInt(int default) int @public

     

Return the binary digits at the start of the string converted to a number.

For example, "010101".binToInt() returns 21.

Ignores anything after the number.

Returns default when the string does not start with a 0 or 1. Also returns default when the string is NIL and ?.binToInt() was used.

FUNC $contains(string s) bool @public

     

Return TRUE if the string contains s.

When the string is NIL returns FALSE.

FUNC $contains(regex re) bool @public

     

Return TRUE if re matches in the string.

When the string is NIL returns FALSE.

FUNC $endsWith(string s) bool @public

     

Return TRUE when the string ends with s.

When using ?. and the string is NIL returns -1.

FUNC $escape() string @public

     

Double all backslashes and put a backslash before a double quote.

This turns an arbitrary string into a string that can be put in double quotes.

When no escaping is done returns the string unmodified.

When using ?.escape() on a NIL string the result is NIL.

FUNC $find(string s) int @public

     

Return the lowest index where string s appears.

When s matches at the start 0 is returned. When not found returns -1. When s is longer than this string it will not be found, thus -1 is returned.

When using ?.find() and the string is NIL returns -1.

FUNC $find(regex re) int @public

     

Return the lowest index where regexp re matches.

When re matches at the start 0 is returned. When there is no match returns -1.

When the string is NIL returns -1.

FUNC $find(int c) int @public

     

Return the lowest index of the character c.

When c is the first character 0 is returned. When not found returns -1.

When using ?. and the string is NIL returns -1.

FUNC $find(string s, int start) int @public

     

Return the lowest index where the string s appears at or after start.

When start is zero this works the same as find(s). When not found returns -1. When found returns start or more.

When using ?. and the string is NIL returns -1.

FUNC $find(int c, int start) int @public

     

Return the lowest index of the character c at or after start.

When start is zero this works the same as find(c).

When c is found returns start or more.

When c is not found returns -1.

When using ?. and the string is NIL returns -1.

FUNC $findLast(string s) int @public

     

Return the highest index where string s appears.

When s matches at the start 0 is returned.

When not found returns -1. When s is longer than this string it will not be found, thus -1 is returned.

When using ?. and the string is NIL returns -1.

FUNC $findLast(int c) int @public

     

Return the highest index of the character c.

When c is the first character 0 is returned. When not found returns -1.

When using ?. and the string is NIL returns -1.

FUNC $format(dyn arguments) string @file

     

Replace placeholders in the string with argument values.

A placeholder starts with a { and ends with a }. To get a literal { use {{. A trailing { is also passed on as-is.

Placeholders can use a number, which is the index in arguments: {0} refers to the first argument, {1} to the second, etc.

Placeholders can use a name, in which case the arguments must be passed by name: {xyz} refers to argument xyz in format(xyz = value).

Without further specification ToString() is invoked on the argment before it replaces the placeholder. Optionally a format can be specified right after the {, e.g. {04x nr} (the integer argument "nr" formatted as four hex digits). The format and the argument number/name must be separated by exactly one space.

Errors are reported in the resulting string. To throw an exception instead insert {THROW} before any placeholders.

FUNC $hash() nat @public

     

Return a number that is a hash value of the string.

Two equal strings always have the same hash value. Two different strings can result in the same hash value, but the chance of this happening is small.

The hash method is fast and has a reasonable distribution.

FUNC $hexToInt() int @public

     

Return the hex digits at the start of the string converted to a number.

For example, "a2b4".hexToInt() returns 0xa2b4.

A leading "0x" or "0X" is ignored. Ignores anything after the number.

Throws an E.BadValue exception when the string does not start with a hex digit. Also when it starts with "-".

When using ?.hexToInt() on a NIL string the result is zero.

FUNC $hexToInt(int default) int @public

     

Return the hex digits at the start of the string converted to a number.

For example, "a2b4".hexToInt() returns 0xa2b4.

A leading "0x" or "0X" is ignored. Ignores anything after the number.

Returns default when the string does not start with a hex digit. That includes "-". Also returns default when the string is NIL and ?.hexToInt() was used.

FUNC $padLeft(int minSize, int pad) string @public

     

Return the string with padding added on the left.

The resulting string is at least minSize characters long. If the current string is shorter the pad character is added as many times as needed.

Example: "foo".padLeft(5, '-') returns "--foo".

When using ?.padLeft() on a NIL string the result is NIL.

FUNC $padRight(int minSize, int pad) string @public

     

Return the string with padding added on the right.

The resulting string is at least minSize characters long. If the current string is shorter the pad character is added as many times as needed.

Example: "foo".padRight(5, '-') returns "foo--".

When using ?.padRight() on a NIL string the result is NIL.

FUNC $quotedBinToInt() int @public

     

Return the binary digits at the start of the string converted to a number, ignoring quotes.

Ignores single quotes and underscores, these can be used to make the number easier to read. For example, "1001'0101".quotedBinToInt() returns 149.

Ignores anything after the number.

Throws an E.BadValue exception when the string does not start with a 0 or 1.

When using ?.quotedBinToInt() on a NIL string the result is zero.

FUNC $quotedBinToInt(int default) int @public

     

Return the binary digits at the start of the string converted to a number, ignoring quotes.

Ignores single quotes and underscores, these can be used to make the number easier to read. For example, "1001'0101".quotedBinToInt() returns 149.

Ignores anything after the number.

Returns default when the string does not start with a 0 or 1 and when using ?.quotedBinToInt() on a NIL string.

FUNC $quotedHexToInt() int @public

     

Return the hex digits at the start of the string converted to a number, ignoring quotes.

Ignores single quotes and underscores, these can be used to make the number easier to read. For example, "ffff'ffff".quotedHexToInt() returns 16777215.

A leading "0x" or "0X" is ignored. Ignores anything after the number.

Throws an E.BadValue exception when the string does not start with a hex digit. That includes "-".

When using ?.quotedHexToInt() on a NIL string the result is zero.

FUNC $quotedHexToInt(int default) int @public

     

Return the hex digits at the start of the string converted to a number, ignoring quotes.

Ignores single quotes and underscores, these can be used to make the number easier to read. For example, "ffff'ffff".quotedHexToInt() returns 16777215.

A leading "0x" or "0X" is ignored. Ignores anything after the number.

Returns default when the string does not start with a hex digit. That includes "-". Also returns default when the string is NIL and ?.quotedHexToInt() was used.

FUNC $quotedToInt() int @public

     

Return the digits at the start of the string converted to a number, ignoring quotes.

Ignores single quotes and underscores, these can be used to make the number easier to read. For example, "100'000".quotedToInt() returns 100000.

Ignores anything after the number.

Throws an E.BadValue exception when the string does not start with a digit or a minus sign.

When using ?.quotedToInt() on a NIL string the result is zero.

FUNC $quotedToInt(int default) int @public

     

Return the digits at the start of the string converted to a number, ignoring quotes.

Ignores single quotes and underscores, these can be used to make the number easier to read. For example, "100'000".quotedToInt() returns 100000.

Ignores anything after the number.

Returns default when the string does not start with a digit or a minus sign. When using ?.quotedToInt() also when the string is NIL.

FUNC $replace(int from, int to) string @public

     

Replace the first occurrence of the from character with to.

When from is not found returns the string unmodified.

When using ?.replace() on a NIL string the result is NIL.

FUNC $replace(string from, string to) string @public

     

Replace the first occurrence of from with to.

When from is not found returns the string unmodified.

When using ?.replace() on a NIL string the result is NIL.

FUNC $replaceAll(int from, int to) string @public

     

Replace all occurrences of the from character with to.

When from is not found returns the string unmodified.

When using ?.replaceAll() on a NIL string the result is NIL.

FUNC $replaceAll(string from, string to) string @public

     

Replace all occurrences of from with to.

When from is not found returns the string unmodified.

When using ?.replaceAll() on a NIL string the result is NIL.

FUNC $reverse() string @public

     

Return the string with all characters in reverse order.

Example: "foobar".reverse() returns "raboof".

When using ?.reverse() on a NIL string the result is NIL.

FUNC $slice(int start) string @public

     

Return a copy of the string, starting at index start.

This counts characters, not bytes. To count bytes first use $asByteString().

If start is equal to or larger than the size of the string an empty string is returned. If start is zero or negative the whole string is returned.

When using slice() on a NIL string the result is NIL.

FUNC $slice(int start, int end) string @public

     

Return a copy of the string, starting at index start and ending at end, inclusive.

If start is equal to or larger than the size of the string an empty string is returned. If start is zero or negative the string starts at index zero. If the start is after end an empty string is returned.

When using slice() on a NIL string the result is NIL.

FUNC $sliceSize(int start, int length) string @public

     

Return a copy of the string, starting at index start with up to length characters.

If start is equal to or larger than the size of the string an empty string is returned. If start is zero or negative the string starts at index zero. If length is larger than the number of characters available, only the available characters are returned.

When using sliceSize() on a NIL string the result is NIL.

FUNC $sliceWrap(int start) string @public

     

Return a copy of the string, starting at index start.

A negative index is relative to the end of the string, sliceWrap(-1) returns a string with only the last character. Thus the index wraps around at the start.

This counts characters, not bytes. To count bytes first use $asByteString().

If start is equal to or larger than the size of the string an empty string is returned. If start is negative and the absolute value is larger than the string size the whole string is returned.

When using sliceWrap() on a NIL string the result is NIL.

FUNC $sliceWrap(int start, int end) string @public

     

Return a copy of the string, starting at index start and ending at end, inclusive.

A negative index is relative to the end of the string. sliceWrap(0, -1) returns the whole string. sliceWrap(-1, -1) only the last character. Thus the index wraps around at the start.

If start is equal to or larger than the size of the string an empty string is returned. If start is negative and the absolute value is larger than the returned string starts at index zero. If the start character is after the end character an empty string is returned.

When using sliceWrap() on a NIL string the result is NIL.

FUNC $sliceWrapSize(int start, int length) string @public

     

Return a copy of the string, starting at index start with up to length characters

A negative index is relative to the end of the string. sliceWrapSize(-3, 3) returns the last three characters. Thus the index wraps around at the start.

If start is equal to or larger than the size of the string an empty string is returned. If start is negative and the absolute value is larger than the size thereturned string starts at index zero. If length is larger than the number of characters available, only the available characters are returned.

When using sliceWrapSize() on a NIL string the result is NIL.

FUNC $split() list<string> @public

     

Return a list with the string split at white space.

Empty strings are omitted.

Example: "foo bar ".split() returns ["foo", "bar"].

When using split() on a NIL string the result is NIL.

FUNC $split(string sep) list<string> @public

     

Return a list with the string split into pieces, split at sep.

The matches with the sep string are omitted.

sep must match exactly.

When there are no characters between two sep matches, or at the end or start of the string, the list will contain an empty string item.

 "one, two,three".split(", ")
 # result: ["one", "two,three"]

When using ?.split() on a NIL string the result is NIL.

FUNC $splitAnyOf(string charSet) list<string> @public

     

Return a list with the string split at the characters in charSet.

Empty strings are omitted.

Example: "foo/bar: yes ".split("/: ") returns ["foo", "bar", "yes"].

When using ?.split() on a NIL string the result is NIL.

FUNC $startsWith(string s) bool @public

     

Return TRUE when the string starts with s.

When using ?. and the string is NIL returns -1.

FUNC $toArray() array<nat32> @public

     

Return an array with the characters of the string.

Looking up characters by index will be much faster in the array.

Throws an E.IllegalByte exception if a character uses more than 4 bytes.

When the string is NIL this returns NIL.

FUNC $toByteString() byteString @public

     

Return the string as a byteString.

Equivalent to $asByteString()

FUNC $toFloat() float @public

     

Return the number at the start of the string converted to a float.

For example, "1.234".toFloat() returns 1.234.

Ignores anything after the number.

Throws an E.BadValue exception when the string does not start with a digit or a minus sign.

Using toFloat() on a NIL string throws an E.NilAccess exception.

FUNC $toFloat(int &length) float @public

     

Return the number at the start of the string converted to a float.

Sets the length argument to the number of characters used.

Throws an E.BadValue exception when the string does not start with a digit or a minus sign.

Using toFloat() on a NIL string throws an E.NilAccess exception.

FUNC $toInt() int @public

     

Return the digits at the start of the string converted to a number.

For example, "1234".toInt() returns 1234.

Ignores anything after the number.

Throws an E.BadValue exception when the string does not start with a digit or a minus sign.

When using ?.toInt() on a NIL string the result is zero.

FUNC $toInt(int default) int @public

     

Return the digits at the start of the string converted to a number.

For example, "1234".toInt() returns 1234.

Ignores anything after the number.

Returns default when the string does not start with a digit or a minus sign. Also returns default when the string is NIL and ?.toInt() was used.

FUNC $toLower() string @public

     

Return a copy of the string with all characters lower-cased.

TODO: Currently only works for latin1 characters

When using toLower() on a NIL string the result is NIL.

FUNC $toLowerAscii() string @public

     

Return a copy of the string with all ASCII characters lower-cased.

This only handles ASCII letters and leaves all other characters unchanged.

When using toLowerAscii() on a NIL string the result is NIL.

FUNC $toUpper() string @public

     

Return a copy of the string with all characters upper-cased.

TODO: Currently only works for latin1 characters

When using toUpper() on a NIL string the result is NIL.

FUNC $toUpperAscii() string @public

     

Return a copy of the string with all ASCII characters upper-cased.

This only handles ASCII letters and leaves all other characters unchanged.

When using toUpperAscii() on a NIL string the result is NIL.

FUNC $toVarString() varString @public

     

Return the string converted to a varString.

Returns NIL when the string is NIL.

FUNC $trim() string @public

     

Return the string with leading and trailing white space removed.

Returns an empty string if the string contains only white space. Example: " foo bar ".trim() returns "foo bar".

When using ?.trim() on a NIL string the result is NIL.

FUNC $trimLeading() string @public

     

Return the string with leading white space removed.

Returns an empty string if the string contains only white space. Example: " foo bar ".trim() returns "foo bar ".

When using ?.trimLeading() on a NIL string the result is NIL.

FUNC $trimTrailing() string @public

     

Return the string with trailing white space removed.

Returns an empty string if the string contains only white space. Example: " foo bar ".trimTrailing() returns " foo bar".

When using ?.trimTrailing() on a NIL string the result is NIL.

license

      Copyright 2012 Bram Moolenaar All Rights Reserved.

      Licensed under the Apache License, Version 2.0. See the LICENSE file or obtain a copy at: http://www.apache.org/licenses/LICENSE-2.0