diff options
author | Neil Jerram <neil@ossau.uklinux.net> | 2002-04-01 18:46:26 +0000 |
---|---|---|
committer | Neil Jerram <neil@ossau.uklinux.net> | 2002-04-01 18:46:26 +0000 |
commit | 0624ce33f3a258013fb58c124941315e007352b9 (patch) | |
tree | b0642e22e01003fec03e2eee7fccd8bc90bf4df8 | |
parent | 755de645575d233e191808d8963c18af9d9b4867 (diff) | |
download | guile-0624ce33f3a258013fb58c124941315e007352b9.tar.gz |
Update vector docs.
Remove Guile extensions index.
A few other odds and ends.
-rw-r--r-- | doc/ref/ChangeLog | 15 | ||||
-rw-r--r-- | doc/ref/guile.texi | 38 | ||||
-rw-r--r-- | doc/ref/scheme-compound.texi | 137 | ||||
-rw-r--r-- | doc/ref/scheme-indices.texi | 7 | ||||
-rw-r--r-- | doc/ref/scheme-intro.texi | 5 |
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: |