uvector - uniform numeric vector extension to STk

                                                 Shiro Kawai (shiro@acm.org)
                           $Id: README,v 1.3 1999/11/10 08:06:37 shiro Exp $

This package is an extension module of "homogeneous numeric vector datatypes"
defined in SRFI-4 (http://srfi.schemers.org/srfi-4/).

You need STk-4.0.1 or later to install this package.
See STk homepage (http://kaolin.unice.fr/stk) for the most recent STk
distribution.

You can obtain the most recent version of this package at
http://practical-scheme.net/

If you find a bug or add some code to this module, please let
me know by email shiro@acm.org.  I'll incorporate the change to
the later version.


INSTALL
=======

There are two ways to install this package.

  (1) install as an extension module.  With this option,
      you can load uvector module dynamically by `(load "uvector")'
      expression.  However, the reader syntax defined in SRFI-4
      is not available.

  (2) install as a built-in module.  You need to patch STk source
      tree, and uvector module is compiled in the stk executable.
      With this option, stk reader recognizes SRFI-4 syntax.

INSTALL AS AN EXTENTION MODULE

  (1) gunzip and untar the package.  You'll get "uvector" directory.
  (2) cd uvector
  (3) stk Makefile.scm
  (4) make
  (5) make install

INSTALL AS A BUILT-IN MODULE

  (0) You need to have a STk-4.0.1 source tree.  $STKTOPDIR stands for
      the top directory of STk source.
  (1) gunzip and untar the package.
  (2) cd uvector
  (3) ./apply-patch $STKTOPDIR
  (4) cd $STKTOPDIR
  (5) Build STk with normal procedure (./configure + make + make install)


CONFORMANCE
===========

All SFRI-4 procedures are defined, i.e. 

  (TAGvector? obj)
  (make-TAGvector n [ TAGvalue ]) 
  (TAGvector TAGvalue...) 
  (TAGvector-length TAGvect) 
  (TAGvector-ref TAGvect i) 
  (TAGvector-set! TAGvect i TAGvalue) 
  (TAGvector->list TAGvect) 
  (list->TAGvector TAGlist) 

where TAG is one of s8, u8, s16, u16, s32, u32, s64, u64, f32 or f64.

For integer vectors, the lower bits of supported range is used if
TAGvalue is out of range.  For floating-point vectors, the result
is unspecified if a value out of range is passed.

There's a known bug in s32vector.  If you specify -(2^31) as a TAGvalue,
it becomes 0.


EXTENSION
=========

Following procedures are also available for all tag types.

  (TAGvector-copy TAGvect)
     Creats a copy of TAGvect.

  (TAGvector-copy! TAGvect1 TAGvect2)
     Copies the contents of TAGvect2 into TAGvect1.  The original contents
     of TAGvect1 is destroyed.  TAGvect1 and TAGvect2 must have the same
     length.

  (TAGvector->vector TAGvect)
     Convert TAGvect to a standard Scheme vector.

  (vector->TAGvector vector)
     Convert a standard Scheme vector to a TAGvector.

Following procedures are also available for f32 and f64 vectors.

  (TAGvector-norm TAGvect)
     Returns a norm of the TAGvect.

  (TAGvector-normalize! TAGvect)
     Normalize TAGvect.  The original contents of TAGvect is destroyed.
     If the norm of TAGvect is zero (or very close to zero), and error
     is thrown.

  (TAGvector-scale TAGvect TAGvalue)
     Returns a new TAGvector whose elements are the multiplication of
     elements of TAGvect by TAGvalue.   TAGvalue must be an inexact
     number.

  (TAGvector-scale! TAGvect TAGvalue)
     Replaces elements in TAGvect by the multiplication of the original
     elements of TAGvect by TAGvalue.   TAGvalue must be an inexact
     number.  The modified TAGvect is returned.

  (TAGvector-add TAGvect1 TAGvect2 ...)
     Returns a new TAGvector whose elements are the sum of corresponding
     elements of specified TAGvect's.  All arguments must have the
     same length.

  (TAGvector-increment! TAGvect1 TAGvect2 ...)
     Destructively modifies elements of TAGvect1 to the sum of itself
     and corresponding elements of specified TAGvect's.
     All arguments must have the same length.

  (TAGvector-subtract TAGvect1 TAGvect2 ...)
     Returns a new TAGvector whose elements are calculated by subtracting
     corresponding elements of TAGvect2 ... from TAGvect1.
     All arguments must have the same length.

  (TAGvector-decrement! TAGvect1 TAGvect2 ...)
     Destructively modifies elements of TAGvect1 by subtracting the
     corresponding elements of TAGvect2 ....
     All arguments must have the same length.

  (TAGvector-dot-product TAGvect1 TAGvect2)
     Returns a dot product of two TAGvect's.  Both argument must have
     the same length.

  (TAGvector-cross-product TAGvect1 TAGvect2)
     Returns a cross product of two TAGvect's.  Both argument must have
     the length of 3.