►The Racket Reference
▼3 Datatypes
►3.4 Byte Strings
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
make-shared-bytes
shared-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
3.4.5 Additional Byte String Functions
bytes-append*
bytes-join
  top  ← prev  up  next → 

3.4 Byte Strings

+Bytes and Byte Strings in The Racket Guide introduces byte strings.

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, and they are interned in read-syntax mode.

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 Reading Strings for information on reading byte strings and Printing Strings for information on printing byte strings.

See also: immutable?.

3.4.1 Byte String Constructors, Selectors, and Mutators

procedure

(bytes? v) → boolean?

  v : any/c
Returns #t if v is a byte string, #f otherwise.

Examples:

> (bytes? #"Apple")

#t

> (bytes? "Apple")

#f

procedure

(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.

Example:

> (make-bytes 5 65)

#"AAAAA"

procedure

(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.

Example:

> (bytes 65 112 112 108 101)

#"Apple"

procedure

(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.

Examples:

> (bytes->immutable-bytes (bytes 65 65 65))

#"AAA"

> (define b (bytes->immutable-bytes (make-bytes 5 65)))
> (bytes->immutable-bytes b)

#"AAAAA"

> (eq? (bytes->immutable-bytes b) b)

#t

procedure

(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

procedure

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

  bstr : bytes?
Returns the length of bstr.

Example:

> (bytes-length #"Apple")

5

procedure

(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.

Example:

> (bytes-ref #"Apple" 0)

65

procedure

(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"

procedure

(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 or equal to the length of bstr, and end must be greater than or equal to start, otherwise the exn:fail:contract exception is raised.

Examples:

> (subbytes #"Apple" 1 3)

#"pp"

> (subbytes #"Apple" 1)

#"pple"

procedure

(bytes-copy bstr) → bytes?

  bstr : bytes?
Returns (subbytes str 0).

procedure

(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"

procedure

(bytes-fill! dest b) → void?

  dest : (and/c bytes? (not/c immutable?))
  b : byte?
Changes dest so that every position in the bytes is filled with b.

Examples:

> (define s (bytes 65 112 112 108 101))
> (bytes-fill! s 113)
> s

#"qqqqq"

procedure

(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.

Example:

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

#"AppleBanana"

procedure

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

  bstr : bytes?
Returns a new list of bytes corresponding to the content of bstr. That is, the length of the list is (bytes-length bstr), and the sequence of bytes in bstr is the same sequence in the result list.

Example:

> (bytes->list #"Apple")

'(65 112 112 108 101)

procedure

(list->bytes lst) → bytes?

  lst : (listof byte?)
Returns a new mutable byte string whose content is the list of bytes in lst. That is, the length of the byte string is (length lst), and the sequence of bytes in lst is the same sequence in the result byte string.

Example:

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

#"Apple"

procedure

(make-shared-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. For communication among places, the new byte string is allocated in the shared memory space.

Example:

> (make-shared-bytes 5 65)

#"AAAAA"

procedure

(shared-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. For communication among places, the new byte string is allocated in the shared memory space.

Example:

> (shared-bytes 65 112 112 108 101)

#"Apple"

3.4.2 Byte String Comparisons

procedure

(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

procedure

(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

procedure

(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

procedure

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

  bstr : bytes?
  err-char : (or/c #f 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 rule 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.

Example:

> (bytes->string/utf-8 (bytes 195 167 195 176 195 182 194 163))

"çðö£"

procedure

(bytes->string/locale bstr    
  [err-char    
  start    
  end]) → string?
  bstr : bytes?
  err-char : (or/c #f 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.

procedure

(bytes->string/latin-1 bstr    
  [err-char    
  start    
  end]) → string?
  bstr : bytes?
  err-char : (or/c #f 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. The err-char argument is ignored, but present for consistency with the other operations.

Example:

> (bytes->string/latin-1 (bytes 254 211 209 165))

"þÓÑ¥"

procedure

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

  str : string?
  err-byte : (or/c #f 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.

Examples:

> (define b
    (bytes->string/utf-8
     (bytes 195 167 195 176 195 182 194 163)))
> (string->bytes/utf-8 b)

#"\303\247\303\260\303\266\302\243"

> (bytes->string/utf-8 (string->bytes/utf-8 b))

"çðö£"

procedure

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

  str : string?
  err-byte : (or/c #f 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.

procedure

(string->bytes/latin-1 str    
  [err-byte    
  start    
  end]) → bytes?
  str : string?
  err-byte : (or/c #f 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. 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.

Examples:

> (define b
    (bytes->string/latin-1 (bytes 254 211 209 165)))
> (string->bytes/latin-1 b)

#"\376\323\321\245"

> (bytes->string/latin-1 (string->bytes/latin-1 b))

"þÓÑ¥"

procedure

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

  str : string?
  start : exact-nonnegative-integer? = 0
  end : exact-nonnegative-integer? = (string-length 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.

Examples:

> (string-utf-8-length
    (bytes->string/utf-8 (bytes 195 167 195 176 195 182 194 163)))

8

> (string-utf-8-length "hello")

5

procedure

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

 → exact-nonnegative-integer?
  bstr : bytes?
  err-char : (or/c #f 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.

Examples:

> (bytes-utf-8-length (bytes 195 167 195 176 195 182 194 163))

4

> (bytes-utf-8-length (make-bytes 5 65))

5

procedure

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

  bstr : bytes?
  skip : exact-nonnegative-integer? = 0
  err-char : (or/c #f 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.

Examples:

> (bytes-utf-8-ref (bytes 195 167 195 176 195 182 194 163) 0)

#\ç

> (bytes-utf-8-ref (bytes 195 167 195 176 195 182 194 163) 1)

#\ð

> (bytes-utf-8-ref (bytes 195 167 195 176 195 182 194 163) 2)

#\ö

> (bytes-utf-8-ref (bytes 65 66 67 68) 0)

#\A

> (bytes-utf-8-ref (bytes 65 66 67 68) 1)

#\B

> (bytes-utf-8-ref (bytes 65 66 67 68) 2)

#\C

procedure

(bytes-utf-8-index bstr    
  [skip    
  err-char    
  start    
  end]) → exact-nonnegative-integer?
  bstr : bytes?
  skip : exact-nonnegative-integer? = 0
  err-char : (or/c #f 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.

Examples:

> (bytes-utf-8-index (bytes 195 167 195 176 195 182 194 163) 0)

0

> (bytes-utf-8-index (bytes 195 167 195 176 195 182 194 163) 1)

2

> (bytes-utf-8-index (bytes 195 167 195 176 195 182 194 163) 2)

4

> (bytes-utf-8-index (bytes 65 66 67 68) 0)

0

> (bytes-utf-8-index (bytes 65 66 67 68) 1)

1

> (bytes-utf-8-index (bytes 65 66 67 68) 2)

2

3.4.4 Bytes to Bytes Encoding Conversion

procedure

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

  from-name : string?
  to-name : string?
Produces a byte 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 "" on Unix, or if it is any of the guaranteed combinations (including "") on Windows and Mac OS X.

In the Racket 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; the from-name and to-name arguments are passed on to iconv_open. On 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.

Use bytes-convert with the result to convert byte strings.

procedure

(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.

procedure

(bytes-convert converter 
  src-bstr 
  [src-start-pos 
  src-end-pos 
  dest-bstr 
  dest-start-pos 
  dest-end-pos]) 
 → 
(or/c bytes? exact-nonnegative-integer?)
exact-nonnegative-integer?
(or/c 'complete 'continues 'aborts 'error)
  converter : bytes-converter?
  src-bstr : bytes?
  src-start-pos : exact-nonnegative-integer? = 0
  src-end-pos : exact-nonnegative-integer?
   = (bytes-length src-bstr)
  dest-bstr : (or/c bytes? #f) = #f
  dest-start-pos : exact-nonnegative-integer? = 0
  dest-end-pos : (or/c exact-nonnegative-integer? #f)
   = 
(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 bytes 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.

Examples:

> (define convert (bytes-open-converter "UTF-8" "UTF-16"))
> (bytes-convert convert (bytes 65 66 67 68))

#"\377\376A\0B\0C\0D\0"

4

'complete

> (bytes 195 167 195 176 195 182 194 163)

#"\303\247\303\260\303\266\302\243"

> (bytes-convert convert (bytes 195 167 195 176 195 182 194 163))

#"\347\0\360\0\366\0\243\0"

8

'complete

> (bytes-close-converter convert)

procedure

(bytes-convert-end converter 
  [dest-bstr 
  dest-start-pos 
  dest-end-pos]) 
 → 
(or/c bytes? exact-nonnegative-integer?)
(or/c 'complete 'continues)
  converter : bytes-converter?
  dest-bstr : (or/c bytes? #f) = #f
  dest-start-pos : exact-nonnegative-integer? = 0
  dest-end-pos : (or/c exact-nonnegative-integer? #f)
   = 
(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:

procedure

(bytes-converter? v) → boolean?

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

Examples:

> (bytes-converter? (bytes-open-converter "UTF-8" "UTF-16"))

#t

> (bytes-converter? (bytes-open-converter "whacky" "not likely"))

#f

> (define b (bytes-open-converter "UTF-8" "UTF-16"))
> (bytes-close-converter b)
> (bytes-converter? b)

#t

procedure

(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.

3.4.5 Additional Byte String Functions

 (require racket/bytes)
The bindings documented in this section are provided by the racket/bytes and racket libraries, but not racket/base.

procedure

(bytes-append* str ... strs) → bytes?

  str : bytes?
  strs : (listof bytes?)
Like bytes-append, but the last argument is used as a list of arguments for bytes-append, so (bytes-append* str ... strs) is the same as (apply bytes-append str ... strs). In other words, the relationship between bytes-append and bytes-append* is similar to the one between list and list*.

Examples:

> (bytes-append* #"a" #"b" '(#"c" #"d"))

#"abcd"

> (bytes-append* (cdr (append* (map (lambda (x) (list #", " x))
                                     '(#"Alpha" #"Beta" #"Gamma")))))

#"Alpha, Beta, Gamma"

procedure

(bytes-join strs sep) → bytes?

  strs : (listof bytes?)
  sep : bytes?
Appends the byte strings in strs, inserting sep between each pair of bytes in strs.

Example:

> (bytes-join '(#"one" #"two" #"three" #"four") #" potato ")

#"one potato two potato three potato four"

  top  ← prev  up  next →