1 Language Model
2 Syntactic Forms
3 Datatypes
4 Structures
5 Classes and Objects
6 Units
7 Contracts
8 Pattern Matching
9 Control Flow
10 Concurrency
11 Macros
12 Input and Output
13 Reflection and Security
14 Operating System
15 Memory Management
16 Running PLT Scheme
Bibliography
Index
On this page:
3.4.1 Byte String Constructors, Selectors, and Mutators
bytes?
make-bytes
bytes
bytes->immutable-bytes
byte?
bytes-length
bytes-ref
bytes-set!
subbytes
bytes-copy
bytes-copy!
bytes-fill!
bytes-append
bytes->list
list->bytes
3.4.2 Byte String Comparisons
bytes=?
bytes<?
bytes>?
3.4.3 Bytes to/ from Characters, Decoding and Encoding
bytes->string/ utf-8
bytes->string/ locale
bytes->string/ latin-1
string->bytes/ utf-8
string->bytes/ locale
string->bytes/ latin-1
string-utf-8-length
bytes-utf-8-length
bytes-utf-8-ref
bytes-utf-8-index
3.4.4 Bytes to Bytes Encoding Conversion
bytes-open-converter
bytes-close-converter
bytes-convert
bytes-convert-end
bytes-converter?
locale-string-encoding
Version: 4.0.2

 

3.4 Byte Strings

Bytes and Byte Strings in Guide: PLT Scheme introduces byte strings.

    3.4.1 Byte String Constructors, Selectors, and Mutators

    3.4.2 Byte String Comparisons

    3.4.3 Bytes to/from Characters, Decoding and Encoding

    3.4.4 Bytes to Bytes Encoding Conversion

A byte string is a fixed-length array of bytes. A byte is an exact integer between 0 and 255 inclusive.

A byte string can be mutable or immutable. When an immutable byte string is provided to a procedure like bytes-set!, the exn:fail:contract exception is raised. Byte-string constants generated by the default reader (see Reading Strings) are immutable.

Two byte strings are equal? when they have the same length and contain the same sequence of bytes.

A byte string can be used as a single-valued sequence (see Sequences). The bytes of the string serve as elements of the sequence. See also in-bytes.

See also: immutable.

3.4.1 Byte String Constructors, Selectors, and Mutators

(bytes? v)  boolean?

  v : any/c

Returns #t if v is a byte string, #f otherwise.

