DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(guile.info.gz) Conventional Arrays

Info Catalog (guile.info.gz) Arrays (guile.info.gz) Array Mapping
 
 22.6.1 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, and 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).
 
  -- Scheme Procedure: array? v [prot]
  -- C Function: scm_array_p (v, prot)
      Return `#t' if the OBJ is an array, and `#f' if not.  The
      PROTOTYPE argument is used with uniform arrays and is described
      elsewhere.
 
  -- Scheme Procedure: make-array initial-value bound1 bound2 ...
      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: uniform-vector-ref v args
  -- Scheme Procedure: array-ref v . args
  -- C Function: scm_uniform_vector_ref (v, args)
      Return the element at the `(index1, index2)' element in ARRAY.
 
  -- Scheme Procedure: array-in-bounds? v . args
  -- C Function: scm_array_in_bounds_p (v, args)
      Return `#t' if its arguments would be acceptable to `array-ref'.
 
  -- 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.
 
  -- Scheme Procedure: make-shared-array oldra mapfunc . dims
  -- C Function: scm_make_shared_array (oldra, mapfunc, dims)
      `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 ra
  -- C Function: scm_shared_array_increments (ra)
      For each dimension, return the distance between elements in the
      root vector.
 
  -- Scheme Procedure: shared-array-offset ra
  -- C Function: scm_shared_array_offset (ra)
      Return the root vector index of the first element in the array.
 
  -- Scheme Procedure: shared-array-root ra
  -- C Function: scm_shared_array_root (ra)
      Return the root vector of a shared array.
 
  -- Scheme Procedure: transpose-array ra . args
  -- C Function: scm_transpose_array (ra, args)
      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.  DIM0, DIM1, ... 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 DIM0, DIM1, ... correspond to dimensions in the
      array to be returned, 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 ra . axes
  -- C Function: scm_enclose_array (ra, axes)
      DIM0, DIM1 ... 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.
 
      examples:
           (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
      Return a list of inclusive bounds of integers.
           (array-shape (make-array 'foo '(-1 3) 5)) => ((-1 3) (0 4))
 
  -- Scheme Procedure: array-dimensions ra
  -- C Function: scm_array_dimensions (ra)
      `Array-dimensions' is similar to `array-shape' but replaces
      elements with a `0' minimum with one greater than the maximum. So:
           (array-dimensions (make-array 'foo '(-1 3) 5)) => ((-1 3) 5)
 
  -- Scheme Procedure: array-rank ra
  -- C Function: scm_array_rank (ra)
      Return the number of dimensions of OBJ.  If OBJ is not an array,
      `0' is returned.
 
  -- Scheme Procedure: array->list v
  -- C Function: scm_array_to_list (v)
      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 SOURCE to the
      corresponding element of DESTINATION.  DESTINATION must have the
      same rank as SOURCE, and be at least as large in each dimension.
      The order is unspecified.
 
  -- Scheme Procedure: array-fill! ra fill
  -- C Function: scm_array_fill_x (ra, fill)
      Store FILL in every element of ARRAY.  The value returned is
      unspecified.
 
  -- Scheme Procedure: array-equal? ra0 ra1
      Return `#t' iff 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.
 
Info Catalog (guile.info.gz) Arrays (guile.info.gz) Array Mapping
automatically generated byinfo2html