/[guile]/guile/guile-core/doc/ref/scheme-compound.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-compound.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.6 by ossau, Fri Mar 29 20:25:24 2002 UTC revision 1.7 by ossau, Mon Apr 1 18:46:26 2002 UTC
# Line 528  return value is not specified. Line 528  return value is not specified.
528  @section Vectors  @section Vectors
529  @tpindex Vectors  @tpindex Vectors
530    
 @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?  
   
531  Vectors are sequences of Scheme objects.  Unlike lists, the length of a  Vectors are sequences of Scheme objects.  Unlike lists, the length of a
532  vector, once the vector is created, cannot be changed.  The advantage of  vector, once the vector is created, cannot be changed.  The advantage of
533  vectors over lists is that the time required to access one element of a vector  vectors over lists is that the time required to access one element of a vector
# Line 545  different types of objects in the same v Line 540  different types of objects in the same v
540  vectors, you may wish to use arrays, instead.  Note, too, that some array  vectors, you may wish to use arrays, instead.  Note, too, that some array
541  procedures operate happily on vectors (@pxref{Arrays}).  procedures operate happily on vectors (@pxref{Arrays}).
542    
543  @subsection Vector Read Syntax  @menu
544    * Vector Syntax::               Read syntax for vectors.
545    * Vector Creation::             Dynamic vector creation and validation.
546    * Vector Accessors::            Accessing and modifying vector contents.
547    @end menu
548    
549    
550    @node Vector Syntax
551    @subsection Read Syntax for Vectors
552    
553  Vectors can literally be entered in source code, just like strings,  Vectors can literally be entered in source code, just like strings,
554  characters or some of the other data types.  The read syntax for vectors  characters or some of the other data types.  The read syntax for vectors
# Line 561  number in hexadecimal notation. Line 564  number in hexadecimal notation.
564  #("Hello" foo #xdeadbeef)  #("Hello" foo #xdeadbeef)
565  @end lisp  @end lisp
566    
 @subsection Vector Predicates  
567    
568  @rnindex vector?  @node Vector Creation
569  @deffn {Scheme Procedure} vector? obj  @subsection Dynamic Vector Creation and Validation
 @deffnx {C Function} scm_vector_p (obj)  
 Return @code{#t} if @var{obj} is a vector, otherwise return  
 @code{#f}.  
 @end deffn  
570    
571  @subsection Vector Constructors  Instead of creating a vector implicitly by using the read syntax just
572    described, you can create a vector dynamically by calling one of the
573  @rnindex make-vector  @code{vector} and @code{list->vector} primitives with the list of Scheme
574  @deffn {Scheme Procedure} make-vector k [fill]  values that you want to place into a vector.  The size of the vector
575  @deffnx {C Function} scm_make_vector (k, fill)  thus created is determined implicitly by the number of arguments given.
 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  
576    
577  @rnindex vector  @rnindex vector
578  @rnindex list->vector  @rnindex list->vector
# Line 594  given arguments.  Analogous to @code{lis Line 587  given arguments.  Analogous to @code{lis
587  @end lisp  @end lisp
588  @end deffn  @end deffn
589    
590    (As an aside, an interesting implementation detail is that the Guile
591    reader reads the @code{#(@dots{})} syntax by reading everything but the
592    initial @code{#} as a @emph{list}, and then passing the list that
593    results to @code{list->vector}.  Notice how neatly this fits with the
594    similarity between the read (and print) syntaxes for lists and vectors.)
595    
596    The inverse operation is @code{vector->list}:
597    
598  @rnindex vector->list  @rnindex vector->list
599  @deffn {Scheme Procedure} vector->list v  @deffn {Scheme Procedure} vector->list v
600  @deffnx {C Function} scm_vector_to_list (v)  @deffnx {C Function} scm_vector_to_list (v)
# Line 605  Return a newly allocated list composed o Line 606  Return a newly allocated list composed o
606  @end lisp  @end lisp
607  @end deffn  @end deffn
608    
609  @subsection Vector Modification  To allocate a vector with an explicitly specified size, use
610    @code{make-vector}.  With this primitive you can also specify an initial
611    value for the vector elements (the same value for all elements, that
612    is):
613    
614    @rnindex make-vector
615    @deffn {Scheme Procedure} make-vector k [fill]
616    @deffnx {C Function} scm_make_vector (k, fill)
617    Return a newly allocated vector of @var{k} elements.  If a
618    second argument is given, then each position is initialized to
619    @var{fill}.  Otherwise the initial contents of each position is
620    unspecified.
621    @end deffn
622    
623    To check whether an arbitrary Scheme value @emph{is} a vector, use the
624    @code{vector?} primitive:
625    
626    @rnindex vector?
627    @deffn {Scheme Procedure} vector? obj
628    @deffnx {C Function} scm_vector_p (obj)
629    Return @code{#t} if @var{obj} is a vector, otherwise return
630    @code{#f}.
631    @end deffn
632    
633    
634    @node Vector Accessors
635    @subsection Accessing and Modifying Vector Contents
636    
637    @code{vector-length} and @code{vector-ref} return information about a
638    given vector, respectively its size and the elements that are contained
639    in the vector.
640    
641  A vector created by any of the vector constructor procedures  @rnindex vector-length
642  (@pxref{Vectors}) documented above can be modified using the  @deffn {Scheme Procedure} vector-length vector
643  following procedures.  @deffnx {C Function} scm_vector_length vector
644    Return the number of elements in @var{vector} as an exact integer.
645  @emph{NOTE:} According to R5RS, using any of these procedures on  @end deffn
646  literally entered vectors is an error, because these vectors are  
647  considered to be constant, although Guile currently does not detect this  @rnindex vector-ref
648    @deffn {Scheme Procedure} vector-ref vector k
649    @deffnx {C Function} scm_vector_ref vector k
650    Return the contents of position @var{k} of @var{vector}.
651    @var{k} must be a valid index of @var{vector}.
652    @lisp
653    (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
654    (vector-ref '#(1 1 2 3 5 8 13 21)
655        (let ((i (round (* 2 (acos -1)))))
656          (if (inexact? i)
657            (inexact->exact i)
658               i))) @result{} 13
659    @end lisp
660    @end deffn
661    
662    A vector created by one of the dynamic vector constructor procedures
663    (@pxref{Vector Creation}) can be modified using the following
664    procedures.
665    
666    @emph{NOTE:} According to R5RS, it is an error to use any of these
667    procedures on a literally read vector, because such vectors should be
668    considered as constants.  Currently, however, Guile does not detect this
669  error.  error.
670    
671  @rnindex vector-set!  @rnindex vector-set!
672  @deffn {Scheme Procedure} vector-set! vector k obj  @deffn {Scheme Procedure} vector-set! vector k obj
673    @deffnx {C Function} scm_vector_set_x vector k obj
674  Store @var{obj} in position @var{k} of @var{vector}.  Store @var{obj} in position @var{k} of @var{vector}.
675  @var{k} must be a valid index of @var{vector}.  @var{k} must be a valid index of @var{vector}.
676  The value returned by @samp{vector-set!} is unspecified.  The value returned by @samp{vector-set!} is unspecified.
# Line 659  same vector, @code{vector-move-right!} i Line 712  same vector, @code{vector-move-right!} i
712  @var{start1} is less than @var{start2}.  @var{start1} is less than @var{start2}.
713  @end deffn  @end deffn
714    
 @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  
   
715    
716  @node Records  @node Records
717  @section Records  @section Records

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.7

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26