bytevectors.texi (6056B)
1 @c -*-texinfo-*- 2 @setfilename ../src/bytevectors 3 4 @node Bytevectors, Errors, Vectors, Top 5 @comment node-name, next, previous, up 6 7 @chapter Bytevectors 8 @cindex Bytevectors 9 10 A bytevector is an object that contains a sequence of bytes, that is, 11 exact integers between 0 and 255 inclusive. A bytevector has a length 12 that is fixed at creation time, and as many bytes, indexed from 13 @code{0} to @code{length-1}. Compared to vectors, bytevectors use 14 less size for each element. 15 16 Bytevectors may be mutable or immutable. If an attempt is made to 17 mutate an immutable bytevector, an error is signaled. Two immutable 18 bytevectors are ``eq?'' iff they are ``equal?''. Two mutable 19 bytevectors are ``eq?'' if they were created by the same constructor 20 call. Two mutable bytevectors are ``equal?'' iff they have the same 21 length and have ``equal?'' bytes in each position. There is only one 22 empty bytevector (that is, a bytevector of length 0) and that 23 bytevector is immutable. The bytevector type is encapsulated. 24 25 SOURCE NOTE: The report doesn't currently include bytevectors. They 26 are taken from r7rs scheme. 27 28 @deffn Applicative bytevector? (bytevector? . obje) 29 The primitive type predicate for type bytevector. @code{bytevector?} 30 returns true iff all the objects in @code{objects} are of type 31 bytevector. 32 @end deffn 33 34 @deffn Applicative immutable-bytevector? (immutable-bytevector? objects) 35 @deffnx Applicative mutable-bytevector? (mutable-bytevector? objects) 36 The primitive type predicates for types immutable bytevector and 37 mutable bytevector. These return true iff all the objects in 38 @code{objects} are of type immutable bytevector or mutable bytevector 39 respectively. 40 @end deffn 41 42 @deffn Applicative make-bytevector (make-bytevector k [u8]) 43 Applicative @code{make-bytevector} constructs and returns a new 44 mutable bytevector of length @code{k}. If @code{u8} is specified, 45 then all bytes in the returned bytevector are @code{obj}, otherwise 46 the content of the bytevector is unspecified. 47 @end deffn 48 49 @deffn Applicative bytevector-length (bytevector-length bytevector) 50 Applicative @code{bytevector-length} returns the length of 51 @code{bytevector}. 52 @end deffn 53 54 @deffn Applicative bytevector-ref (bytevector-ref bytevector k) 55 Applicative @code{bytevector-ref} returns the byte of 56 @code{bytevector} at position @code{k}. If @code{k} is out of bounds 57 (i.e. less than @code{0} or greater or equal than 58 @code{(bytevector-length bytevector)}) an error is signaled. 59 @end deffn 60 61 @deffn Applicative bytevector-set! (bytevector-set! bytevector k u8) 62 Applicative @code{bytevector-set!} replaces the byte with index 63 @code{k} in @code{bytevector} with byte @code{u8}. If @code{k} is out 64 of bounds, or @code{bytevector} is immutable, an error is 65 signaled. The result returned by @code{bytevector-set!} is inert. 66 @end deffn 67 68 @deffn Applicative bytevector (bytevector . u8s) 69 Applicative @code{bytevector} contructs and return a new mutable 70 bytevector composed of the byte arguments. 71 @end deffn 72 73 @deffn Applicative bytevector->list (bytevector->list bytevector) 74 @deffnx Applicative list->bytevector (list->bytevector u8s) 75 These applicatives convert between bytevectors and lists of bytes. If 76 the list passed to @code{list->bytevector} contains an object that 77 isn't a byte, an error is signaled. The objects returned by these 78 applicatives are always mutable. 79 @end deffn 80 81 @deffn Applicative bytevector-copy (bytevector-copy bytevector) 82 Applicative @code{bytevector-copy} constructs and returns a new 83 mutable bytevector with the same length and bytes as 84 @code{bytevector}. 85 @end deffn 86 87 @deffn Applicative bytevector->vector (bytevector->vector bytevector) 88 @deffnx Applicative vector->bytevector (vector->bytevector vector) 89 These applicatives convert between bytevectors and vectors. If a 90 vector containing objects other than bytes (exact integers between 0 91 and 255 inclusive) is passed to @code{vector->bytevector}, an error is 92 signaled. The objects returned by these applicatives are always 93 mutable. 94 @end deffn 95 96 @deffn Applicative bytevector-copy! (bytevector-copy! bytevector1 bytevector2) 97 bytevector2 should have a length greater than or equal to that of 98 bytevector1. 99 100 Copies the bytes in bytevector1 to the corresponding positions in 101 bytevector2. If bytevector2 is immutable, an error is signaled. The 102 result returned by @code{bytevector-copy!} is inert. 103 @end deffn 104 105 @deffn Applicative bytevector-copy-partial (bytevector-copy-partial bytevector k1 k2) 106 Both @code{k1} & @code{k2} should be valid indexes in 107 @code{bytevector}. Also it should be the case that @code{k1 <= k2}. 108 109 Applicative @code{bytevector-copy-partial} constructs and returns a 110 new mutable bytevector with length @code{k2 - k1}, with the bytes from 111 @code{bytevector}, starting at index @code{k1} (inclusive) and ending 112 at index @code{k2} (exclusive). 113 @end deffn 114 115 @deffn Applicative bytevector-copy-partial! (bytevector-copy-partial! bytevector1 k1 k2 bytevector2 k3) 116 Both @code{k1} & @code{k2-1} should be valid indexes in 117 @code{bytevector1}. Also it should be the case that @code{k1 <= k2}. 118 Both @code{k3} & @code{k3 + (k2-k1) - 1} should be valid indexes in 119 @code{bytevector2}. 120 121 Applicative @code{bytevector-copy-partial!} copies bytes k1 122 (inclusive) through k2 (exclusive) from @code{bytevector1} to the 123 @code{k2-k1} positions in @code{bytevector2} starting at @code{k3}. 124 If @code{bytevector2} is an immutable bytevector, an error is 125 signaled. The result returned by @code{bytevector-copy-partial!} is 126 inert. 127 @end deffn 128 129 @deffn Applicative bytevector-fill! (bytevector-fill! bytevector u8) 130 Applicative @code{bytevector-fill!} replaces all the bytes in 131 @code{bytevector} with byte @code{u8}. If @code{bytevector} is an 132 immutable bytevector, an error is signaled. The result 133 returned by @code{bytevector-fill!} is inert. 134 @end deffn 135 136 @deffn Applicative bytevector->immutable-bytevector (bytevector->immutable-bytevector bytevector) 137 Applicative @code{bytevector->immutable-bytevector} constructs and 138 returns a new immutable bytevector with the same length and bytes as 139 @code{bytevector}. 140 @end deffn