Changes between Version 1 and Version 2 of NumericVectorsCowan
 Timestamp:
 11/22/12 11:31:07 (5 years ago)
Legend:
 Unmodified
 Added
 Removed
 Modified

NumericVectorsCowan
v1 v2 1 This is a proposal for a WG2 numeric vector API. The conceit is that we provide what appear to be a set of specialized numericonly vectors a la SRFI 4, but there really is only one underlying type, the bytevector. This makes it easy to see a single byte sequence in a variety of ways, not just as homogeneous vectors.1 This is a proposal for a WG2 numeric vector API. The conceit is that we provide what appear to be a set of specialized numericonly vectors, but there really is only one underlying type, the bytevector. This makes it easy to see a single byte sequence in a variety of ways, not just as a homogeneous vector. 2 2 3 This design differs from related designs in that everything is a separate procedure with minimal arguments; this makes for a ''lot'' of procedures, but each onecan be easily inlined by even a very dumb compiler, providing high efficiency.3 This design subsumes [http://srfi.schemers.org/srfi4/srfi4.html SRFI 4] with the exception of its type predicates. It differs from related designs such as SRFI 63, SRFI 66, and R6RS in that each procedure listed below actually represents many procedures, one for each defined representation type. This makes for a ''lot'' of procedures, but many of them can be easily inlined by even a very dumb compiler, providing high efficiency. 4 4 5 == Numerictypes ==5 == Representation types == 6 6 7 7 A <type> consists of a <principal type> followed by an <endianism>. … … 47 47 Bigendian (for float and complex, IEEE format) 48 48 49 Endianism is not applicable to the `u8` and `s8` types. 49 Endianism is not applicable to the `u8` and `s8` types. Thus there are 3 * 14  4, or 38, representation types altogether. 50 50 51 51 … … 54 54 `(make<type>vector `''k''` ` [ ''fill'' ]`)` 55 55 56 Returns a newly allocated bytevector of length ''k * b'', where ''b'' is the number of bytes consumed by <type>. ''Fill'' is converted to a binary value according to <type> and used to fill the bytevector; the default is implementationdefined.56 Returns a newly allocated bytevector of length ''k * b'', where ''b'' is the number of bytes specified by <type>. ''Fill'' is converted to a binary value according to <type> and used to fill the bytevector; the default is implementationdefined. An error is signaled if ''fill'' cannot be accurately converted to `<type>`. 57 57 58 58 `(<type>vector ` ''v'' ... `)` 59 59 60 Returns a newly allocated bytevector of length ''k * b'', where ''k'' is the number of arguments to the procedure and ''b'' is the number of bytes specified by <type>. It is filled with the binary values resulting from encoding the ''v'' values according to <type>.60 Returns a newly allocated bytevector of length ''k * b'', where ''k'' is the number of arguments to the procedure and ''b'' is the number of bytes specified by <type>. It is filled with the binary values resulting from encoding the arguments according to <type>. An error is signaled if an argument cannot be accurately converted to `<type>`. 61 61 62 62 == Selectors == … … 66 66 Returns the length of ''bytevector'' divided by ''b'', where ''b'' is the number of bytes specified by <type>, and rounded toward zero. 67 67 68 `(<type>vectorref` ''bytevector k''`)` 69 70 Returns a Scheme number corresponding to the binary value encoded according to <type> beginning at offset ''k * b'' in ''bytevector'', where ''b'' is the number of bytes specified by <type>. This procedure treats ''bytevector'' as a uniformly typed vector. 71 68 72 `(bytevector<type>ref` ''bytevector k''`)` 69 73 70 Returns a Scheme number corresponding to the binary value encoded according to ''type''beginning at offset ''k'' in ''bytevector''. This procedure treats ''bytevector'' as potentially containing more than one type.74 Returns a Scheme number corresponding to the binary value encoded according to <type> beginning at offset ''k'' in ''bytevector''. This procedure treats ''bytevector'' as potentially containing more than one type. 71 75 72 `(<type>vectorref` ''bytevector k''`)` 73 74 Returns a Scheme number corresponding to the binary value encoded according to ''type'' beginning at offset ''k * b'' in ''bytevector'', where ''b'' is the size of the binary value in bytes. This procedure treats ''bytevector'' as a uniformly typed vector. 76 Since `bytevectoru8ref` is defined in the small language, it is excluded here. 75 77 76 78 == Mutators == 77 79 78 (`bytevector<type>set!` ''bytevector k v''`)`80 `(<type>vectorset!` ''bytevector k v''`)` 79 81 80 Converts ''v'' to a binary value encoded according to ''type'' and places it into ''bytevector'' beginning at offset ''k''. This procedure treats ''bytevector'' as potentially containing more than one type.82 Converts ''v'' to a binary value encoded according to <type> and places it into ''bytevector'' beginning at offset ''k * b'', where ''b'' is the number of bytes specified by <type>. This procedure treats ''bytevector'' as a uniformly typed vector. An error is signaled if ''v'' cannot be accurately converted to `<type>`. 81 83 82 (`<type>vectorset!` ''bytevector k v''`)`84 `(bytevector<type>set!` ''bytevector k v''`)` 83 85 84 Converts ''v'' to a binary value encoded according to ''type'' and places it into ''bytevector'' beginning at offset ''k * b'', where ''b'' is the size of the binary value in bytes. This procedure treats ''bytevector'' as a uniformly typed vector. 86 Converts ''v'' to a binary value encoded according to <type> and places it into ''bytevector'' beginning at offset ''k''. This procedure treats ''bytevector'' as potentially containing more than one type. An error is signaled if ''v'' cannot be accurately converted to `<type>`. 87 88 Since `bytevectoru8set!` is defined in the small language, it is excluded here. 85 89 86 90 == Conversions == 87 91 88 (`vector><type>vector `''vector''`)`92 `(vector><type>vector `''vector''`)` 89 93 90 Returns a vector with the same elements as ''<type>vector''. 94 `(list><type>vector `''vector''`)` 91 95 92 (`<type>vector>vector `''<type>vector''`)` 96 Returns a newly allocated bytevector which, when viewed as a <type>vector, has the same elements as ''vector'' or ''list''. An error is signaled if an element of ''vector'' or ''list'' cannot be accurately converted to `<type>`. 93 97 94 Returns a <type>vector with the same elements as ''vector''. It is an error if an element cannot be accurately converted to `<type>`. 98 `(<type>vector>vector `''bytevector''`)` 95 99 100 `(<type>vector>list `''bytevector''`)` 96 101 97 === Equality, map, foreach, fold, unfold === 102 Returns a vector or list with the same elements as ''bytevector'' viewed as a <type>vector. 98 103 99 '''TBD''' 104 === Copying, appending, and filling === 105 106 `(<type>vectorcopy `[ [ ''start'' ] ''end'' ] `)` 107 108 These procedures are equivalent to calling `bytevectorcopy` with the ''start'' and ''end'' arguments multiplied by ''b'', where ''b'' is the number of bytes specified by <type>. 109 110 `(<type>vectorcopy! `''to at from'' [ [ ''start'' ] ''end'' ] `)` 111 112 These procedures are equivalent to calling `bytevectorcopy!` with the ''start'', ''end'', and ''at'' arguments multiplied by ''b'', where ''b'' is the number of bytes specified by <type>. 113 114 There are no `<type>vectorappend` procedures, as `bytevectorappend` is sufficient. 115 116 `(<type>vectorfill! `''bytevector fill'' [ [ ''start'' ] ''end'' ] `)` 117 118 Stores ''fill'' in the elements of ''bytevector'' viewed as a <type>vector from ''start'' to ''end''. An error is signaled if ''fill'' cannot be accurately converted to `<type>`. 119 120 == More procedures == 121 122 See NumericVectorsAdvancedCowan.