guile/NEWS-wip-vector-cleanup.txt

(wip-vector-cleanup for Guile 3.0) -*- coding: utf-8; mode: org; -*-

TBA to NEWS for this branch.
 
* Forward incompatible changes

Applying these changes will make your program work with this version of
Guile and continue working with older versions (at least back to 2.2).

** vector->list and vector-copy require a true vector argument.

Use array->list and array-copy (from (ice-9 arrays)) on general arrays.

** scm_is_simple_vector has been removed.

Use scm_is_vector instead.

** libguile/generalized-vectors.[hc] libguile/generalized-arrays.[hc] and have been removed.

If you were including these headers directly for any reason, just include libguile.h instead.

** scm_from_contiguous_typed_array has been removed.

This function was undocumented. Instead, use scm_make_typed_array and
the array handle functions to copy data to the new array.

** uniform-array->bytevector has been moved from (rnrs bytevectors) / (rnrs) to core.

This function is undocumented.


* Backward incompatible changes

Applying these changes will make your program work with this version of
Guile and STOP working with older versions.

** scm_array_p takes a single argument.

This function used to take a second unused argument for the sake of
compatibility with older versions of Guile. Just remove this argument from your
calls.

** SCM_SIMPLE_VECTOR_REF, SCM_SIMPLE_VECTOR_SET and SCM_SIMPLE_VECTOR_LENGTH have been renamed.

Use SCM_VECTOR_REF, SCM_VECTOR_SET and SCM_VECTOR_LENGTH instead.

** The vector argument to scm_vector_elements / scm_vector_writable_elements must be a true vector. Handle/inc arguments have been removed.

Use scm_array_get_handle and scm_array_handle_elements / scm_array_handle_writable_elements on general #t arrays.

** The vector argument to scm_bitvector_elements / scm_bitvector_writable_elements must be a true bitvector. Handle/inc arguments have been removed.

Use scm_array_get_handle and scm_array_handle_bit_elements / scm_array_handle_bit_writable_elements on general bit arrays.
Use scm_array1_bit_elements (NEW) / scm_array1_bit_writable_elements (NEW) on rank-1 bit arrays.


* Bugfixes introducing incompatibility

** vector-move-right! vector-move-left! require true vector arguments

These functions weren't advertised to work on non-vector arrays. They did try to, but only incorrectly. For example:

  (define a (vector 1 2 3 4 5))
  (define b (make-array 0 '(1 5)))
  (vector-move-right! a 0 2 b 2)
  b
  => #1@1(0 0 1 2 0)

instead of the correct result #1@1(0 1 2 0 0). This buggy support has been removed.


* Compatible changes

** vector-copy! from (srfi :43) is provided in core.


* Rationale / TODO

The ultimate goal of this patch set is to have arrays be strictly layered above typed vectors so they can be replaced by a different implementation without affecting the latter.

** Status as of 3.0.0
  
  - The _elements functions require the array handle interface even for true vectors, when all of handle, inc and off are unnecessary. This creates a burden (having to declare & release handles, etc).
  - The srfi-4 _elements functions don't accept arbitrary rank-1 xxxarray even though they require the array handle interface (inc, handle are superfluous).

** Plan [4/8]

  - [X] Provide scm_VTYPE_(writable_)elements with signature [(SCM) -> pointer] for all vector types.
  - [ ] Provide scm_array1_VTYPE_(writable_)elements with signature [(SCM, &handle, ...) -> pointer] for all vector types. These replace the old scm_VTYPE_(writable_)elements but will be available on the array API and not on the xxxvector APIs.
  - [X] Remove the dependence of vector.c on array-handle-h
  - [X] Remove the dependence of VECTOR-TYPE-ref -> array_handle use seen in scm_array_get_handle.
  - [ ] Remove the dependence of bitvector.c srfi-4.c etc. on array-handle.h
  - [X] Bug: setaffinity in posix.c failed to release the mask handle
  - [ ] Bug: scm_bitvector_elements doesn't select for type = bit
  - [ ] Bug: bit-set*! already requires second arg to be true bitvector


* Other

** basic rank-1 ops on VECTOR_TYPEs need (len begin inc) instead of (begin end)

  - look at CBLAS/BLIS
  - this is a problem because all the RnRS & SRFIs use (begin end) :-(