up: VARBYTESTRING     index Zimbu documentation

CLASS T.varByteString @public

summary

     

The builtin type varByteString.

The varByteString is a sequence of bytes (octets), including NUL.

This uses the same storage as varString. Making mutations is done in an efficient way, avoiding too many reallocations and copying.

$Size() int @public  Return the size of the varByteString, the number of bytes.
$ToString() string @public  Return the varByteString as a string.
$toVarString() varString @public  Return the varByteString as a varString.
$asVarString() varString @public  Return the varByteString as a varString.
$toByteString() byteString @public  Return the varByteString as a byteString.
$toVarByteString() varByteString @public  Return the varByteString as-is, this is a no-op.
$find(s) int @public  Return the lowest index where varByteString 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 varByteString 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 varByteString s appears.
$findLast(c) int @public  Return the highest index of the character c.
$startsWith(s) bool @public  Return TRUE when the varByteString starts with s.
$endsWith(s) bool @public  Return TRUE when the varByteString ends with s.
$hash() int @public  Return a number that is a hash value of the varByteString.
$add(s) varByteString @public  Append a byteString to the varByteString.
$slice(start) varByteString @public  Return a copy of the varByteString, starting at index start.
$slice(start, end) varByteString @public  Return a copy of the varByteString, starting at index start and ending at end, inclusive.
$sliceSize(start, length) varByteString @public  Return a copy of the varByteString, starting at index start with up to length bytes.
$sliceWrap(start) varByteString @public  Return a copy of the varByteString, starting at index start.
$sliceWrap(start, end) varByteString @public  Return a copy of the varByteString, starting at index start and ending at end, inclusive.
$sliceWrapSize(start, length) varByteString @public  Return a copy of the varByteString, starting at index start with up to length bytes.
$split() list<byteString> @public  Return a list with the varByteString split into pieces, split at white space.
$split(sep) list<byteString> @public  Return a list with the varByteString split into pieces, split at sep.
 
 

members (alphabetically)

     

FUNC $Size() int @public

     

Return the size of the varByteString, the number of bytes.

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

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

FUNC $ToString() string @public

     

Return the varByteString as a string.

When the varByteString is NIL this returns NIL

FUNC $add(byteString s) varByteString @public

     

Append a byteString to the varByteString.

Returns the modified varByteString.

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

FUNC $asVarString() varString @public

     

Return the varByteString as a varString.

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

FUNC $endsWith(varByteString s) bool @public

     

Return TRUE when the varByteString ends with s.

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

FUNC $find(varByteString s) int @public

     

Return the lowest index where varByteString s appears.

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

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

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

     

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

FUNC $findLast(varByteString s) int @public

     

Return the highest index where varByteString s appears.

When s matches at the start 0 is returned.

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

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

FUNC $hash() int @public

     

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

A varByteString value always results in the same hash value. Two different varByteString 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 $slice(int start) varByteString @public

     

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

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

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

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

     

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

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

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

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

     

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

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

FUNC $sliceWrap(int start) varByteString @public

     

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

A negative index is relative to the end of the varByteString, sliceWrap(-1) returns a varByteString 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 varByteString an empty varByteString is returned. If start is negative and the absolute value is larger than the varByteString size the whole varByteString is returned.

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

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

     

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

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

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

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

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

     

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

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

FUNC $split() list<byteString> @public

     

Return a list with the varByteString 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 varByteString split into pieces, split at sep.

The matches with the sep byteString are omitted.

sep must match exactly.

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

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

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

FUNC $startsWith(varByteString s) bool @public

     

Return TRUE when the varByteString starts with s.

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

FUNC $toByteString() byteString @public

     

Return the varByteString as a byteString.

When the varByteString is NIL this returns NIL.

FUNC $toVarByteString() varByteString @public

     

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

Also works on NIL.

FUNC $toVarString() varString @public

     

Return the varByteString as a varString.

This does not do any conversion, it only changes the type of the object. Also works on a 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