up: VARSTRING     index Zimbu documentation

CLASS T.varString @public

summary

     

The builtin type varString.

The varString can contain any sequence of Unicode characters, including NUL.

VarString is mutable. The characters are stored in an optimal way, depending on the mutations. When possible a string is used. When appending strings a list of strings is used to avoid reallocation and copying. When appending characters extra space is allocated to reduce reallocations.

 varString s = "foo"  # initialize from a string constant
 s.append("bar")      # "foobar"
 s.makeUpper()        # "FOOBAR"

The characters are UTF-8 encoded. Illegal byte sequences may appear but cause an exception for operations that work with characters.

The storage is identical to varByteString, a varString can be typecast to varByteString and the other way around without conversion:

 varString vs = getString()
 varByteString vb = vs.asVarByteString()   # quick, no conversion

$Size() int @public  Return the size of the varString in characters.
$ToString() string @public  Return the varString as a string.
$toVarString() string @public  Return the varString as-is, this is a no-op.
$asVarbyteString() varByteString @public  Return the varString as a varByteString.
$toVarbyteString() varByteString @public  Return the varString as a varByteString.
$toInt() int @public  Return the digits at the start of the varString converted to a number.
$toInt(default) int @public  Return the digits at the start of the varString converted to a number.
$quotedToInt() int @public  Return the digits at the start of the varString converted to a number, ignoring quotes.
$quotedToInt(default) int @public  Return the digits at the start of the varString converted to a number, ignoring quotes.
$hexToInt() int @public  Return the hex digits at the start of the varString converted to a number.
$hexToInt(default) int @public  Return the hex digits at the start of the varString converted to a number.
$quotedHexToInt() int @public  Return the hex digits at the start of the varString converted to a number, ignoring quotes.
$quotedHexToInt(default) int @public  Return the hex digits at the start of the varString converted to a number, ignoring quotes.
$binToInt() int @public  Return the binary digits at the start of the varString converted to a number.
$binToInt(default) int @public  Return the binary digits at the start of the varString converted to a number.
$quotedBinToInt() int @public  Return the binary digits at the start of the varString converted to a number, ignoring quotes.
$quotedBinToInt(default) int @public  Return the binary digits at the start of the varString converted to a number, ignoring quotes.
$toLower() varString @public  Return a copy of the varString with all characters lower-cased.
$toLowerAscii() varString @public  Return a copy of the varString with all ASCII characters lower-cased.
$toUpper() varString @public  Return a copy of the varString with all characters upper-cased.
$toUpperAscii() varString @public  Return a copy of the varString with all ASCII characters upper-cased.
$find(s) int @public  Return the lowest index where varString s appears.
$find(c) int @public  Return the lowest index of the character c.
$find(s, start) int @public  Return the lowest index where the varString 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 varString s appears.
$findLast(c) int @public  Return the highest index of the character c.
$startsWith(s) bool @public  Return TRUE when the varString starts with s.
$endsWith(s) bool @public  Return TRUE when the varString ends with s.
$hash() int @public  Return a number that is a hash value of the varString.
$add(s) varString @public  Append a string to the varString.
$slice(start) varString @public  Return a copy of the varString, starting at index start.
$slice(start, end) varString @public  Return a copy of the varString, starting at index start and ending at end, inclusive.
$sliceSize(start, length) varString @public  Return a copy of the varString, starting at index start with up to length characters.
$sliceWrap(start) varString @public  Return a copy of the varString, starting at index start.
$sliceWrap(start, end) varString @public  Return a copy of the varString, starting at index start and ending at end, inclusive.
$sliceWrapSize(start, length) varString @public  Return a copy of the varString, starting at index start with up to length characters
$split() list<string> @public  Return a list with the varString split at white space.
$split(sep) list<string> @public  Return a list with the varString split into pieces, split at sep.
$splitAnyOf(charSet) list<string> @public  Return a list with the varString split at the characters in charSet.
 
 

members (alphabetically)

     

FUNC $Size() int @public

     

Return the size of the varString in characters.

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

The size is stored thus this method is efficient. It does not go over the characters to find the end.

The empty varString returns zero. When used on NIL Size() returns zero, it does not throw an E.NilAccess exception.

FUNC $ToString() string @public

     

Return the varString as a string.

When the varString is NIL this returns NIL.

