bytevectors.texinfo (5133B)
1 @node Bytevectors 2 @section Bytevectors 3 4 @define{Bytevectors} represent blocks of binary data. They are fixed-length 5 sequences of bytes, where a @define{byte} is an exact integer in the range 6 from 0 to 255 inclusive. A bytevector is typically more space-efficient 7 than a vector containing the same values. 8 9 @cindex valid indexes 10 11 The @define{length} of a bytevector is the number of elements that it 12 contains. This number is a non-negative integer that is fixed when 13 the bytevector is created. The @define{valid indexes} of a bytevector are 14 the exact non-negative integers less than the length of the bytevector, 15 starting at index zero as with vectors. 16 17 Bytevectors are written using the notation @code{#u8(}@var{byte} 18 @dots{}@code{)}. For example, a bytevector of length 3 containing the 19 byte 0 in element 0, the byte 10 in element 1, and the byte 5 in element 20 2 can be written as follows: 21 22 @lisp 23 #u8(0 10 5) 24 @end lisp 25 26 Bytevector constants are self-evaluating, so they do not need to be 27 quoted in programs. 28 29 @deffn procedure bytevector? obj 30 31 Returns @code{#t} if @var{obj} is a bytevector. Otherwise, @code{#f} is 32 returned. 33 34 @end deffn 35 36 @deffn procedure make-bytevector k 37 @deffnx procedure make-bytevector k byte 38 39 The @code{make-bytevector} procedure returns a newly allocated 40 bytevector of length @var{k}. If @var{byte} is given, then all elements 41 of the bytevector are initialized to @var{byte}, otherwise the contents 42 of each element are unspecified. 43 44 @lisp 45 (make-bytevector 2 12) @result{} #u8(12 12) 46 @end lisp 47 48 @end deffn 49 50 @deffn procedure bytevector byte@dots{} 51 52 Returns a newly allocated bytevector containing its arguments. 53 54 @lisp 55 (bytevector 1 3 5 1 3 5) @result{} #u8(1 3 5 1 3 5) 56 (bytevector) @result{} #u8() 57 @end lisp 58 59 @end deffn 60 61 @deffn procedure bytevector-length bytevector 62 63 Returns the length of @var{bytevector} in bytes as an exact integer. 64 65 @end deffn 66 67 @deffn procedure bytevector-u8-ref bytevector k 68 69 It is an error if @var{k} is not a valid index of @var{bytevector}. 70 71 Returns the @var{k}th byte of @var{bytevector}. 72 73 @lisp 74 (bytevector-u8-ref '#u8(1 1 2 3 5 8 13 21) 75 5) 76 @result{} 8 77 @end lisp 78 79 @end deffn 80 81 @deffn procedure bytevector-u8-set! bytevector k byte 82 83 It is an error if @var{k} is not a valid index of @var{bytevector}. 84 85 Stores @var{byte} as the @var{k}th byte of @var{bytevector}. 86 87 @lisp 88 (let ((bv (bytevector 1 2 3 4))) 89 (bytevector-u8-set! bv 1 3) 90 bv) 91 @result{} #u8(1 3 3 4) 92 @end lisp 93 94 @end deffn 95 96 @deffn procedure bytevector-copy bytevector 97 @deffnx procedure bytevector-copy bytevector start 98 @deffnx procedure bytevector-copy bytevector start end 99 100 Returns a newly allocated bytevector containing the bytes in 101 @var{bytevector} between @var{start} and @var{end}. 102 103 @lisp 104 (define a #u8(1 2 3 4 5)) 105 (bytevector-copy a 2 4)) @result{} #u8(3 4) 106 @end lisp 107 108 @end deffn 109 110 @deffn procedure bytevector-copy! to at from 111 @deffnx procedure bytevector-copy! to at from start 112 @deffnx procedure bytevector-copy! to at from start end 113 114 It is an error if @var{at} is less than zero or greater than the length 115 of @var{to}. It is also an error if 116 @code{(- (bytevector-length }@var{to}@code{)} @var{at}@code{)} is less 117 than @code{(- }@var{end} @var{start}@code{)}. 118 119 Copies the bytes of bytevector @var{from} between @var{start} and 120 @var{end} to bytevector @var{to}, starting at @var{at}. The order in 121 which bytes are copied is unspecified, except that if the source and 122 destination overlap, copying takes place as if the source is first 123 copied into a temporary bytevector and then into the destination. 124 This can be achieved without allocating storage by making sure to 125 copy in the correct direction in such circumstances. 126 127 @lisp 128 (define a (bytevector 1 2 3 4 5)) 129 (define b (bytevector 10 20 30 40 50)) 130 (bytevector-copy! b 1 a 0 2) 131 b @result{} #u8(10 1 2 40 50) 132 @end lisp 133 134 Note: This procedure appears in @rsixrs{}, but places the source 135 before the destination, contrary to other such procedures in Scheme. 136 137 @end deffn 138 139 @deffn procedure bytevector-append bytevector@dots{} 140 141 Returns a newly allocated bytevector whose elements are the concatenation of the 142 elements in the given @var{bytevector}s. 143 144 @lisp 145 (bytevector-append #u8(0 1 2) #u8(3 4 5)) 146 @result{} #u8(0 1 2 3 4 5) 147 @end lisp 148 149 @end deffn 150 151 @deffn procedure utf8->string bytevector 152 @deffnx procedure utf8->string bytevector start 153 @deffnx procedure utf8->string bytevector start end 154 @deffnx procedure string->utf8 string 155 @deffnx procedure string->utf8 string start 156 @deffnx procedure string->utf8 string start end 157 158 It is an error for @var{bytevector} to contain invalid UTF-8 byte 159 sequences. 160 161 These procedures translate between strings and bytevectors that encode 162 those strings using the UTF-8 encoding. The @code{utf8->string} 163 procedure decodes the bytes of a bytevector between @var{start} and 164 @var{end} and returns the corresponding string; the @code{string->utf8} 165 procedure encodes the characters of a string between @var{start} 166 and @var{end} and returns the corresponding bytevector. 167 168 @lisp 169 (utf8->string #u8(#x41)) @result{} "A" 170 (string->utf8 "@theultimate{}") @result{} #u8(#xCE #xBB) 171 @end lisp 172 173 @end deffn