Examples:

  > (bytes? #"Apple")

  #t

  > (bytes? "Apple")

  #f

(make-bytes k [b])  bytes?

  k : exact-nonnegative-integer?

  b : byte? = 0

Returns a new mutable byte string of length k where each position in the byte string is initialized with the byte b.

Examples:

  > (make-bytes 5 65)

  #"AAAAA"

(bytes b ...)  bytes?

  b : byte?

Returns a new mutable byte string whose length is the number of provided bs, and whose positions are initialized with the given bs.

Examples:

  > (bytes 65 112 112 108 101)

  #"Apple"

(bytes->immutable-bytes bstr)

 

 

(and/c bytes?

       immutable?)

  bstr : bytes?

Returns an immutable byte string with the same content as bstr, returning bstr itself if bstr is immutable.

(byte? v)  boolean?

  v : any/c

Returns #t if v is a byte (i.e., an exact integer between 0 and 255 inclusive), #f otherwise.

Examples:

  > (byte? 65)

  #t

  > (byte? 0)

  #t

  > (byte? 256)

  #f

  > (byte? -1)

  #f

(bytes-length bstr)  exact-nonnegative-integer?

  bstr : bytes?

Returns the length of bstr.

Examples:

  > (bytes-length #"Apple")

  5

(bytes-ref bstr k)  byte?

  bstr : bytes?

  k : exact-nonnegative-integer?

Returns the character at position k in bstr. The first position in the bytes cooresponds to 0, so the position k must be less than the length of the bytes, otherwise the exn:fail:contract exception is raised.

Examples:

  > (bytes-ref #"Apple" 0)

  65

(bytes-set! bstr k b)  void?

  bstr : (and/c bytes? (not/c immutable?))

  k : exact-nonnegative-integer?

  b : byte?

Changes the character position k in bstr to b. The first position in the byte string cooresponds to 0, so the position k must be less than the length of the bytes, otherwise the exn:fail:contract exception is raised.

Examples:

  > (define s (bytes 65 112 112 108 101))

  > (bytes-set! s 4 121)

  > s

  #"Apply"

(subbytes bstr start [end])  bytes?

  bstr : bytes?

  start : exact-nonnegative-integer?

  end : exact-nonnegative-integer? = (bytes-length str)

Returns a new mutable byte string that is (- end start) bytes long, and that contains the same bytes as bstr from start inclusive to end exclusive. The start and end arguments must be less than the length of bstr, and end must be greater than or equal to bstr, otherwise the exn:fail:contract exception is raised.

Examples:

  > (subbytes #"Apple" 1 3)

  #"pp"

  > (subbytes #"Apple" 1)

  #"pple"

(bytes-copy bstr)  bytes?

  bstr : bytes?

Returns (subbytes str 0).

(bytes-copy!

 

dest

 

 

 

 

 

 

dest-start

 

 

 

 

 

 

src

 

 

 

 

 

 [

src-start

 

 

 

 

 

 

src-end])

 

 

void?

  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)

Changes the bytes of dest starting at position dest-start to match the bytes in src from src-start (inclusive) to src-end (exclusive). The bytes strings dest and 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 dest-start, src-start, or src-end are out of range (taking into account the sizes of the bytes strings and the source and destination regions), the exn:fail:contract exception is raised.

Examples:

  > (define s (bytes 65 112 112 108 101))

  > (bytes-copy! s 4 #"y")

  > (bytes-copy! s 0 s 3 4)

  > s

  #"lpply"

(bytes-fill! dest char)  void?

  dest : (and/c bytes? (not/c immutable?))

  char : char?

Changes dest so that every position in the bytes is filled with char.

Examples:

  > (define s (bytes 65 112 112 108 101))

  > (bytes-fill! s 113)

  > s

  #"qqqqq"

(bytes-append bstr ...)  bytes?

  bstr : bytes?

Returns a new mutable byte string that is as long as the sum of the given bstrs’ lengths, and that contains the concatenated bytes of the given bstrs. If no bstrs are provided, the result is a zero-length byte string.

Examples:

  > (bytes-append #"Apple" #"Banana")

  #"AppleBanana"

(bytes->list bstr)  (listof byte?)

  bstr : bytes?

Returns a new list of bytes coresponding to the content of bstr. That is, the length of the list is (bytes-length (scheme bstr)), and the sequence of bytes of bstr are in the same sequence in the result list.

Examples:

  > (bytes->list #"Apple")

  (65 112 112 108 101)

(list->bytes lst)  bytes?

  lst : (listof byte?)

Returns a new mutable bytes whose content is the list of bytes in lst. That is, the length of the bytes is (length (scheme lst)), and the sequence of bytes in lst is in the same sequence in the result bytes.

Examples:

  > (list->bytes (list 65 112 112 108 101))

  #"Apple"

3.4.2 Byte String Comparisons

(bytes=? bstr1 bstr2 ...+)  boolean?

  bstr1 : bytes?

  bstr2 : bytes?

Returns #t if all of the arguments are eqv?.

Examples:

  > (bytes=? #"Apple" #"apple")

  #f

  > (bytes=? #"a" #"as" #"a")

  #f

(bytes<? bstr1 bstr2 ...+)  boolean?

  bstr1 : bytes?

  bstr2 : bytes?

Returns #t if the arguments are lexicographically sorted increasing, where individual bytes are ordered by <, #f otherwise.

Examples:

  > (bytes<? #"Apple" #"apple")

  #t

  > (bytes<? #"apple" #"Apple")

  #f

  > (bytes<? #"a" #"b" #"c")

  #t

(bytes>? bstr1 bstr2 ...+)  boolean?

  bstr1 : bytes?

  bstr2 : bytes?

Like bytes<?, but checks whether the arguments are decreasing.

Examples:

  > (bytes>? #"Apple" #"apple")

  #f

  > (bytes>? #"apple" #"Apple")

  #t

  > (bytes>? #"c" #"b" #"a")

  #t

3.4.3 Bytes to/from Characters, Decoding and Encoding

(bytes->string/utf-8 bstr [err-char start end])  string?

  bstr : bytes?

  err-char : (or/c false/c char?) = #f

  start : exact-nonnegative-integer? = 0

  end : exact-nonnegative-integer? = (bytes-length bstr)

Produces a string by decoding the start to end substring of bstr as a UTF-8 encoding of Unicode code points. If err-char is not #f, then it is used for bytes that fall in the range 128 to 255 but are not part of a valid encoding sequence. (This is consistent with reading characters from a port; see Encodings and Locales for more details.) If err-char is #f, and if the start to end substring of bstr is not a valid UTF-8 encoding overall, then the exn:fail:contract exception is raised.

(bytes->string/locale

 

bstr

 

 

 

 

 

 [

err-char

 

 

 

 

 

 

start

 

 

 

 

 

 

end])

 

 

string?

  bstr : bytes?

  err-char : (or/c false/c char?) = #f

  start : exact-nonnegative-integer? = 0

  end : exact-nonnegative-integer? = (bytes-length bstr)

Produces a string by decoding the start to end substring of bstr using the current locale’s encoding (see also Encodings and Locales). If err-char is not #f, it is used for each byte in bstr that is not part of a valid encoding; if err-char is #f, and if the start to end substring of bstr is not a valid encoding overall, then the exn:fail:contract exception is raised.

(bytes->string/latin-1

 

bstr

 

 

 

 

 

 [

err-char

 

 

 

 

 

 

start

 

 

 

 

 

 

end])

 

 

string?

  bstr : bytes?

  err-char : (or/c false/c char?) = #f

  start : exact-nonnegative-integer? = 0

  end : exact-nonnegative-integer? = (bytes-length bstr)

Produces a string by decoding the start to end substring of bstr as a Latin-1 encoding of Unicode code points; i.e., each byte is translated directly to a character using integer->char, so the decoding always succeeds. (See also the Latin-1 footnote of Encodings and Locales.) The err-char argument is ignored, but present for consistency with the other operations.

(string->bytes/utf-8 str [err-byte start end])  bytes?

  str : string?

  err-byte : (or/c false/c byte?) = #f

  start : exact-nonnegative-integer? = 0

  end : exact-nonnegative-integer? = (string-length str)

Produces a byte string by encoding the start to end substring of str via UTF-8 (always succeeding). The err-byte argument is ignored, but included for consistency with the other operations.

(string->bytes/locale str [err-byte start end])  bytes?

  str : string?

  err-byte : (or/c false/c byte?) = #f

  start : exact-nonnegative-integer? = 0

  end : exact-nonnegative-integer? = (string-length str)

Produces a string by encoding the start to end substring of str using the current locale’s encoding (see also Encodings and Locales). If err-byte is not #f, it is used for each character in str that cannot be encoded for the current locale; if err-byte is #f, and if the start to end substring of str cannot be encoded, then the exn:fail:contract exception is raised.

(string->bytes/latin-1

 

str

 

 

 

 

 

 [

err-byte

 

 

 

 

 

 

start

 

 

 

 

 

 

end])

 

 

bytes?

  str : string?

  err-byte : (or/c false/c byte?) = #f

  start : exact-nonnegative-integer? = 0

  end : exact-nonnegative-integer? = (string-length str)

Produces a string by encoding the start to end substring of str using Latin-1; i.e., each character is translated directly to a byte using char->integer. If err-byte is not #f, it is used for each character in str whose value is greater than 255. (See also the Latin-1 footnote of Encodings and Locales. If err-byte is #f, and if the start to end substring of str has a character with a value greater than 255, then the exn:fail:contract exception is raised.

(string-utf-8-length str [start end])  exact-nonnegative-integer?

  str : string?

  start : exact-nonnegative-integer? = 0

  end : exact-nonnegative-integer? = (string-lenght str)

Returns the length in bytes of the UTF-8 encoding of str’s substring from start to end, but without actually generating the encoded bytes.

(bytes-utf-8-length bstr [err-char start end])

  exact-nonnegative-integer?

  bstr : bytes?

  err-char : (or/c false/c char?) = #f

  start : exact-nonnegative-integer? = 0

  end : exact-nonnegative-integer? = (bytes-length bstr)

Returns the length in characters of the UTF-8 decoding of bstr’s substring from start to end, but without actually generating the decoded characters. If err-char is #f and the substring is not a UTF-8 encoding overall, the result is #f. Otherwise, err-char is used to resolve decoding errors as in bytes->string/utf-8.

(bytes-utf-8-ref bstr [skip err-char start end])  char?

  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)

Returns the skipth character in the UTF-8 decoding of bstr’s substring from start to end, but without actually generating the other decoded characters. If the substring is not a UTF-8 encoding up to the skipth character (when err-char is #f), or if the substring decoding produces fewer than skip characters, the result is #f. If err-char is not #f, it is used to resolve decoding errors as in bytes->string/utf-8.

(bytes-utf-8-index

 

bstr

 

 

 

 

 

 [

skip

 

 

 

 

 

 

err-char

 

 

 

 

 

 

start

 

 

 

 

 

 

end])

 

 

exact-nonnegative-integer?

  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)

Returns the offset in bytes into bstr at which the skipth character’s encoding starts in the UTF-8 decoding of bstr’s substring from start to end (but without actually generating the other decoded characters). The result is relative to the start of bstr, not to start. If the substring is not a UTF-8 encoding up to the skipth character (when err-char is #f), or if the substring decoding produces fewer than skip characters, the result is #f. If err-char is not #f, it is used to resolve decoding errors as in bytes->string/utf-8.

3.4.4 Bytes to Bytes Encoding Conversion

(bytes-open-converter from-name to-name)  bytes-converter?

  from-name : string?

  to-name : string?

Produces a string converter to go from the encoding named by from-name to the encoding named by to-name. If the requested conversion pair is not available, #f is returned instead of a converter.

Certain encoding combinations are always available:

A newly opened byte converter is registered with the current custodian (see Custodians), so that the converter is closed when the custodian is shut down. A converter is not registered with a custodian (and does not need to be closed) if it is one of the guaranteed combinations not involving "" under Unix, or if it is any of the guaranteed combinations (including "") under Windows and Mac OS X.

In PLT’s software distributions for Windows, a suitable "iconv.dll" is included with "libmzschVERS.dll".

The set of available encodings and combinations varies by platform, depending on the iconv library that is installed. Under Windows, "iconv.dll" or "libiconv.dll" must be in the same directory as "libmzschVERS.dll" (where VERS is a version number), in the user’s path, in the system directory, or in the current executable’s directory at run time, and the DLL must either supply _errno or link to "msvcrt.dll" for _errno; otherwise, only the guaranteed combinations are available.

(bytes-close-converter converter)  void

  converter : bytes-converter?

Closes the given converter, so that it can no longer be used with bytes-convert or bytes-convert-end.

(bytes-convert

 

converter

 

 

 

src-bstr

 

 

 [

src-start-pos

 

 

 

src-end-pos

 

 

 

dest-bstr

 

 

 

dest-start-pos

 

 

 

dest-end-pos])

 

 

 

(or/c bytes? nonnegative-exact-integer?)

nonnegative-exact-integer?

(one-of 'complete 'continues 'aborts 'error)

  converter : bytes-converter?

  src-bstr : bytes?

  src-start-pos : nonnegative-exact-integer? = 0

  

src-end-pos

 

:

 

nonnegative-exact-integer?

 

 

 

=

 

(bytes-length src-bstr)

  dest-bstr : (or/c bytes? false/c) = #f

  dest-start-pos : nonnegative-exact-integer? = 0

  

dest-end-pos

 

:

 

(or/c nonnegative-exact-integer? false/c)

 

 

 

=

 

(and dest-bstr

     (bytes-length dest-bstr))

Converts the bytes from src-start-pos to src-end-pos in src-bstr.

If dest-bstr is not #f, the converted byte are written into dest-bstr from dest-start-pos to dest-end-pos. If dest-bstr is #f, then a newly allocated byte string holds the conversion results, and if dest-end-pos is not #f, the size of the result byte string is no more than (- dest-end-pos dest-start-pos).

The result of bytes-convert is three values:

Applying a converter accumulates state in the converter (even when the third result of bytes-convert is 'complete). This state can affect both further processing of input and further generation of output, but only for conversions that involve “shift sequences” to change modes within a stream. To terminate an input sequence and reset the converter, use bytes-convert-end.

(bytes-convert-end

 

converter

 

 

 [

dest-bstr

 

 

 

dest-start-pos

 

 

 

dest-end-pos])

 

 

 

(or/c bytes? nonnegative-exact-integer?)

(one-of 'complete 'continues)

  converter : bytes-converter?

  dest-bstr : (or/c bytes? false/c) = #f

  dest-start-pos : nonnegative-exact-integer? = 0

  

dest-end-pos

 

:

 

(or/c nonnegative-exact-integer? false/c)

 

 

 

=

 

(and dest-bstr

     (bytes-length dest-bstr))

Like bytes-convert, but instead of converting bytes, this procedure generates an ending sequence for the conversion (sometimes called a “shift sequence”), if any. Few encodings use shift sequences, so this function will succeed with no output for most encodings. In any case, successful output of a (possibly empty) shift sequence resets the converter to its initial state.

The result of bytes-convert-end is two values:

(bytes-converter? v)  boolean?

  v : any/c

Returns #t if v is a byte converter produced by bytes-open-converter, #f otherwise.

(locale-string-encoding)  any

Returns a string for the current locale’s encoding (i.e., the encoding normally identified by ""). See also system-language+country.