r7rs-small-texinfo

R7RS-small Scheme converted to Texinfo.
git clone https://kaka.farm/~git/r7rs-small-texinfo
Log | Files | Refs | README | LICENSE

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