11.48 srfi.207 - String-notated bytevectors

Module: srfi.207 ¶

This SRFI defines an alternative representation of bytevectors, and provides a bunch of procedures that can treat a bytevector as a bytestring.

Function: bytestring arg … ¶

[SRFI-207]{srfi.207} Each argument must be either one of the followings, and the procedure returns a new bytevector which is concatenation of the given arguments.

• An exact integer, between 0 and 255 inclusive.
• An ASCII character.
• A bytevector
• A string of ASCII characters

An error is signaled if anything other than above is given.

(bytestring "lor" #\r #\x65 #u8(#x6d))
  ⇒ #u8(108 111 114 114 101 109)  ; #u8"lorem"

Function: make-bytestring lis ¶

[SRFI-207]{srfi.207} Returns a new bytevector whose content is a concatenation of elements in lis. Each element must be either an exact integer between 0 and 255 inclusive, an ASCII character, a bytevector or an ASCII string. It is effectively the same as (apply bytestring lis).

Function: make-bytestring! bv at lis ¶

[SRFI-207]{srfi.207} Fill a bytevector bv starting from index at with the elements in lis. Each element must be either an exact integer between 0 and 255 inclusive, an ASCII character, a bytevector or an ASCII string.

Returns an undefined value.

(rlet1 bv (make-u8vector 10)
  (make-bytestring! bv 1 '("ab" #\c #u8"de")))
  ⇒ #u8(0 97 98 99 100 101 0 0 0 0)

Function: bytevector->hex-string bv ¶

Function: hex-string->bytevector string ¶

[SRFI-207]{srfi.207} Convert a bytevector to hexadecimal digit string, and vice versa.

A condition that satisfies bytestring-error? is thrown by hex-string->bytevector if string contains a letter not valid as a hexadecimal digits.

(bytevector->hex-string #u8"aloha")
  ⇒ "616c6f6861"
(hex-string->bytevector "616C6F6861")
  ⇒ #u8(97 108 111 104 97)  ; #u8"aloha"

Function: bytevector->base64 bv :optional digits ¶

Function: base64->bytevector string :optional digits ¶

[SRFI-207]{srfi.207} Encode a bytevector bv to Base64 encoded string, and vice versa.

A condition that satisfies bytestring-error? is thrown by base64->bytevector if string contains a letter not valid as a hexadecimal digits. Whitespace characters in string are silently ignored, though.

By default, they use standard Base64 mappings. You can specify a string of two ASCII characters in digits to alter mapping of 62nd and 63rd digits; the ’URL-safe’ variant of Base64 can be achieved by passing "-_" as digits.

See rfc.base64 - Base64 encoding/decoding, for Gauche-specific Base64 library that provides more APIs.

Function: bytestring->list bv :optional start end ¶

[SRFI-207]{srfi.207} Converts each element of a bytevector bv to either a character (if the element is an integer between 32 and 127, inclusive) or an integer, and returns a list of converted elements. If you pass the resulting list to make-bytestring, you can obtain the same bytevector as bv.

If you pass the optional start and end indexes, only the specified range of bv is considered.

Function: make-bytestring-generator arg … ¶

[SRFI-207]{srfi.207} Returns a generator that works as the same as (uvector->generator (bytestring arg …)), but this can skip creating intermediate bytestrings.

Function: bytestring-pad bv len char-or-u8 ¶

Function: bytestring-pad-right bv len char-or-u8 ¶

[SRFI-207]{srfi.207} Returns a newly allocated bytevector of at least len long. If bv is shorter than len, the rest is padded with char-or-u8 (which can be either an ASCII character or an exact integer between 0 and 255). The pad is added to the left with bytestring-pad, and to the right with bytestring-pad-right.

This is a bytestring version of string-pad and string-pad-right (see String selection).

Function: bytestring-trim bv pred ¶

Function: bytestring-trim-right bv pred ¶

Function: bytestring-trim-both bv pred ¶

[SRFI-207]{srfi.207} Remove octets that satisfies pred at the beginning / at the end / at both ends of a bitvector bv. The procedure pred receives an exact integer between 0 and 255.

They always return a fresh bytevector, even when no octets are trimmed.

This is a bytestring version of string-trim, string-trim-right, and string-trim-both (see String selection).

Function: bytrestring-replace bv1 bv2 start1 end1 :optional start2 end2 ¶

[SRFI-207]{srfi.207} Returns a new bytevector whose content is a copy of a bytevector bv1, except the part beginning from the index start1 (inclusive) and ending at the index end1 (exclusive) is replaced by a byvetvector bv2. When optional start2 and end2 arguments are given, bv2 is trimmed first accordingly. The size of the gap, (- end1 start1), doesn’t need to be the same as the size of the inserted bytevector. Effectively, this is the same as the following code.

(bytevector-append (subseq bv1 0 start1)
                   (subseq bv2 start2 end2)
                   (subseq bv1 end1 (bytevector-length bv1)))

This is a bytestring version of string-replace (see Other string operations).

Function: bytestring<? bv1 bv2 ¶

Function: bytestring<=? bv1 bv2 ¶

Function: bytestring>? bv1 bv2 ¶

Function: bytestring>=? bv1 bv2 ¶

[SRFI-207]{srfi.207} Compare two bytevectors lexicographically. These are bytestring version of string<? (see String comparison).

There’s no bytestring=?, for you can check equality of bytevectors by bytevector=? in scheme.bytevector and gauche.uvector (see Bytevector compatibility).

Note that bytevector-comparator compares bytevectors differently. The comparator first compares the lengths, and only uses elements when both vectors are of the same length (see Predefined comparators).

(bytestring<? #u8"abc" #u8"ac") ⇒ #t
(<? bytevector-comparator #u8"abc" #u8"ac") ⇒ #f

This contrasts SRFI-207’s view of bytevectors as a string of bytes, with the view of them as an array of bytes.

Function: bytestring-index bv pred :optional start end ¶

Function: bytestring-index-right bv pred :optional start end ¶

[SRFI-207]{srfi.207} Returns the first or last index of the octet that satisfies pred in a bytevector bv. The optional start and end arguments limit the range to search.

These are bytestring version of string-index and string-index-right (see String searching).

Function: bytestring-break bv pred ¶

Function: bytestring-span bv pred ¶

[SRFI-207]{srfi.207} Returns two bytevectors, the first one is a maximum prefix of bv whose element does not / does satisfy pred, and the second one is the rest of bv.

(bytestring-break #u8"abracadabra" (cut = <> 100))
 ⇒ #u8(97 98 114 97 99 97) and #u8(100 97 98 114 97)
(bytestring-span #u8(1 2 3 4 5 4 3 2 1) (cut < <> 5))
 ⇒ #u8(1 2 3 4) and #u8(5 4 3 2 1)

Function: bytestring-join bv-list delim :optional grammar ¶

[SRFI-207]{srfi.207} Given list of bytevectors bv-list, concatenates the bytevectors with a delimiter delim, which can be an exact integer between 0 and 255 inclusive, an ASCII character, a bytevector or a string of ASCII characters.

The grammar argument must be one of the symbols infix, strict-infix, suffix, and prefix, as in string-join (see String utilities). The difference between infix and strict-infix is that the former allows to join zero byvectors (returns #u8()), while the latter raises an error when bv-list is empty. When omitted, infix is assumed.

(bytestring-join '(#u8"a" #u8"b" #u8"c") 0) ⇒ #u8(97 0 98 0 99)
(bytestring-join '(#u8"a" #u8"b" #u8"c") 0 'prefix) ⇒ #u8(0 97 0 98 0 99)
(bytestring-join '(#u8"a" #u8"b" #u8"c") 0 'suffix) ⇒ #u8(97 0 98 0 99 0)

Function: bytestring-split bv delim :optional grammar ¶

[SRFI-207]{srfi.207} Split a bytevector bv with delim, which must be either an exact integer between 0 and 255 inclusive or an ASCII character, and returns a list of bytevectors. Delimiters themselves are not included in the result.

The grammar argument is, if given, either one of the symbols infix, strict-infix, prefix, or suffix, similar to bytestring-join. If it is prefix/suffix, the preceding/succeeding delim is ignored, if any. There are no difference between infix and strict-infix. The default is infix.

(bytestring-split #u8"abracadabra" #\a)
 ⇒ (#u8() #u8(98 114) #u8(99) #u8(100) #u8(98 114) #u8())
(bytestring-split #u8"abracadabra" #\a 'prefix)
 ⇒ (#u8(98 114) #u8(99) #u8(100) #u8(98 114) #u8())
(bytestring-split #u8"abracadabra" #\a 'suffix)
 ⇒ (#u8() #u8(98 114) #u8(99) #u8(100) #u8(98 114))

Function: read-textual-bytestring prefix :optional port ¶

[SRFI-207]{srfi.207} This parses a textual representation of a bytestring read from port (defaults to the current input port) and returns a bytevector. If prefix is false, it assumes the preceding "#u8" has already been read. If the input can’t be parsed as a valid textual representation of a bytestring, an error satisfying bytestring-error? is raised.

(with-input-from-string "#u8\"abc\\x80;\"" (cut read-textual-bytestring #t))
  ⇒ #u8(97 98 99 128)

Function: write-textual-bytestring bv :optional port ¶

[SRFI-207]{srfi.207} Writes a bytevector bv in the textual representation to port (defaults to the current output port).

(write-textual-bytestring #u8(65 66 128 255 0))
 ⇒ prints #u8"AB\x80;\xff;\x00;"

Function: write-binary-bitestring port arg … ¶

[SRFI-207]{srfi.207}

Works like (write-textual-bytestring (bytestring arg …) port),
but without creating the intermediate bytevector.
If any arguments are invalid to construct a bytevector, an error
satisfying bytestring-error? signaled.

Function: bytestring-error? obj ¶

[SRFI-207]{srfi.207} Returns #t if obj is a condition thrown from bytestring operations.