Sagittarius Users' Reference

(util bytevector) - Bytevector utility library

Library (util bytevector)

This library provides bytevector utilities which are not provided as builtin procedures such as bytevector->integer.

All procedures take bytevector as its arguments.

Function bytevector-xor bv1 bv2 ...

Function bytevector-xor! out bv1 bv2 ...

Function bytevector-ior bv1 bv2 ...

Function bytevector-ior! out bv1 bv2 ...

Function bytevector-and bv1 bv2 ...

Function bytevector-and! out bv1 bv2 ...

Compute exclusive or, logical or and logical and for each given bytevectors, respectively.

The procedures without ! freshly allocate a new bytevector as it's return value. If the given bytevectors are not the same sized, then the smallest size will be allocated.

The procedures with ! takes first argument as the storage of the result and return it.

Function bytevector-slices bv k :key (padding #f)

Slices the given bytevector bv into k size and returns a list of bytevectors.

The keyword argument padding is given and it must be a procedure accept one argument, then it will be called when the last chunk of bytevector is not size of k. The procedure should return padded bytevector and it doesn't check the returned value nor it's size so it is caller's responsibility to make sure the returned value is a bytevector and the size is k.

(bytevector-slices #vu8(1 2 3 4 5 6) 3)

(#vu8(1 2 3) #vu8(4 5 6))

(bytevector-slices #vu8(1 2 3 4) 3)

(#vu8(1 2 3) #vu8(4))

;; the given bytevector bv is #vu8(4)
(bytevector-slices #vu8(1 2 3 4) 3 :padding (lambda (bv) #vu8(4 5 6)))

(#vu8(1 2 3) #vu8(4 5 6))

;; this is valid as well so that bytevector-slices doesn't check the 
;; return value
(bytevector-slices #vu8(1 2 3 4) 3 :padding (lambda (bv) #f))

(#vu8(1 2 3) #f)

Function bytevector-split-at* bv k :key (padding #f)

Splits bytevector into 2 bytevectors and returns 2 values of bytevectors.

The first returned bytevector size will be k and its content is given bytevector's value starting from 0 to k - 1. The second returned value is the rest of values of bv.

If size of the given bytevector bv is less than k then the second value of returned bytevector will be empty bytevector.

The keyword argument padding is given and it must be a procedure accept one argument, then it will be called when given bytevector's size is less than k and first returned value will the result of padding.

(bytevector-split-at* #vu8(1 2 3 4 5) 3)

#vu8(1 2 3) and #vu8(4 5)

(bytevector-split-at* #vu8(1 2) 3 :padding (lambda (bv) #vu8(1 2 3)))

#vu8(1 2 3) and #vu8()

(bytevector-split-at* #vu8(1 2) 3 :padding (lambda (bv) #f))

#f and #vu8()

Function ->odd-parity bv :optional (start 0) (end (bytevector-length bv))

Function ->odd-parity! bv :optional (start 0) (end (bytevector-length bv))

Compute odd parity of the given bytevector bv and return the result of bytevector.

If the second procedure is used, then bv will be modified.

Function bytevector<? bv1 bv2 rest ...

Function bytevector>? bv1 bv2 rest ...

Function bytevector<=? bv1 bv2 rest ...

Function bytevector>=? bv1 bv2 rest ...

Comparing given bytevectors.

The comparison is done by comparing the elements of bytevectors from index 0. The comparison procedures are <, >, <=and >=, respectively.

Function bytevector->hex-string bv :key (upper? #t)

Converts given bytevector bv to hex string.

The keyword argument upper? is specified with true value, then the procedures converts to upper case hex values, otherwise lower case.

Function hex-string->bytevector string

Converts given hex string string to bytevector.

Function bytevector->escaped-string bv

Converts given bytevector to string without transcoder.

The conversion is the same as the following code:

(list->string (map integer->char (bytevector->u8-list bv)))

This procedure is implemented in a memory efficient way.

Function bytevector-reverse! bv :optional (start 0) (end (bytevector-length bv))

Function bytevector-reverse bv :optional (start 0) (end (bytevector-length bv))

Reverse the given bytevector bv.

Optional arguments start and end controls from and until where the procedure reverses the bytevector. end is exclusive.

The bytevector-reverse! reverses destructively.

SRFI-13 convension APIs

U8 sets

U8 set is a list of integers which range is in between 0 <= n <= 255. This is useful to handle bytevectors as if they are ASCII strings.

Function u8? o

Returns #t if given o is an integer in range of 0 <= _o_ <= 255, otherwise #f.

Function u8-set? o

Returns #t if given o is a list and its all elements satisfy u8?. Otherwise #f.

Function u8-set-contains? u8-set u8

u8-set must satisfy u8-set?. u8 should satisfy u8. The procedure doesn't check if arguments satify this.

Returns #t if given u8-set contains u8.

Function string->u8-set string

Converts given string to list of integers. Given string should only contains in range of ASCII characters but the procedure doesn't check. Thus the procedure may return a list doesn't satify u8-set?. It is users' responsibility to pass ASCII string.

Function char-set->u8-set cset

Converts given char-set cset to u8 set. This procedure returns a list that satify u8-set? by dropping outside of ASCII characters.

Bytevectors as ASCII strings

Function bytevector-fold kons knil bv :optional start end

Function bytevector-fold-right kons knil bv :optional start end

Iterate given bv from start until end. kons is called by each element with result of the kons. The inital value is knil.

This is analogy of fold-left and fold-right.

Function bytevector-take bv n

Function bytevector-take-right bv n

Subtract bytevector bv until index n (exclusive).

The bytevector-take takes from left and the bytevector-take-righttakes from right.

Function bytevector-drop bv n

Function bytevector-drop-right bv n

Drops given bv until index n (exclusive).

The bytevector-drop drops from left and the bytevector-drop-rightdrops from right.

Function bytevector-trim bv :optional criterion start end

Function bytevector-trim-right bv :optional criterion start end

Function bytevector-trim-both bv :optional criterion start end

Trims given bytevector bv from left, right and both, respectively.

The optional argument criterion specifies how to trim. By default, it uses whitespaces. " \r\f\v\n\t".

The optional arguments start and end specify from and until where the procedure trims. The default value is 0 for start and the length of given bytevector for end.

Function bytevector-pad bv n :optional (u8 0) start end

Function bytevector-pad-right bv n :optional (u8 0) start end

Pads given bytevector bv with n elements of u8. The bytevector-pad pads left side of given bv. The bytevector-pad-right pads right side of given bv.

The optional arguments start and end specify from and until where the procedure pads. The default value is 0 for start and the length of given bytevector for end.

Function bytevector-prefix-length bv1 bv2 :optional start1 end1 start2 end2

Function bytevector-suffix-length bv1 bv2 :optional start1 end1 start2 end2

Return the length of the longest common prefix/suffix of the two bytevectors.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv1 and bv2.

Function bytevector-prefix? bv1 bv2 :optional start1 end1 start2 end2

Function bytevector-suffix? bv1 bv2 :optional start1 end1 start2 end2

Returns #t if bv1 is a prefix/suffix of bv2. Otherwise #f.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv1 and bv2.

Function bytevector-index bv criterion :optional start end

Function bytevector-index-right bv criterion :optional start end

Searches through the given bytevector bv from the left (right), returning the index of the first occurrence of an element which satisfies the criterion.

criterion can be a u8 value, a u8 set or a procedure.

If the procedure doesn't find any element satisfies criterion, then returns #f.

Function bytevector-skip bv criterion :optional start end

Function bytevector-skip-right bv criterion :optional start end

Search through the given bytevector bv from the left (right), returning the index of the first occurrence of an element which does not satisfy the criterion.

criterion can be a u8 value, a u8 set or a procedure.

If the procedure doesn't find any element which does not satisfy criterion, then returns #f.

Function bytevector-contains bv1 bv2 :optional start1 end1 start2 end2

Returns index of bv1 where bv2 is found. If bv1 doesn't contain bv2 then returns #f.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv1 and bv2.

Function bytevector-replace bv1 bv2 start1 end2 :optional start2 end2

Returns

(bytevector-append (bytevector-copy s1 0 start1)
                   (bytevector-copy s2 start2 end2)
                   (bytevector-copy s1 end1 (string-length s1)))

Function bytevector-tokenize bv :optional token-set start end

Split the given bytevector bv into a list of sub bytevectors, where each sub bytevector is a maximal non-empty contigunous sequence of elements from the u8 set token-set.

Optional argument token-set must be a u8 set. By default, it's a list of bytes of ASCII graphical characters.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv.

Function bytevector-filter criterion bv :optional start end

Function bytevector-delete criterion bv :optional start end

Filter the bytevector bv, retaining only those elements that satisfy / do not satisfy the criterion argument.

criterion can be a u8 value, a u8 set or a procedure.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv.