From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Kevin Ryde Newsgroups: gmane.lisp.guile.bugs Subject: Re: more garbled documentation in uniform arrays Date: Sun, 18 Jan 2004 00:48:12 +1000 Sender: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Message-ID: <877jzq6383.fsf@zip.com.au> References: <200401091738.i09Hc2MI016344@pc18.math.umbc.edu> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1074354892 19590 80.91.224.253 (17 Jan 2004 15:54:52 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 17 Jan 2004 15:54:52 +0000 (UTC) Cc: bug-guile@gnu.org Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Sat Jan 17 16:54:47 2004 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1Ahsma-0007qy-00 for ; Sat, 17 Jan 2004 16:54:45 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.24) id 1Ahsm0-00020n-Fw for guile-bugs@m.gmane.org; Sat, 17 Jan 2004 10:54:08 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1AhrqS-0005Gi-FO for bug-guile@gnu.org; Sat, 17 Jan 2004 09:54:40 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1AhrkW-0003Zh-Er for bug-guile@gnu.org; Sat, 17 Jan 2004 09:49:03 -0500 Original-Received: from [61.8.0.36] (helo=snoopy.pacific.net.au) by monty-python.gnu.org with esmtp (Exim 4.24) id 1AhrkU-0003Yz-Ma for bug-guile@gnu.org; Sat, 17 Jan 2004 09:48:30 -0500 Original-Received: from mongrel.pacific.net.au (mongrel.pacific.net.au [61.8.0.107]) by snoopy.pacific.net.au (8.12.3/8.12.3/Debian-6.6) with ESMTP id i0HEmT92003845; Sun, 18 Jan 2004 01:48:29 +1100 Original-Received: from localhost (ppp178.dyn251.pacific.net.au [203.143.251.178]) by mongrel.pacific.net.au (8.12.3/8.12.3/Debian-6.6) with ESMTP id i0HEmQha021057; Sun, 18 Jan 2004 01:48:26 +1100 Original-Received: from gg by localhost with local (Exim 3.36 #1 (Debian)) id 1AhrkE-0000FW-00; Sun, 18 Jan 2004 00:48:14 +1000 Original-To: "Rouben Rostamian" User-Agent: Gnus/5.110002 (No Gnus v0.2) Emacs/21.3 (gnu/linux) X-BeenThere: bug-guile@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Bug reports for GUILE, GNU's Ubiquitous Extension Language List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.bugs:1103 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.bugs:1103 "Rouben Rostamian" 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) => # (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) => # - 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