* more garbled documentation in uniform arrays
@ 2004-01-09 17:38 Rouben Rostamian
2004-01-17 14:48 ` Kevin Ryde
0 siblings, 1 reply; 4+ messages in thread
From: Rouben Rostamian @ 2004-01-09 17:38 UTC (permalink / raw)
Version: guile--1.6.4
Guile reference manual: both "info" and TeX formats:
In the section titled "Conventional Arrays"
(This is Section 19.6.1 in my printout)
Essentially all items listed in this section need a good overhaul.
For instance, in the description of array-set! we read:
(Cut-and-paste from the info document follows:)
- Scheme Procedure: array-set! v obj . args
- Scheme Procedure: uniform-array-set1! v obj args
- C Function: scm_array_set_x (v, obj, args)
Set the element at the `(index1, index2)' element in ARRAY to
NEW-VALUE. The value returned by array-set! is unspecified.
The terms used in the description bear no similarity to arguments given
in the prototype.
--
Rouben Rostamian
_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: more garbled documentation in uniform arrays
2004-01-09 17:38 Rouben Rostamian
@ 2004-01-17 14:48 ` Kevin Ryde
0 siblings, 0 replies; 4+ messages in thread
From: Kevin Ryde @ 2004-01-17 14:48 UTC (permalink / raw)
Cc: bug-guile
"Rouben Rostamian" <rostamian@umbc.edu> writes:
>
> Essentially all items listed in this section need a good overhaul.
Yep. Bit of polish below. The hairy functions like enclose-array are
still not super clear.
Conventional Arrays
-------------------
"Conventional arrays" are a collection of cells organized into an
arbitrary number of dimensions. Each cell can hold any kind of Scheme
value and can be accessed in constant time by supplying an index for
each dimension.
This contrasts with uniform arrays, which use memory more efficiently
but can hold data of only a single type. It contrasts also with lists
where inserting and deleting cells is more efficient, but more time is
usually required to access a particular cell.
A conventional array is displayed as `#' followed by the "rank"
(number of dimensions) followed by the cells, organized into dimensions
using parentheses. The nesting depth of the parentheses is equal to
the rank.
When an array is created, the number of dimensions and range of each
dimension must be specified, e.g., to create a 2x3 array with a
zero-based index:
(make-array 'ho 2 3) =>
#2((ho ho ho) (ho ho ho))
The range of each dimension can also be given explicitly, e.g.,
another way to create the same array:
(make-array 'ho '(0 1) '(0 2)) =>
#2((ho ho ho) (ho ho ho))
A conventional array with one dimension based at zero is identical to
a vector:
(make-array 'ho 3) =>
#(ho ho ho)
The following procedures can be used with conventional arrays (or
vectors). An argument shown as IDX... means one parameter for each
dimension in the array. Or a IDXLIST is a list of such values, one for
each dimension.
- Scheme Procedure: array? obj [prot]
- C Function: scm_array_p (obj, prot)
Return `#t' if the OBJ is an array, and `#f' if not.
The PROT argument is used with uniform arrays (*note Uniform
Arrays::). If given then the return is `#t' if OBJ is an array
and of that prototype.
- Scheme Procedure: make-array initial-value bound ...
Create and return an array that has as many dimensions as there are
BOUNDs and fill it with INITIAL-VALUE.
Each BOUND may be a positive non-zero integer N, in which case the
index for that dimension can range from 0 through N-1; or an
explicit index range specifier in the form `(LOWER UPPER)', where
both LOWER and UPPER are integers, possibly less than zero, and
possibly the same number (however, LOWER cannot be greater than
UPPER).
- Scheme Procedure: array-ref array idx ...
- Scheme Procedure: uniform-vector-ref array idx ...
- C Function: scm_uniform_vector_ref (array, idxlist)
Return the element at `(idx ...)' in ARRAY.
(define a (make-array 999 '(1 2) '(3 4)))
(array-ref a 2 4) => 999
- Scheme Procedure: array-in-bounds? array idx ...
- C Function: scm_array_in_bounds_p (array, idxlist)
Return `#t' if the given index would be acceptable to `array-ref'.
(define a (make-array #f '(1 2) '(3 4)))
(array-in-bounds? a 2 3) => #f
(array-in-bounds? a 0 0) => #f
- Scheme Procedure: array-set! array obj idx ...
- Scheme Procedure: uniform-array-set1! array obj idxlist
- C Function: scm_array_set_x (array, obj, idxlist)
Set the element at `(idx ...)' in ARRAY to OBJ. The return value
is unspecified.
(define a (make-array #f '(0 1) '(0 1)))
(array-set! a #t 1 1)
a => #2((#f #f) (#f #t))
- Scheme Procedure: make-shared-array oldarray mapfunc bound ...
- C Function: scm_make_shared_array (oldarray, mapfunc, boundlist)
`make-shared-array' can be used to create shared subarrays of other
arrays. The MAPPER is a function that translates coordinates in
the new array into coordinates in the old array. A MAPPER must be
linear, and its range must stay within the bounds of the old
array, but it can be otherwise arbitrary. A simple example:
(define fred (make-array #f 8 8))
(define freds-diagonal
(make-shared-array fred (lambda (i) (list i i)) 8))
(array-set! freds-diagonal 'foo 3)
(array-ref fred 3 3) => foo
(define freds-center
(make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
(array-ref freds-center 0 0) => foo
- Scheme Procedure: shared-array-increments array
- C Function: scm_shared_array_increments (array)
For each dimension, return the distance between elements in the
root vector.
- Scheme Procedure: shared-array-offset array
- C Function: scm_shared_array_offset (array)
Return the root vector index of the first element in the array.
- Scheme Procedure: shared-array-root array
- C Function: scm_shared_array_root (array)
Return the root vector of a shared array.
- Scheme Procedure: transpose-array array dim1 ...
- C Function: scm_transpose_array (array, dimlist)
Return an array sharing contents with ARRAY, but with dimensions
arranged in a different order. There must be one DIM argument for
each dimension of ARRAY. DIM1, DIM2, ... should be integers
between 0 and the rank of the array to be returned. Each integer
in that range must appear at least once in the argument list.
The values of DIM1, DIM2, ... correspond to dimensions in the
array to be returned, and their positions in the argument list to
dimensions of ARRAY. Several DIMs may have the same value, in
which case the returned array will have smaller rank than ARRAY.
(transpose-array '#2((a b) (c d)) 1 0) => #2((a c) (b d))
(transpose-array '#2((a b) (c d)) 0 0) => #1(a d)
(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) =>
#2((a 4) (b 5) (c 6))
- Scheme Procedure: enclose-array array dim1 ...
- C Function: scm_enclose_array (array, dimlist)
DIM1, DIM2 ... should be nonnegative integers less than the rank
of ARRAY. ENCLOSE-ARRAY returns an array resembling an array of
shared arrays. The dimensions of each shared array are the same
as the DIMth dimensions of the original array, the dimensions of
the outer array are the same as those of the original array that
did not match a DIM.
An enclosed array is not a general Scheme array. Its elements may
not be set using `array-set!'. Two references to the same element
of an enclosed array will be `equal?' but will not in general be
`eq?'. The value returned by ARRAY-PROTOTYPE when given an
enclosed array is unspecified.
For example,
(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1)
=>
#<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0)
=>
#<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
- Scheme Procedure: array-shape array
- Scheme Procedure: array-dimensions array
- C Function: scm_array_dimensions (array)
Return a list of the bounds for each dimenson of ARRAY.
`array-shape' gives `(LOWER UPPER)' for each dimension.
`array-dimensions' instead returns just UPPER+1 for dimensions
with a 0 lower bound. Both are suitable as input to `make-array'.
For example,
(define a (make-array 'foo '(-1 3) 5))
(array-shape a) => ((-1 3) (0 4))
(array-dimensions a) => ((-1 3) 5)
- Scheme Procedure: array-rank obj
- C Function: scm_array_rank (obj)
Return the number of dimensions of an array OBJ, or if OBJ is not
an array then return 0.
- Scheme Procedure: array->list array
- C Function: scm_array_to_list (array)
Return a list consisting of all the elements, in order, of ARRAY.
- Scheme Procedure: array-copy! src dst
- Scheme Procedure: array-copy-in-order! src dst
- C Function: scm_array_copy_x (src, dst)
Copy every element from vector or array SRC to the corresponding
element of DST. DST must have the same rank as SRC, and be at
least as large in each dimension. The return value is unspecified.
- Scheme Procedure: array-fill! array fill
- C Function: scm_array_fill_x (array, fill)
Store FILL in every element of ARRAY. The value returned is
unspecified.
- Scheme Procedure: array-equal? array1 array2 ...
Return `#t' if all arguments are arrays with the same shape, the
same type, and have corresponding elements which are either
`equal?' or `array-equal?'. This function differs from `equal?'
in that a one dimensional shared array may be ARRAY-EQUAL? but not
EQUAL? to a vector or uniform vector.
- Scheme Procedure: array-contents array [strict]
- C Function: scm_array_contents (array, strict)
If ARRAY may be "unrolled" into a one dimensional shared array
without changing their order (last subscript changing fastest),
then `array-contents' returns that shared array, otherwise it
returns `#f'. All arrays made by MAKE-ARRAY and
MAKE-UNIFORM-ARRAY may be unrolled, some arrays made by
MAKE-SHARED-ARRAY may not be.
If the optional argument STRICT is provided, a shared array will
be returned only if its elements are stored internally contiguous
in memory.
_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: more garbled documentation in uniform arrays
@ 2004-01-17 15:48 Rouben Rostamian
2004-01-23 0:15 ` Kevin Ryde
0 siblings, 1 reply; 4+ messages in thread
From: Rouben Rostamian @ 2004-01-17 15:48 UTC (permalink / raw)
Cc: bug-guile
Kevin Ryde <user42@zip.com.au> wrote:
> "Rouben Rostamian" <rostamian@umbc.edu> writes:
> >
> > Essentially all items listed in this section need a good overhaul.
>
> Yep. Bit of polish below. The hairy functions like enclose-array are
> still not super clear.
>
> Conventional Arrays
> -------------------
>
> "Conventional arrays" are a collection of cells organized into an
> arbitrary number of dimensions. Each cell can hold any kind of Scheme
...snipped...
Thanks, Kevin, for doing all that work in cleaning up the manual
section on Conventional Arrays. I think it makes much better sense
now. The addition of sample code fragments in several places is a
very good touch.
I have a couple of suggestions for further changes.
1.
The subject of this section is "Conventional Arrays". Mixing in
the documentation of uniform-arrays/uniform-vectors is not ideal.
I think it would be less confusing if the descriptions of all
uniform-* procedures were moved to the section "Uniform Arrays"
where they belong.
2.
The second paragraph in the description of make-array reads a bit
awkward to me. I have suggested an alternative below. Use it if
you see fit.
--------------------
- Scheme Procedure: make-array initial-value bound ...
Create and return an array that has as many dimensions as there are
BOUNDs and fill it with INITIAL-VALUE.
old Each BOUND may be a positive non-zero integer N, in which case the
old index for that dimension can range from 0 through N-1; or an
old explicit index range specifier in the form `(LOWER UPPER)', where
old both LOWER and UPPER are integers, possibly less than zero, and
old possibly the same number (however, LOWER cannot be greater than
old UPPER).
new Each BOUND may be a positive non-zero integer N, in which case
new the index for that dimension can range from 0 through N-1;
new or an explicit index range specifier as a list of two integers
new `(LOWER UPPER)', where LOWER or UPPER may be negative but
new UPPER cannot be less than LOWER.
--
Rouben Rostamian
_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: more garbled documentation in uniform arrays
2004-01-17 15:48 more garbled documentation in uniform arrays Rouben Rostamian
@ 2004-01-23 0:15 ` Kevin Ryde
0 siblings, 0 replies; 4+ messages in thread
From: Kevin Ryde @ 2004-01-23 0:15 UTC (permalink / raw)
Cc: bug-guile
"Rouben Rostamian" <rostamian@umbc.edu> writes:
>
> The subject of this section is "Conventional Arrays". Mixing in
> the documentation of uniform-arrays/uniform-vectors is not ideal.
The whole division between the two isn't terribly clear. Partly
because there isn't really a division :), there's just one underlying
set of functions.
> The second paragraph in the description of make-array reads a bit
> awkward to me. I have suggested an alternative below.
Hmm. I think I'll leave it for the moment. It can all stand a bit
more polish.
_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2004-01-23 0:15 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2004-01-17 15:48 more garbled documentation in uniform arrays Rouben Rostamian
2004-01-23 0:15 ` Kevin Ryde
-- strict thread matches above, loose matches on Subject: below --
2004-01-09 17:38 Rouben Rostamian
2004-01-17 14:48 ` Kevin Ryde
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).