summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNeil Jerram <neil@ossau.uklinux.net>2002-04-01 18:46:26 +0000
committerNeil Jerram <neil@ossau.uklinux.net>2002-04-01 18:46:26 +0000
commit0624ce33f3a258013fb58c124941315e007352b9 (patch)
treeb0642e22e01003fec03e2eee7fccd8bc90bf4df8
parent755de645575d233e191808d8963c18af9d9b4867 (diff)
downloadguile-0624ce33f3a258013fb58c124941315e007352b9.tar.gz
Update vector docs.
Remove Guile extensions index. A few other odds and ends.
-rw-r--r--doc/ref/ChangeLog15
-rw-r--r--doc/ref/guile.texi38
-rw-r--r--doc/ref/scheme-compound.texi137
-rw-r--r--doc/ref/scheme-indices.texi7
-rw-r--r--doc/ref/scheme-intro.texi5
5 files changed, 110 insertions, 92 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 62ca7919b..fcd198edf 100644
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -1,5 +1,20 @@
2002-04-01 Neil Jerram <neil@ossau.uklinux.net>
+ * scheme-intro.texi (Scheme Layout): Remove reference to defunct
+ Guile Extensions index.
+
+ * guile.texi: Removed Guile Extensions index.
+
+ * scheme-indices.texi (Guile Extensions Index): Removed.
+
+ * guile.texi: Remove vgone, vdeprecated, vchanged and vnote
+ macros; they're not actually useful after all. Update copyright
+ years.
+
+ * scheme-compound.texi (Vectors): Make subsections into nodes.
+ (Vectors): Review, slightly reorg and clarify docs in this
+ section.
+
* scheme-data.texi (Symbols): Reorganized node substructure and
added lots of explanatory text around the @deffn's.
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index cd83b3e79..25f9ef264 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -46,37 +46,15 @@
@c reference manual to group stuff according to whether it is R5RS or a
@c Guile extension.
@defcodeindex rn
-@defcodeindex ge
@include version.texi
-@c Macros for describing version information. I've initially defined
-@c all of these to expand to nothing, but they could perhaps be made to
-@c expand to something like "New in Guile 45!" in future.
-
-@c vnew - indicates the Guile version in which item first appeared.
+@c vnew - For (some) new items, indicates the Guile version in which
+@c item first appeared. In future, this could be made to expand to
+@c something like a "New in Guile 45!" banner.
@macro vnew{VERSION}
@end macro
-@c vdeprecated - indicates that the item has been deprecated, and the
-@c Guile version in which the deprecation started.
-@macro vdeprecated{VERSION}
-@end macro
-
-@c vgone - a way of tracking items that are no longer here. In this
-@c case, VERSION is the last Guile version in which the item was present.
-@macro vgone{WHAT, VERSION}
-@end macro
-
-@c vchanged - indicates the Guile version in which item's behaviour
-@c significantly changed.
-@macro vchanged{VERSION}
-@end macro
-
-@c vnote - catchall for any additional notes.
-@macro vnote{NOTE}
-@end macro
-
@c @iftex
@c @cropmarks
@c @end iftex
@@ -93,7 +71,8 @@ Guile Reference Manual
Copyright (C) 1996 Free Software Foundation @*
Copyright (C) 1997 Free Software Foundation @*
Copyright (C) 2000 Free Software Foundation @*
-Copyright (C) 2001 Free Software Foundation
+Copyright (C) 2001 Free Software Foundation @*
+Copyright (C) 2002 Free Software Foundation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -121,7 +100,7 @@ by the Free Software Foundation.
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
-@subtitle $Id: guile.texi,v 1.16 2002-03-27 21:55:31 ossau Exp $
+@subtitle $Id: guile.texi,v 1.17 2002-04-01 18:46:26 ossau Exp $
@subtitle For use with Guile @value{VERSION}
@c AUTHORS
@@ -186,6 +165,10 @@ Copyright @copyright{} 1997 Free Software Foundation
Copyright @copyright{} 2000 Free Software Foundation
+Copyright @copyright{} 2001 Free Software Foundation
+
+Copyright @copyright{} 2002 Free Software Foundation
+
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@@ -291,7 +274,6 @@ Indices
* Variable Index::
* Type Index::
* R5RS Index::
-* Guile Extensions Index::
@end menu
diff --git a/doc/ref/scheme-compound.texi b/doc/ref/scheme-compound.texi
index 75623563b..b39ea76ca 100644
--- a/doc/ref/scheme-compound.texi
+++ b/doc/ref/scheme-compound.texi
@@ -528,11 +528,6 @@ return value is not specified.
@section Vectors
@tpindex Vectors
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Should the subsections of this section be nodes
-@c of their own, or are the resulting nodes too short, then?
-
Vectors are sequences of Scheme objects. Unlike lists, the length of a
vector, once the vector is created, cannot be changed. The advantage of
vectors over lists is that the time required to access one element of a vector
@@ -545,7 +540,15 @@ different types of objects in the same vector. For vectors containing
vectors, you may wish to use arrays, instead. Note, too, that some array
procedures operate happily on vectors (@pxref{Arrays}).
-@subsection Vector Read Syntax
+@menu
+* Vector Syntax:: Read syntax for vectors.
+* Vector Creation:: Dynamic vector creation and validation.
+* Vector Accessors:: Accessing and modifying vector contents.
+@end menu
+
+
+@node Vector Syntax
+@subsection Read Syntax for Vectors
Vectors can literally be entered in source code, just like strings,
characters or some of the other data types. The read syntax for vectors
@@ -561,25 +564,15 @@ number in hexadecimal notation.
#("Hello" foo #xdeadbeef)
@end lisp
-@subsection Vector Predicates
-@rnindex vector?
-@deffn {Scheme Procedure} vector? obj
-@deffnx {C Function} scm_vector_p (obj)
-Return @code{#t} if @var{obj} is a vector, otherwise return
-@code{#f}.
-@end deffn
-
-@subsection Vector Constructors
+@node Vector Creation
+@subsection Dynamic Vector Creation and Validation
-@rnindex make-vector
-@deffn {Scheme Procedure} make-vector k [fill]
-@deffnx {C Function} scm_make_vector (k, fill)
-Return a newly allocated vector of @var{k} elements. If a
-second argument is given, then each position is initialized to
-@var{fill}. Otherwise the initial contents of each position is
-unspecified.
-@end deffn
+Instead of creating a vector implicitly by using the read syntax just
+described, you can create a vector dynamically by calling one of the
+@code{vector} and @code{list->vector} primitives with the list of Scheme
+values that you want to place into a vector. The size of the vector
+thus created is determined implicitly by the number of arguments given.
@rnindex vector
@rnindex list->vector
@@ -594,6 +587,14 @@ given arguments. Analogous to @code{list}.
@end lisp
@end deffn
+(As an aside, an interesting implementation detail is that the Guile
+reader reads the @code{#(@dots{})} syntax by reading everything but the
+initial @code{#} as a @emph{list}, and then passing the list that
+results to @code{list->vector}. Notice how neatly this fits with the
+similarity between the read (and print) syntaxes for lists and vectors.)
+
+The inverse operation is @code{vector->list}:
+
@rnindex vector->list
@deffn {Scheme Procedure} vector->list v
@deffnx {C Function} scm_vector_to_list (v)
@@ -605,19 +606,71 @@ Return a newly allocated list composed of the elements of @var{v}.
@end lisp
@end deffn
-@subsection Vector Modification
+To allocate a vector with an explicitly specified size, use
+@code{make-vector}. With this primitive you can also specify an initial
+value for the vector elements (the same value for all elements, that
+is):
+
+@rnindex make-vector
+@deffn {Scheme Procedure} make-vector k [fill]
+@deffnx {C Function} scm_make_vector (k, fill)
+Return a newly allocated vector of @var{k} elements. If a
+second argument is given, then each position is initialized to
+@var{fill}. Otherwise the initial contents of each position is
+unspecified.
+@end deffn
+
+To check whether an arbitrary Scheme value @emph{is} a vector, use the
+@code{vector?} primitive:
+
+@rnindex vector?
+@deffn {Scheme Procedure} vector? obj
+@deffnx {C Function} scm_vector_p (obj)
+Return @code{#t} if @var{obj} is a vector, otherwise return
+@code{#f}.
+@end deffn
+
-A vector created by any of the vector constructor procedures
-(@pxref{Vectors}) documented above can be modified using the
-following procedures.
+@node Vector Accessors
+@subsection Accessing and Modifying Vector Contents
-@emph{NOTE:} According to R5RS, using any of these procedures on
-literally entered vectors is an error, because these vectors are
-considered to be constant, although Guile currently does not detect this
+@code{vector-length} and @code{vector-ref} return information about a
+given vector, respectively its size and the elements that are contained
+in the vector.
+
+@rnindex vector-length
+@deffn {Scheme Procedure} vector-length vector
+@deffnx {C Function} scm_vector_length vector
+Return the number of elements in @var{vector} as an exact integer.
+@end deffn
+
+@rnindex vector-ref
+@deffn {Scheme Procedure} vector-ref vector k
+@deffnx {C Function} scm_vector_ref vector k
+Return the contents of position @var{k} of @var{vector}.
+@var{k} must be a valid index of @var{vector}.
+@lisp
+(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
+(vector-ref '#(1 1 2 3 5 8 13 21)
+ (let ((i (round (* 2 (acos -1)))))
+ (if (inexact? i)
+ (inexact->exact i)
+ i))) @result{} 13
+@end lisp
+@end deffn
+
+A vector created by one of the dynamic vector constructor procedures
+(@pxref{Vector Creation}) can be modified using the following
+procedures.
+
+@emph{NOTE:} According to R5RS, it is an error to use any of these
+procedures on a literally read vector, because such vectors should be
+considered as constants. Currently, however, Guile does not detect this
error.
@rnindex vector-set!
@deffn {Scheme Procedure} vector-set! vector k obj
+@deffnx {C Function} scm_vector_set_x vector k obj
Store @var{obj} in position @var{k} of @var{vector}.
@var{k} must be a valid index of @var{vector}.
The value returned by @samp{vector-set!} is unspecified.
@@ -659,30 +712,6 @@ same vector, @code{vector-move-right!} is usually appropriate when
@var{start1} is less than @var{start2}.
@end deffn
-@subsection Vector Selection
-
-These procedures return information about a given vector, such as the
-size or what elements are contained in the vector.
-
-@rnindex vector-length
-@deffn {Scheme Procedure} vector-length vector
-Return the number of elements in @var{vector} as an exact integer.
-@end deffn
-
-@rnindex vector-ref
-@deffn {Scheme Procedure} vector-ref vector k
-Return the contents of position @var{k} of @var{vector}.
-@var{k} must be a valid index of @var{vector}.
-@lisp
-(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
-(vector-ref '#(1 1 2 3 5 8 13 21)
- (let ((i (round (* 2 (acos -1)))))
- (if (inexact? i)
- (inexact->exact i)
- i))) @result{} 13
-@end lisp
-@end deffn
-
@node Records
@section Records
diff --git a/doc/ref/scheme-indices.texi b/doc/ref/scheme-indices.texi
index 46a87b3d8..acecb3ff4 100644
--- a/doc/ref/scheme-indices.texi
+++ b/doc/ref/scheme-indices.texi
@@ -5,13 +5,6 @@
@printindex rn
-@page
-@node Guile Extensions Index
-@unnumbered Guile Extensions Index
-
-@printindex ge
-
-
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
diff --git a/doc/ref/scheme-intro.texi b/doc/ref/scheme-intro.texi
index 5bac00086..3cd9967b4 100644
--- a/doc/ref/scheme-intro.texi
+++ b/doc/ref/scheme-intro.texi
@@ -45,9 +45,8 @@ parts and Guile-specific extensions, the text indicates which parts of
the documentation describe R5RS behaviour and which parts describe Guile
extensions.
-For a breakdown of Guile's core language and features in terms of what
-is R5RS-compliant and what is Guile-specific, see the corresponding
-indices: @ref{R5RS Index} and @ref{Guile Extensions Index}.
+For a quick way of identifying the parts of Guile that implement
+R5RS-compliant features, see the R5RS index: @ref{R5RS Index}.
@c Local Variables: