328 lines
14 KiB
Racket
328 lines
14 KiB
Racket
#reader(lib "docreader.ss" "scribble")
|
|
@require["mz.ss"]
|
|
|
|
@title[#:tag "bytestrings"]{Byte Strings}
|
|
|
|
A @pidefterm{byte string} is a fixed-length arary of bytes. A
|
|
@pidefterm{byte} is an exact integer between @scheme[0] and
|
|
@scheme[255] inclusive.
|
|
|
|
@index['("byte strings" "immutable")]{A} byte string can be
|
|
@defterm{mutable} or @defterm{immutable}. When an immutable byte
|
|
string is provided to a procedure like @scheme[bytes-set!], the
|
|
@exnraise[exn:fail:contract]. Byte-string constants generated by the
|
|
default reader (see @secref["parse-string"]) are immutable.
|
|
|
|
Two byte strings are @scheme[eq?] when mutating one would mutate the
|
|
other. Two byte strings are @scheme[eqv?] and @scheme[equal?] when
|
|
they have the same length and contain the same sequence of bytes.
|
|
|
|
See also: @scheme[immutable].
|
|
|
|
@; ----------------------------------------
|
|
@section{Byte String Constructors, Selectors, and Mutators}
|
|
|
|
@defproc[(make-bytes [k exact-nonnegative-integer?] [b byte? 0])
|
|
bytes?]{ Returns a new mutable byte string of length @scheme[k] where each
|
|
position in the byte string is initialized with the byte @scheme[b].
|
|
|
|
@examples[(make-bytes 5 65)]}
|
|
|
|
|
|
@defproc[(bytes [b byte?] ...0) bytes?]{ Returns a new mutable byte
|
|
string whose length is the number of provided @scheme[b]s, and whose
|
|
positions are initialized with the given @scheme[b]s.
|
|
|
|
@examples[(bytes 65 112 112 108 101)]}
|
|
|
|
|
|
@defproc[(bytes->immutable-bytes [bstr bytes?]) (and/c bytes?
|
|
immutable?)]{ Returns an immutable byte string with the same content
|
|
as @scheme[bstr], returning @scheme[bstr] itself if @scheme[bstr] is
|
|
immutable.}
|
|
|
|
|
|
@defproc[(bytes? [v any/c]) boolean?]{ Returns @scheme[#t] if @scheme[v]
|
|
is a byte string, @scheme[#f] otherwise.
|
|
|
|
@examples[(bytes? #"Apple") (bytes? "Apple")]}
|
|
|
|
|
|
@defproc[(byte? [v any/c]) boolean?]{ Returns @scheme[#t] if @scheme[v] is
|
|
a byte (i.e., an exact integer between @scheme[0] and @scheme[255]
|
|
inclusive), @scheme[#f] otherwise.
|
|
|
|
@examples[(byte? 65) (byte? 0) (byte? 256) (byte? -1)]}
|
|
|
|
|
|
@defproc[(bytes-length [bstr bytes?]) exact-nonnegative-integer?]{
|
|
Returns the length of @scheme[bstr].
|
|
|
|
@examples[(bytes-length #"Apple")]}
|
|
|
|
|
|
@defproc[(bytes-ref [bstr bytes?] [k exact-nonnegative-integer?])
|
|
byte?]{ Returns the character at position @scheme[k] in @scheme[bstr].
|
|
The first position in the bytes cooresponds to @scheme[0], so the
|
|
position @scheme[k] must be less than the length of the bytes,
|
|
otherwise the @exnraise[exn:fail:contract].
|
|
|
|
@examples[(bytes-ref #"Apple" 0)]}
|
|
|
|
|
|
@defproc[(bytes-set! [bstr (and/c bytes? (not/c immutable?))] [k
|
|
exact-nonnegative-integer?] [b byte?]) void?]{ Changes the
|
|
character position @scheme[k] in @scheme[bstr] to @scheme[b]. The first
|
|
position in the byte string cooresponds to @scheme[0], so the position
|
|
@scheme[k] must be less than the length of the bytes, otherwise the
|
|
@exnraise[exn:fail:contract].
|
|
|
|
@examples[(define s (bytes 65 112 112 108 101))
|
|
(bytes-set! s 4 121)
|
|
s]}
|
|
|
|
|
|
@defproc[(subbytes [bstr bytes?] [start exact-nonnegative-integer?]
|
|
[end exact-nonnegative-integer? (bytes-length str)]) bytes?]{
|
|
Returns a new mutable byte string that is @scheme[(- @scheme[end]
|
|
@scheme[start])] bytes long, and that contains the same bytes
|
|
as @scheme[bstr] from @scheme[start] inclusive to @scheme[end] exclusive. The
|
|
@scheme[start] and @scheme[end] arguments must be less than the length of
|
|
@scheme[bstr], and @scheme[end] must be greater than or equal to @scheme[bstr],
|
|
otherwise the @exnraise[exn:fail:contract].
|
|
|
|
@examples[(subbytes #"Apple" 1 3)
|
|
(subbytes #"Apple" 1)]}
|
|
|
|
|
|
@defproc[(bytes-copy [bstr bytes?]) bytes?]{ Returns
|
|
@scheme[(subbytes str 0)].}
|
|
|
|
|
|
@defproc[(bytes-copy! [dest (and/c bytes? (not/c immutable?))]
|
|
[dest-start exact-nonnegative-integer?]
|
|
[src bytes?]
|
|
[src-start exact-nonnegative-integer? 0]
|
|
[src-end exact-nonnegative-integer? (bytes-length src)])
|
|
void?]{
|
|
Changes the bytes of @scheme[dest] from positions
|
|
@scheme[dest-start] (inclusive) to @scheme[dest-end] (exclusive) to
|
|
match the bytes in @scheme[src] from @scheme[src-start]
|
|
(inclusive). The bytes strings @scheme[dest] and @scheme[src] can be the
|
|
same byte string, and in that case the destination region can overlap with
|
|
the source region; the destination bytes after the copy match
|
|
the source bytes from before the copy. If any of
|
|
@scheme[dest-start], @scheme[src-start], or @scheme[src-end]
|
|
are out of range (taking into account the sizes of the bytes strings and
|
|
the source and destination regions), the
|
|
@exnraise[exn:fail:contract].
|
|
|
|
@examples[(define s (bytes 65 112 112 108 101))
|
|
(bytes-copy! s 4 #"y")
|
|
(bytes-copy! s 0 s 3 4)
|
|
s]}
|
|
|
|
@defproc[(bytes-fill! [dest (and/c bytes? (not/c immutable?))] [char
|
|
char?]) void?]{ Changes @scheme[dest] so that every position in the
|
|
bytes is filled with @scheme[char].
|
|
|
|
@examples[(define s (bytes 65 112 112 108 101))
|
|
(bytes-fill! s 113)
|
|
s]}
|
|
|
|
|
|
@defproc[(bytes-append [bstr bytes?] ...0) bytes?]{ Returns a new
|
|
mutable byte string that is as long as the sum of the given @scheme[bstr]s'
|
|
lengths, and that contains the concatenated bytes of the given
|
|
@scheme[bstr]s. If no @scheme[bstr]s are provided, the result is a zero-length
|
|
byte string.
|
|
|
|
@examples[(bytes-append #"Apple" #"Banana")]}
|
|
|
|
|
|
@defproc[(bytes->list [bstr bytes?]) (listof byte?)]{ Returns a new
|
|
list of bytes coresponding to the content of @scheme[bstr]. That is,
|
|
the length of the list is @scheme[(bytes-length @scheme[bstr])], and the
|
|
sequence of bytes of @scheme[bstr] are in the same sequence in the
|
|
result list.
|
|
|
|
@examples[(bytes->list #"Apple")]}
|
|
|
|
|
|
@defproc[(list->bytes [lst (listof byte?)]) bytes?]{ Returns a new
|
|
mutable bytes whose content is the list of bytes in @scheme[lst].
|
|
That is, the length of the bytes is @scheme[(length @scheme[lst])], and
|
|
the sequence of bytes in @scheme[lst] is in the same sequence in
|
|
the result bytes.
|
|
|
|
@examples[(list->bytes (list 65 112 112 108 101))]}
|
|
|
|
|
|
@; ----------------------------------------
|
|
@section{Byte String Comparisons}
|
|
|
|
|
|
@defproc[(bytes=? [bstr1 bytes?] [bstr2 bytes?] ...1) boolean?]{ Returns
|
|
@scheme[#t] if all of the arguments are @scheme[eqv?].}
|
|
|
|
@examples[(bytes=? #"Apple" #"apple")
|
|
(bytes=? #"a" #"as" #"a")]
|
|
|
|
@define[(bytes-sort direction)
|
|
@elem{Like @scheme[bytes<?], but checks whether the arguments are @|direction|.}]
|
|
|
|
@defproc[(bytes<? [bstr1 bytes?] [bstr2 bytes?] ...1) boolean?]{
|
|
Returns @scheme[#t] if the arguments are lexicographically sorted
|
|
increasing, where individual bytes are ordered by @scheme[<],
|
|
@scheme[#f] otherwise.
|
|
|
|
@examples[(bytes<? #"Apple" #"apple")
|
|
(bytes<? #"apple" #"Apple")
|
|
(bytes<? #"a" #"b" #"c")]}
|
|
|
|
@defproc[(bytes>? [bstr1 bytes?] [bstr2 bytes?] ...1) boolean?]{
|
|
@bytes-sort["decreasing"]
|
|
|
|
@examples[(bytes>? #"Apple" #"apple")
|
|
(bytes>? #"apple" #"Apple")
|
|
(bytes>? #"c" #"b" #"a")]}
|
|
|
|
@; ----------------------------------------
|
|
@section{Bytes to/from Characters, Decoding and Encoding}
|
|
|
|
|
|
@defproc[(bytes->string/utf-8 [bstr bytes?]
|
|
[err-char (or/c false/c char?) #f]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (bytes-length bstr)])
|
|
string?]{
|
|
Produces a string by decoding the @scheme[start] to @scheme[end]
|
|
substring of @scheme[bstr] as a UTF-8 encoding of Unicode code points.
|
|
If @scheme[err-char] is not @scheme[#f], then it is used
|
|
for bytes that fall in the range @scheme[#o200] to @scheme[#o377] but
|
|
are not part of a valid encoding sequence. (This is consistent with
|
|
reading characters from a port; see @secref["ports"] for more details.)
|
|
If @scheme[err-char] is @scheme[#f], and if the
|
|
@scheme[start] to @scheme[end] substring of @scheme[bstr] is not a valid
|
|
UTF-8 encoding overall, then the @exnraise[exn:fail:contract].}
|
|
|
|
@defproc[(bytes->string/locale [bstr bytes?]
|
|
[err-char (or/c false/c char?) #f]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (bytes-length bstr)])
|
|
string?]{
|
|
Produces a string by decoding the @scheme[start] to @scheme[end] substring
|
|
of @scheme[bstr] using the current locale's encoding (see also
|
|
@secref["locales"]). If @scheme[err-char] is not
|
|
@scheme[#f], it is used for each byte in @scheme[bstr] that is not part
|
|
of a valid encoding; if @scheme[err-char] is @scheme[#f], and if the
|
|
@scheme[start] to @scheme[end] substring of @scheme[bstr] is not a valid
|
|
encoding overall, then the @exnraise[exn:fail:contract].}
|
|
|
|
@defproc[(bytes->string/latin-1 [bstr bytes?]
|
|
[err-char (or/c false/c char?) #f]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (bytes-length bstr)])
|
|
string?]{
|
|
Produces a string by decoding the @scheme[start] to @scheme[end] substring
|
|
of @scheme[bstr] as a Latin-1 encoding of Unicode code points; i.e.,
|
|
each byte is translated directly to a character using
|
|
@scheme[integer->char], so the decoding always succeeds. (See also the
|
|
Latin-1 footnote of @secref["encodings"].) The @scheme[err-char]
|
|
argument is ignored, but present for consistency with the other
|
|
operations.}
|
|
|
|
@defproc[(string->bytes/utf-8 [str string?]
|
|
[err-byte (or/c false/c byte?) #f]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (string-length str)])
|
|
bytes?]{
|
|
Produces a byte string by encoding the @scheme[start] to @scheme[end]
|
|
substring of @scheme[str] via UTF-8 (always succeeding). The
|
|
@scheme[err-byte] argument is ignored, but included for consistency with
|
|
the other operations.}
|
|
|
|
@defproc[(string->bytes/locale [str string?]
|
|
[err-byte (or/c false/c byte?) #f]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (string-length str)])
|
|
bytes?]{
|
|
Produces a string by encoding the @scheme[start] to @scheme[end] substring
|
|
of @scheme[str] using the current locale's encoding (see also
|
|
@secref["locales"]). If @scheme[err-byte] is not @scheme[#f], it is used
|
|
for each character in @scheme[str] that cannot be encoded for the
|
|
current locale; if @scheme[err-byte] is @scheme[#f], and if the
|
|
@scheme[start] to @scheme[end] substring of @scheme[str] cannot be encoded,
|
|
then the @exnraise[exn:fail:contract].}
|
|
|
|
@defproc[(string->bytes/latin-1 [str string?]
|
|
[err-byte (or/c false/c byte?) #f]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (string-length str)])
|
|
bytes?]{
|
|
Produces a string by encoding the @scheme[start] to @scheme[end] substring
|
|
of @scheme[str] using Latin-1; i.e., each character is translated
|
|
directly to a byte using @scheme[char->integer]. If @scheme[err-byte] is
|
|
not @scheme[#f], it is used for each character in @scheme[str] whose
|
|
value is greater than @scheme[255]. (See also the Latin-1 footnote of
|
|
@secref["encodings"]. If @scheme[err-byte] is @scheme[#f], and if the
|
|
@scheme[start] to @scheme[end] substring of @scheme[str] has a character
|
|
with a value greater than @scheme[255], then the
|
|
@exnraise[exn:fail:contract].}
|
|
|
|
@defproc[(string-utf-8-length [str string?]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (string-lenght str)])
|
|
exact-nonnegative-integer?]{
|
|
Returns the length in bytes of the UTF-8 encoding of @scheme[str]'s
|
|
substring from @scheme[start] to @scheme[end], but without actually
|
|
generating the encoded bytes.}
|
|
|
|
@defproc[(bytes-utf-8-length [bstr bytes?]
|
|
[err-char (or/c false/c char?) #f]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (bytes-length bstr)])
|
|
exact-nonnegative-integer?]{
|
|
Returns the length in characters of the UTF-8 decoding of
|
|
@scheme[bstr]'s substring from @scheme[start] to @scheme[end], but without
|
|
actually generating the decoded characters. If @scheme[err-char] is
|
|
@scheme[#f] and the substring is not a UTF-8 encoding overall, the
|
|
result is @scheme[#f]. Otherwise, @scheme[err-char] is used to resolve
|
|
decoding errors as in @scheme[bytes->string/utf-8].}
|
|
|
|
@defproc[(bytes-utf-8-ref [bstr bytes?]
|
|
[skip exact-nonnegative-integer? 0]
|
|
[err-char (or/c false/c char?) #f]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (bytes-length bstr)])
|
|
char?]{
|
|
Returns the @scheme[skip]th character in the UTF-8 decoding of
|
|
@scheme[bstr]'s substring from @scheme[start] to @scheme[end], but without
|
|
actually generating the other decoded characters. If the substring is
|
|
not a UTF-8 encoding up to the @scheme[skip]th character (when
|
|
@scheme[err-char] is @scheme[#f]), or if the substring decoding produces
|
|
fewer than @scheme[skip] characters, the result is @scheme[#f]. If
|
|
@scheme[err-char] is not @scheme[#f], it is used to resolve decoding
|
|
errors as in @scheme[bytes->string/utf-8].}
|
|
|
|
@defproc[(bytes-utf-8-index [bstr bytes?]
|
|
[skip exact-nonnegative-integer? 0]
|
|
[err-char (or/c false/c char?) #f]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (bytes-length bstr)])
|
|
exact-nonnegative-integer?]{
|
|
Returns the offset in bytes into @scheme[bstr] at which the @scheme[skip]th
|
|
character's encoding starts in the UTF-8 decoding of @scheme[bstr]'s
|
|
substring from @scheme[start] to @scheme[end] (but without actually
|
|
generating the other decoded characters). The result is relative to
|
|
the start of @scheme[bstr], not to @scheme[start]. If the substring is not
|
|
a UTF-8 encoding up to the @scheme[skip]th character (when
|
|
@scheme[err-char] is @scheme[#f]), or if the substring decoding produces
|
|
fewer than @scheme[skip] characters, the result is @scheme[#f]. If
|
|
@scheme[err-char] is not @scheme[#f], it is used to resolve decoding
|
|
errors as in @scheme[bytes->string/utf-8].}
|
|
|
|
@; ----------------------------------------
|
|
@section{Bytes to Bytes Encoding Conversion}
|
|
|