guile/guile-core/doc ChangeLog srfi-modules.texi

[Martin Grabmueller]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Martin Grabmueller <address@hidden>     01/06/27 06:19:43

Modified files:
        guile-core/doc : ChangeLog srfi-modules.texi 

Log message:
        * srfi-modules.texi (SRFI-4): Added documentation for the new
        module (srfi srfi-4).

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/ChangeLog.diff?cvsroot=OldCVS&tr1=1.103&tr2=1.104&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/srfi-modules.texi.diff?cvsroot=OldCVS&tr1=1.7&tr2=1.8&r1=text&r2=text

Patches:
Index: guile/guile-core/doc/ChangeLog
diff -u guile/guile-core/doc/ChangeLog:1.103 
guile/guile-core/doc/ChangeLog:1.104
--- guile/guile-core/doc/ChangeLog:1.103        Tue Jun 26 14:55:44 2001
+++ guile/guile-core/doc/ChangeLog      Wed Jun 27 06:19:43 2001
@@ -1,3 +1,8 @@
+2001-06-27  Martin Grabmueller  <address@hidden>
+
+       * srfi-modules.texi (SRFI-4): Added documentation for the new
+       module (srfi srfi-4).
+
 2001-06-26  Neil Jerram  <address@hidden>
 
        * gh.texi (scm transition summary): Refer to scm_mem2string
Index: guile/guile-core/doc/srfi-modules.texi
diff -u guile/guile-core/doc/srfi-modules.texi:1.7 
guile/guile-core/doc/srfi-modules.texi:1.8
--- guile/guile-core/doc/srfi-modules.texi:1.7  Mon Jun 18 12:08:31 2001
+++ guile/guile-core/doc/srfi-modules.texi      Wed Jun 27 06:19:43 2001
@@ -17,6 +17,7 @@
 * SRFI-0::                      cond-expand
 * SRFI-1::                      List library.
 * SRFI-2::                      and-let*.
+* SRFI-4::                      Homogeneous numeric vector datatypes.
 * SRFI-6::                      Basic String Ports.
 * SRFI-8::                      receive.
 * SRFI-9::                      define-record-type.
@@ -832,6 +833,131 @@
 @result{}
 1
 @end lisp
+
+
address@hidden SRFI-4
address@hidden SRFI-4 - Homogeneous numeric vector datatypes.
+
address@hidden FIXME::martin: Review me!
+
+SRFI-4 defines a set of datatypes for vectors whose elements are all
+of the same numeric type.  Vectors for signed and unsigned exact
+integer or inexact real numbers in several precisions are available.
+
+Procedures similar to the vector procedures (@pxref{Vectors}) are
+provided for handling these homogeneous vectors, but they are distinct
+datatypes.
+
+The reason for providing this set of datatypes is that with the
+limitation (all elements must have the same type), it is possible to
+implement them much more memory-efficient than normal, heterogenous
+vectors.
+
+If you want to use these datatypes and the corresponding procedures,
+you have to use the module @code{(srfi srfi-4)}.
+
+Ten vector data types are provided: Unsigned and signed integer values
+with 8, 16, 32 and 64 bits and floating point values with 32 and 64
+bits.  In the following descriptions, the tags @code{u8}, @code{s8},
address@hidden, @code{s16}, @code{u32}, @code{s32}, @code{u64},
address@hidden, @code{f32}, @code{f64}, respectively, are used for
+denoting the various types.
+
address@hidden
+* SRFI-4 - Read Syntax::        How to write homogeneous vector literals.
+* SRFI-4 - Procedures::         Available homogeneous vector procedures.
address@hidden menu
+
+
address@hidden SRFI-4 - Read Syntax
address@hidden SRFI-4 - Read Syntax
+
+Homogeneous numeric vectors have an external representation (read
+syntax) similar to normal Scheme vectors, but with an additional tag
+telling the vector's type.
+
address@hidden
+#u16(1 2 3)
address@hidden lisp
+
+denotes a homogeneous numeric vector of three elements, which are the
+values 1, 2 and 3, represented as 16-bit unsigned integers.
+Correspondingly,
+
address@hidden
+#f64(3.1415 2.71)
address@hidden lisp
+
+denotes a vector of two elements, which are the values 3.1415 and
+2.71, represented as floating-point values of 64 bit precision.
+
+Please note that the read syntax for floating-point vectors conflicts
+with Standard Scheme, because there @code{#f} is defined to be the
+literal false value.  That means, that with the loaded SRFI-4 module,
+it is not possible to enter some list like
+
address@hidden
+'(1 #f3)
address@hidden lisp
+
+and hope that it will be parsed as a three-element list with the
+elements 1, @code{#f} and 3.  In normal use, this should be no
+problem, because people tend to terminate tokens sensibly when writing
+Scheme expressions.
+
address@hidden SRFI-4 - Procedures
address@hidden SRFI-4 Procedures
+
+The procedures listed in this section are provided for all homogeneous
+numeric vector datatypes.  For brevity, they are not all documented,
+but a summary of the procedures is given.  In the following
+descriptions, you can replace @code{TAG} by any of the datatype
+indicators @code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32},
address@hidden, @code{u64}, @code{s64}, @code{f32} and @code{f64}.
+
+For example, you can use the procedures @code{u8vector?},
address@hidden, @code{u16vector}, @code{u32vector-length},
address@hidden, @code{f32vector-set!} or @code{f64vector->list}.
+
address@hidden primitive TAGvector? obj
+Return @code{#t} if @var{obj} is a homogeneous numeric vector of type
address@hidden
address@hidden deffn
+
address@hidden primitive make-TAGvector n [value]
+Create a newly allocated homogeneous numeric vector of type
address@hidden, which can hold @var{n} elements.  If @var{value} is given,
+the vector is initialized with the value, otherwise, the contents of
+the returned vector is not specified.
address@hidden deffn
+
address@hidden primitive TAGvector value1 @dots{}
+Create a newly allocated homogeneous numeric vector of type
address@hidden The returned vector is as long as the number of arguments
+given, and is initialized with the argument values.
address@hidden deffn
+
address@hidden primitive TAGvector-length TAGvec
+Return the number of elements in @var{TAGvec}.
address@hidden deffn
+
address@hidden primitive TAGvector-ref TAGvec i
+Return the element at index @var{i} in @var{TAGvec}.
address@hidden deffn
+
address@hidden primitive TAGvector-ref TAGvec i value
+Set the element at index @var{i} in @var{TAGvec} to @var{value}.  The
+return value is not specified.
address@hidden deffn
+
address@hidden primitive TAGvector->list TAGvec
+Return a newly allocated list holding all elements of @var{TAGvec}.
address@hidden deffn
+
address@hidden primitive list->TAGvector lst
+Return a newly allocated homogeneous numeric vector of type @code{TAG},
+initialized with the elements of the list @var{lst}.
address@hidden deffn
 
 
 @node SRFI-6