REF INTVEC                                          Aled Morris Sep 1986

       COPYRIGHT University of Sussex 1990. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<    SIGNED INTEGER VECTORS   >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This REF file deals with the procedures for constructing, and  accessing
intvecs and shortvecs  which are  the other two  other 'packed  integer'
vector-types besides strings which are predefined in Poplog.

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

  1   Introduction

  2   Predicates On Integer Vectors

  3   Constructing Intvecs

  4   Accessing Integer Vector Elements

  5   Generic Datastructure/Vector Procedures on Intvecs

  6   Miscellaneous

  7   Example



---------------
1  Introduction
---------------

Along with strings, Poplog has  two other 'packed integer'  vector-types
predefined:  these  are  the  "intvec"  and  the  "shortvec".  Both  are
indexable 1-dimensional arrays  where each element  is a signed  integer
(unlike strings, where each element  is an unsigned byte). The  elements
are numbered in  the same way  as all Pop-11  vector types, i.e.  from 1
upwards.

    Elements of these vectors are the same as C "int" and "short"  sizes
respectively, so the actual range  of integers permitted will depend  on
the implementation (in all current implementations, intvecs are 32 bits,
and shortvecs are 16 bits). The  datawords of intvecs and shortvecs  are
"intvec" and "shortvec" respectively.

    Packed integer vectors are  an example of the  class of vector  type
objects which can be constructed with the defclass syntax construct  (or
with  the  procedure  conskey);  see  REF * DEFSTRUCT  and   REF * KEYS.
REF * DATA lists the procedures  applicable to all vector-type  objects.
REF * VECTORS gives  full  details  of standard  full  vectors,  another
Pop-11 built-in datatype, and REF * STRINGS details the handling of byte
vectors.




--------------------------------
2  Predicates On Integer Vectors
--------------------------------

isintvec(item) -> bool                                       [procedure]
isshortvec(item) -> bool                                     [procedure]
        Returns true if  item is  an integer vector  of the  appropriate
        type, false if not.




-----------------------
3  Constructing Intvecs
-----------------------

consintvec(int1, int2, ..., intN, N) -> intvec               [procedure]
consshortvec(int1, int2, ..., intN, N) -> shortvec           [procedure]
        Construct and return an integer  vector with its elements  taken
        from the next N integers on the user stack, where the first item
        on the stack will be at the highest subscript value. E.g.

                vars v = consintvec(100, 101, 102, 3);
                v =>
                ** <intvec 100 101 102>


initintvec(n) -> intvec                                      [procedure]
initshortvec(n) -> shortvec                                  [procedure]
        Constructs and returns an integer vector (intvec or shortvec) of
        length n  whose  elements are  all  initialised to  the  value 0
        (zero). (see also initvectorclass in REF * DATA.)




------------------------------------
4  Accessing Integer Vector Elements
------------------------------------

destintvec(intvec) -> (int1, int2, ..., intN, N)             [procedure]
destshortvec(shortvec) -> (int1, int2, ..., intN, N)         [procedure]
        Destruct the  given integer  vector (intvec  or shortvec),  i.e.
        puts all its elements on the stack, together with its length (in
        other words, does the opposite of consintvec and  consshortvec).
        E.g.

                destintvec(v) =>
                ** 100 101 102 3


subscrintvec(n, intvec) -> int                               [procedure]
int -> subscrintvec(n, intvec)
subscrshortvec(n, shortvec) -> int                           [procedure]
int -> subscrshortvec(n, shortvec)
        Returns or updates the n-th element of the integer vector intvec
        or shortvec. Since subscrintvec  is the class_apply of  intvecs,
        and  subscrshortvec  is  the   class_apply  of  shortvecs   (see
        REF * KEYS), these can also be called as

                intvec(n) -> int
                int -> intvec(n) or
                shortvec(n) -> int
                n -> shortvec(n)




-----------------------------------------------------
5  Generic Datastructure/Vector Procedures on Intvecs
-----------------------------------------------------

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




----------------
6  Miscellaneous
----------------

intvec_key -> key                                             [constant]
shortvec_key -> key                                           [constant]
        Hold  the  key   structures  for  both   integer  vectors   (see
        REF * KEYS).




----------
7  Example
----------

In all implementations  of Poplog the  integer size used  in intvecs  is
equivalent to the C language "int"  storage class on those machines  (ie
32 bit  signed quantities).  It  is possible,  therefore, to  pass  such
vectors to C programs as an argument for returning multiple values.  See
REF * EXTERNAL for information on invoking external functions.

Here is an  example of a  C function  which demonstrates the  use of  an
integer vector  to  return values.  The  function computes  the  first n
numbers of the Fibonacci series, which are deposited in the given  array
of integers v:

        void fib(n, v)
        int n, v[];
        {
            int i;

            v[0] = 0;   /* the first two numbers in the Fibonacci */
            v[1] = 1;   /* series are 0 and 1                     */

            for (i = 2; i < n; i++)
            {
                v[i] = v[i - 2] + v[i - 1];
            }
        }

Linking this function into Poplog involves using the exload syntax form:

        exload 'testload'
            [fib]      ;;; object file containing fib
            fib(2)     ;;; declares fib as having 2 arguments, no result
        endexload;

In order to call the function we must construct an intvec:

        vars iv = initintvec(15);

We now have a vector which corresponds  to the C array of integers,  and
we can call the function with the syntax word exacc:

        exacc fib(15, iv);

The vector iv is now filled with  the first 15 numbers of the  Fibonacci
series:

        iv =>
        ** <intvec 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377>

Shortvecs can be  used in the  above example if  the declaration of  the
parameter "v" to the C function "fib" were changed to

        short v[];




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