up: BYTESTRING     index Zimbu documentation

CLASS T.byteString @public

summary

     

The builtin type byteString.

A byteString is a sequence of bytes (octets) with any value from 0 to 255. A byteString cannot be modified, see varByteString for a mutable byteString.

The C implementation uses a sequence of bytes. Conversion to and from string does not involve changes.

The Javascript implementation uses a sequence of characters. Conversion to and from string involves using the characters as utf-8 bytes and requires work.

The object methods can be used on a byteString value:

 byteString buffer = "foobar"
 IO.print(buffer.asString())

$Size() int @public  Return the number of bytes in the byteString.
$ToString() string @public  Convert the byteString to a string.
$ToString(format) string @public  Convert the byteString to a string and then apply format.
$latin1ToString() string @public  Assuming that the byteString contains Latin1 characters, return a string encoded in utf-8.
$asByteString() byteString @public  Returns itself.
$toByteString() byteString @public  Returns itself.
$Compare(other) int @public  Return -1, 0 or 1 when other is larger, equal to or smaller than this byteString.
$Equal(other) bool @public  Return TRUE when other is equal to this byteString, FALSE otherwise.
$asString() string @public  Return the byteString as a string.
$toVarString() varString @public  Convert the byteString to a varString. Equivalent to $latin1ToString().toVarString().
$toVarByteString() varByteString @public  Convert the byteString to a varByteString.
$get(idx) int @public  Return the byte at position idx.
$getByte(idx) int @public  Return the byte at position idx.
$getChar(idx) int @public  Return the UTF-8 encoded character at position idx.
$getCharSize(idx) int @public  Return the byte size of the UTF-8 encoded character at position idx.
$find(b) int @public  Return the lowest index where byteString b appears.
$find(b) int @public  Return the lowest index where byte b appears.
$findLast(b) int @public  Return the highest index where byteString b appears.
$findLast(b) int @public  Return the highest index where byte b appears.
$startsWith(b) bool @public  Return TRUE when the byteString starts with b.
$endsWith(b) bool @public  Return TRUE when the byteString ends with b.
$hash() int @public  Return a number that is a hash value of the byteString.
$slice(start) byteString @public  Return a copy of the byteString, starting at index start.
$slice(start, end) byteString @public  Return a copy of the byteString, starting at index start and ending at end, inclusive.
$sliceSize(start, length) byteString @public  Return a copy of the byteString, starting at index start with up to length bytes.
$sliceWrap(start) byteString @public  Return a copy of the byteString, starting at index start.
$sliceWrap(start, end) byteString @public  Return a copy of the byteString, starting at index start and ending at end, inclusive.
$sliceWrapSize(start, length) byteString @public  Return a copy of the byteString, starting at index start with up to length bytes.
$split() list<byteString> @public  Return a list with the byteString split into pieces, split at white space.
$split(sep) list<byteString> @public  Return a list with the byteString split into pieces, split at sep.
 
 

members (alphabetically)

     

FUNC $Compare(byteString other) int @public

     

Return -1, 0 or 1 when other is larger, equal to or smaller than this byteString.

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

FUNC $Equal(byteString other) bool @public

     

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

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

FUNC $Size() int @public

     

Return the number of bytes in the byteString.

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

The empty byteString returns zero.

FUNC $ToString() string @public

     

Convert the byteString to a string.

Same as $latin1ToString().

When the byteString is NIL this returns NIL.

FUNC $ToString(string format) string @public

     

Convert the byteString to a string and then apply format.

Same as $latin1ToString().ToString(format).

When the byteString is NIL this returns NIL.

FUNC $asByteString() byteString @public

     

Returns itself.

For consistency with string.asByteString()

When the byteString is NIL this returns NIL.

FUNC $asString() string @public

     

Return the byteString as a string.

Throws an exception if the byteString is not valid UTF-8.

When the byteString is NIL this returns NIL.

FUNC $endsWith(byteString b) bool @public

     

Return TRUE when the byteString ends with b.

When using ?.endsWith() and the byteString is NIL returns -1.

FUNC $find(byteString b) int @public

     

Return the lowest index where byteString b appears.

Returns -1 when b does not appear.

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

FUNC $find(int b) int @public

     

Return the lowest index where byte b appears.

Returns -1 when b does not appear.

Throws an exception when b < 0 or b > 255.

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

FUNC $findLast(byteString b) int @public

     

Return the highest index where byteString b appears.

Returns -1 when b does not appear.

When using ?.findLast() and the byteString is NIL returns -1.

FUNC $findLast(int b) int @public

     

Return the highest index where byte b appears.

Returns -1 when b does not appear.

Throws an exception when b < 0 or b > 255.

When using ?.findLast() and the byteString is NIL returns -1.

FUNC $get(int idx) int @public

     

Return the byte at position idx.

Throws an exception if idx is < 0 or beyond the end of the byteString.

When using ?.get() and the byteString is NIL this returns zero.

FUNC $getByte(int idx) int @public

     

Return the byte at position idx.

Throws an exception if idx is < 0 or beyond the end of the byteString.

When using ?.getByte() and the byteString is NIL this returns zero.

FUNC $getChar(int idx) int @public

     

Return the UTF-8 encoded character at position idx.

Throws an exception if idx is < 0 or beyond the end of the byteString. Returns -1 if the byte sequence does not start with a leading byte or when it is truncated.

When using ?.getChar() and the byteString is NIL this returns zero.

FUNC $getCharSize(int idx) int @public

     

Return the byte size of the UTF-8 encoded character at position idx.

Throws an exception if idx is < 0 or beyond the end of the byteString. Returns -1 if the byte sequence does not start with a leading byte or when it is truncated. Returns 1 for a NUL byte.

When using ?.getCharSize() and the byteString is NIL this returns zero.

FUNC $hash() int @public

     

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

A byteString value always results in the same hash value. Two different byteString 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 $latin1ToString() string @public

     

Assuming that the byteString contains Latin1 characters, return a string encoded in utf-8.

Takes each byte and converts it to an UTF-8 character. The resulting string size (counting characters) is equal to the size of the byteString. The byte size of the string may be up to twice that.

For example: "foo".latin1ToString() returns "foo".

When the byteString is NIL this returns NIL.

FUNC $slice(int start) byteString @public

     

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

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

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

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

     

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

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

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

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

     

Return a copy of the byteString, starting at index start with up to length bytes.

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

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

FUNC $sliceWrap(int start) byteString @public

     

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

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

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

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

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

     

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

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

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

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

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

     

Return a copy of the byteString, starting at index start with up to length bytes.

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

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

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

FUNC $split() list<byteString> @public

     

Return a list with the byteString split into pieces, split at white space.

Empty parts are omitted.

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

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

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

     

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

The matches with the sep byteString are omitted.

sep must match exactly.

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

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

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

FUNC $startsWith(byteString b) bool @public

     

Return TRUE when the byteString starts with b.

When using ?.startsWith() and the byteString is NIL returns -1.

FUNC $toByteString() byteString @public

     

Returns itself.

Equivalent to $asByteString()

FUNC $toVarByteString() varByteString @public

     

Convert the byteString to a varByteString.

When the byteString is NIL this returns NIL.

FUNC $toVarString() varString @public

     

Convert the byteString to a varString. Equivalent to $latin1ToString().toVarString().

When the byteString is NIL this returns 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