REF VECTORS                                         John Gibson Aug 1989

        COPYRIGHT University of Sussex 1990. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<   STANDARD FULL VECTORS     >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

A Standard Full (S.F.)  vector in Pop-11  is an indexable  1-dimensional
array where  each element  can be  any POP  item; subscript  values  for
vectors number from 1 upwards. The creation and manipulation  procedures
for standard full vectors are listed.
    A standard  full vector  is a  particular built-in  instance of  the
general class of vectors which can be constructed using * conskey or the
syntax construct * defclass. See REF * DATA for procedures applicable to
vectors in general

         CONTENTS - (Use <ENTER> g to access required sections)

  1   Predicates on S.F. Vectors

  2   Constructing New S.F. Vectors

  3   Accessing S.F. Vector Elements

  4   Generic Datastructure Procedures on S.F. Vectors

  5   Miscellaneous

  6   Related Documentation



-----------------------------
1  Predicates on S.F. Vectors
-----------------------------

isvector(item) -> bool                                       [procedure]
        Returns true if item is a standard full vector, false if not.


check_vector(item)                                           [procedure]
        Mishaps if item is not a standard full vector.




--------------------------------
2  Constructing New S.F. Vectors
--------------------------------

See HELP * TWIDDLYBRA  and HELP * PERCENT  for information  on  building
standard full vectors with syntactic brackets.


consvector(item1, item2, ..., itemN, N) -> fvec              [procedure]
        Constructs and  returns a  standard full  vector from  the  next
        (simple integer) N items on the  user stack, where the top  item
        on the  stack  will  be  at the  highest  subscript  value.  For
        example:

                consvector("a", "b", "c", 3) =>
                ** {a b c}


initv(N) -> fvec                                             [procedure]
        Constructs and returns a standard  full vector fvec of  length N
        whose  elements   are   all   the  word   "undef".   (See   also
        * initvectorclass.)


sysvecons(item1, item2, ..., itemN, M) -> fvec               [procedure]
        Constructs and returns  a standard full  vector fvec  containing
        all the items on the stack  EXCEPT the last M, i.e. it  performs
        consvector(N) where N is

            stacklength() - M

        (This is used by the Pop-11 vector constructor, which saves  the
        stacklength M before compiling a vector constructor  expression,
        and then calls sysvecons(M) after compiling it, thus producing a
        vector of all the items in the expression.)




---------------------------------
3  Accessing S.F. Vector Elements
---------------------------------

destvector(fvec) -> (item1, item2, ..., itemN, N)            [procedure]
        Destructs the  standard  full vector  fvec,  i.e. puts  all  its
        elements on the stack, together with its length (in other words,
        does the opposite of consvector). E.g.

                destvector({A B C D}) =>
                ** A B C D 4


subscrv(n, fvec) -> item                                     [procedure]
item -> subscrv(n, fvec)
        Returns or updates the n-th element of the standard full  vector
        fvec. Since subscrv is the class_apply of standard full  vectors
        (see REF * KEYS), this can also be called as

                fvec(n) -> item
                item -> fvec(n)




---------------------------------------------------
4  Generic Datastructure Procedures on S.F. Vectors
---------------------------------------------------

The  generic   data  structure   procedures  described   in   REF * DATA
(datalength, appdata, explode,  fill, copy, etc)  are all applicable  to
standard  full   vectors,  as   are   the  generic   vector   procedures
(initvectorclass, move_subvector, sysanyvecons,  etc) also described  in
that file.




----------------
5  Miscellaneous
----------------

nullvector -> vec                                             [constant]
        The value of this constant is a vector of length 0.


vector_key -> key                                             [constant]
        This constant holds the key structure for standard full  vectors
        (see REF * KEYS).




------------------------
6  Related Documentation
------------------------

REF * INTVEC
    Describes intvecs (vectors  containing 32 bit  signed integers)  and
    shortvecs (vectors containing 16 bit signed integers).

REF * STRINGS
    Describes byte vectors.

HELP * BITVECTORS
    Describes LIB * BITVECTORS, a  package for creating and  manipulating
    compact bitvectors.

REF * DEFSTRUCT
    Describes syntax for creating new vector or record classes.

REF * DATA
    Information on Poplog data types and how they are represented.

REF * KEYS
    Describes the information  associated with each  data type and  some
    general procedures for  manipulating data and  creating fast  access
    procedures.

REF * FASTPROCS
    Describes  fast,  non-checking,  procedures  for  accessing   vector
    fields.



--- C.all/ref/vectors
--- Copyright University of Sussex 1990. All rights reserved.