FUNC $add(string s) varString @public

     

Append a string to the varString.

Returns the modified varString.

When the varString is NIL throws a NilAccess exception, also when using ?.

FUNC $asVarbyteString() varByteString @public

     

Return the varString as a varByteString.

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

FUNC $binToInt() int @public

     

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

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

Ignores anything after the number.

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

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

FUNC $binToInt(int default) int @public

     

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

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

Ignores anything after the number.

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

FUNC $endsWith(varString s) bool @public

     

Return TRUE when the varString ends with s.

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

FUNC $find(varString s) int @public

     

Return the lowest index where varString s appears.

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

When using ?.find() and the varString 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 varString is NIL returns -1.

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

     

Return the lowest index where the varString 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 varString 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 varString is NIL returns -1.

FUNC $findLast(varString s) int @public

     

Return the highest index where varString s appears.

When s matches at the start 0 is returned.

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

When using ?. and the varString 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 varString is NIL returns -1.

FUNC $hash() int @public

     

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

A varString value always results in the same hash value. Two different varStrings 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.

TODO: this should return a nat

FUNC $hexToInt() int @public

     

Return the hex digits at the start of the varString 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 varString does not start with a hex digit. Also when it starts with "-".

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

FUNC $hexToInt(int default) int @public

     

Return the hex digits at the start of the varString 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 varString does not start with a hex digit. That includes "-". Also returns default when the varString is NIL and ?.hexToInt() was used.

FUNC $quotedBinToInt() int @public

     

Return the binary digits at the start of the varString 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 varString does not start with a 0 or 1.

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

FUNC $quotedBinToInt(int default) int @public

     

Return the binary digits at the start of the varString 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 varString does not start with a 0 or 1 and when using ?.quotedBinToInt() on a NIL varString.

FUNC $quotedHexToInt() int @public

     

Return the hex digits at the start of the varString 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 varString does not start with a hex digit. That includes "-".

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

FUNC $quotedHexToInt(int default) int @public

     

Return the hex digits at the start of the varString 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 varString does not start with a hex digit. That includes "-". Also returns default when the varString is NIL and ?.quotedHexToInt() was used.

FUNC $quotedToInt() int @public

     

Return the digits at the start of the varString 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 varString does not start with a digit or a minus sign.

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

FUNC $quotedToInt(int default) int @public

     

Return the digits at the start of the varString 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 varString does not start with a digit or a minus sign. When using ?.quotedToInt() also when the varString is NIL.

FUNC $slice(int start) varString @public

     

Return a copy of the varString, 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 varString an empty varString is returned. If start is zero or negative the whole varString is returned.

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

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

     

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

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

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

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

     

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

If start is equal to or larger than the size of the varString an empty varString is returned. If start is zero or negative the varString 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 varString the result is NIL.

FUNC $sliceWrap(int start) varString @public

     

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

A negative index is relative to the end of the varString, sliceWrap(-1) returns a varString with only the last character.

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

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

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

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

     

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

A negative index is relative to the end of the varString. sliceWrap(0, -1) returns the whole varString. sliceWrap(-1, -1) only the last character.

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

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

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

     

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

A negative index is relative to the end of the varString. 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 varString an empty varString is returned. If start is negative and the absolute value is larger than the size thereturned varString 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 varString the result is NIL.

FUNC $split() list<string> @public

     

Return a list with the varString split at white space.

Empty parts 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 varString 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 varString, the list will contain an empty string item.

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

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

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

     

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

Empty strings are omitted.

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

FUNC $startsWith(varString s) bool @public

     

Return TRUE when the varString starts with s.

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

FUNC $toInt() int @public

     

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

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

Ignores anything after the number.

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

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

FUNC $toInt(int default) int @public

     

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

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

Ignores anything after the number.

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

FUNC $toLower() varString @public

     

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

TODO: Currently only works for latin1 characters

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

FUNC $toLowerAscii() varString @public

     

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

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

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

FUNC $toUpper() varString @public

     

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

TODO: Currently only works for latin1 characters

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

FUNC $toUpperAscii() varString @public

     

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

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

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

FUNC $toVarString() string @public

     

Return the varString as-is, this is a no-op.

Also works on NIL

FUNC $toVarbyteString() varByteString @public

     

Return the varString as a varByteString.

Equivalent to asVarbyteString()

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