Changes between Version 1 and Version 2 of NumericVectorsCowan


Ignore:
Timestamp:
11/22/12 11:31:07 (5 years ago)
Author:
cowan
Comment:

--

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 numeric-only 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. 
     1This is a proposal for a WG2 numeric vector API.  The conceit is that we provide what appear to be a set of specialized numeric-only 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. 
    22 
    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 one can be easily inlined by even a very dumb compiler, providing high efficiency. 
     3This design subsumes [http://srfi.schemers.org/srfi-4/srfi-4.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. 
    44 
    5 == Numeric types == 
     5== Representation types == 
    66 
    77A <type> consists of a <principal type> followed by an <endianism>. 
     
    4747  Big-endian (for float and complex, IEEE format) 
    4848 
    49 Endianism is not applicable to the `u8` and `s8` types. 
     49Endianism is not applicable to the `u8` and `s8` types.  Thus there are 3 * 14 - 4, or 38, representation types altogether. 
    5050 
    5151 
     
    5454`(make-<type>vector `''k''` ` [ ''fill'' ]`)` 
    5555 
    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 implementation-defined. 
     56Returns 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 implementation-defined.  An error is signaled if ''fill'' cannot be accurately converted to `<type>`. 
    5757 
    5858`(<type>vector ` ''v'' ... `)` 
    5959 
    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>. 
     60Returns 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>`. 
    6161 
    6262== Selectors == 
     
    6666Returns the length of ''bytevector'' divided by ''b'', where ''b'' is the number of bytes specified by <type>, and rounded toward zero. 
    6767 
     68`(<type>vector-ref` ''bytevector k''`)` 
     69 
     70Returns 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 
    6872`(bytevector-<type>-ref` ''bytevector k''`)` 
    6973 
    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. 
     74Returns 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. 
    7175 
    72 `(<type>vector-ref` ''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. 
     76Since `bytevector-u8-ref` is defined in the small language, it is excluded here. 
    7577 
    7678== Mutators == 
    7779 
    78 (`bytevector-<type>-set!` ''bytevector k v''`)` 
     80`(<type>vector-set!` ''bytevector k v''`)` 
    7981 
    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. 
     82Converts ''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>`. 
    8183 
    82 (`<type>vector-set!` ''bytevector k v''`)` 
     84`(bytevector-<type>-set!` ''bytevector k v''`)` 
    8385 
    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. 
     86Converts ''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 
     88Since `bytevector-u8-set!` is defined in the small language, it is excluded here. 
    8589 
    8690== Conversions == 
    8791 
    88 (`vector-><type>vector `''vector''`)` 
     92`(vector-><type>vector `''vector''`)` 
    8993 
    90 Returns a vector with the same elements as ''<type>vector''. 
     94`(list-><type>vector `''vector''`)` 
    9195 
    92 (`<type>vector->vector `''<type>vector''`)` 
     96Returns 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>`. 
    9397 
    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''`)` 
    9599 
     100`(<type>vector->list `''bytevector''`)` 
    96101 
    97 === Equality, map, for-each, fold, unfold === 
     102Returns a vector or list with the same elements as ''bytevector'' viewed as a <type>vector. 
    98103 
    99 '''TBD''' 
     104=== Copying, appending, and filling === 
     105 
     106`(<type>vector-copy `[ [ ''start'' ] ''end'' ] `)` 
     107 
     108These procedures are equivalent to calling `bytevector-copy` with the ''start'' and ''end'' arguments multiplied by ''b'', where ''b'' is the number of bytes specified by <type>. 
     109 
     110`(<type>vector-copy! `''to at from'' [ [ ''start'' ] ''end'' ] `)` 
     111 
     112These procedures are equivalent to calling `bytevector-copy!` with the ''start'', ''end'', and ''at'' arguments multiplied by ''b'', where ''b'' is the number of bytes specified by <type>. 
     113 
     114There are no `<type>vector-append` procedures, as `bytevector-append` is sufficient. 
     115 
     116`(<type>vector-fill! `''bytevector fill'' [ [ ''start'' ] ''end'' ] `)` 
     117 
     118Stores ''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 
     122See NumericVectorsAdvancedCowan.