doco array mapping

doco array mapping

[Kevin Ryde]

I had a bit of nitpick at the array mapping doco a while ago.  I'm
looking to put together a proposed revision.

array-map! currently seems to allow no source arrays at all.  The docs
don't really say anything about that.  Should it be a documented
feature?

array-for-each doesn't say what happens if its arrays have different
index ranges.  I guess the current code iterates over the first array
and expects the rest to cover those indices.  Is there something that
can or should be said about this?


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: doco array mapping

[Kevin Ryde]

New words to propose for the array mapping chapter.  The main idea is
to make the formal parameters talked about in the text match what's in
the prototypes.  I found "lra" and stuff a bit confusing, until the
penny dropped.

I also replaced the examples for array-index-map! with something a
little more realistic.  Not a lot more, but a little at least :-).
Suggestions for something simple but illustrative would be welcome.


Array Mapping
-------------

 - Scheme Procedure: array-map! dst proc src1 ... srcN
 - Scheme Procedure: array-map-in-order! dst proc src1 ... srcN
 - C Function: scm_array_map_x (dst, proc, srclist)
     Set each element of the DST array to values obtained from calls to
     PROC.  The value returned is unspecified.

     Each call is `(PROC ELEM1 ... ELEMN)', where each ELEM is from the
     corresponding SRC array at the DST index.  `array-map-in-order!'
     makes the calls in row-major order, `array-map!' makes them in an
     unspecified order.

     The SRC arrays must have the same number of dimensions as DST, and
     must have a range for each dimension which covers the range in
     DST.  This ensures all DST indices are valid in each SRC.

 - Scheme Procedure: array-for-each proc src1 ... srcN
 - C Function: scm_array_for_each (proc, src1, srclist)
     Apply PROC to each tuple of elements of SRC1 ...  SRCN, in
     row-major order.  The value returned is unspecified.

 - Scheme Procedure: array-index-map! dst proc
 - C Function: scm_array_index_map_x (dst, proc)
     Set each element of the DST array to values returned by calls to
     PROC.  The value returned is unspecified.

     To generate each DST element, a call `(PROC I1 ... IN)' is made,
     where each I1...IN is the destination index, one parameter for
     each dimension.  The order in which the calls are made is
     unspecified.

     For example, to create a 4x4 matrix representing a cyclic group,

              / 0 1 2 3 \
              | 1 2 3 0 |
              | 2 3 0 1 |
              \ 3 0 1 2 /

          (define a (make-array #f 4 4))
          (array-index-map! a (lambda (i j)
                                (modulo (+ i j) 4)))


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: doco array mapping

[Marius Vollmer]

Kevin Ryde <user42@zip.com.au> writes:

> New words to propose for the array mapping chapter.

Good ones.

-- 
GPG: D5D4E405 - 2F9B BCCC 8527 692A 04E3  331E FAF8 226A D5D4 E405


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: doco array mapping

[Kevin Ryde]

I applied this change.

What I wondered before about array-map! on no source arrays and about
what array-for-each does on different sized sources would be worth
clarifying, but they need some thought about what can or should be
supported.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel