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 |
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 |
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 |
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) |
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. |
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 |