HELP ARRAY_ADJOIN                               David Young
                                                August 2002

LIB * ARRAY_ADJOIN provides a procedure to adjoin - that is, put next to
each other - two 2-D arrays.

array_adjoin(arr1, reg1, arr2, reg2, side, arr3) -> arr3
        arr1 is the first input array. It must be 2-D. Arrays of packed
        byte or float data (as created by *newbytearray and
        *newsfloatarray) are handled most efficiently.

        reg1 gives the region of arr1 from which to take data. It may be
        a *boundslist type list or <false> to mean the whole of the
        array.

        arr2 and reg2 specify the second array and region in the same
        way.

        Below, reg1 and reg2 refer to the regions of the arrays from
        which data are to be taken, which may be the whole array.

        side specifies which side of reg1 to adjoin reg2 to. It may be
        one of the words "top", "right", "bottom", "left", or "t", "r",
        "b", "l". These refer to the sides of the region when the array
        is displayed conventionally as an image on the screen, using
        e.g. *rci_show. side may also be an integer, in which case (side
        mod 4) = 0,1,2,3 means t,r,b,l respectively.

        arr3 may be <false>, in which case a new output array is created
        and returned, or it may be an array in which the data are to be
        placed, in which case it is returned as the result. On exit,
        arr3(x, y) = arr1(x, y) for all (x, y) within reg1;
        arr3(x+xs, y+ys) = arr2(x, y) for all (x, y) within reg2, where
        xs and ys are the shifts necessary to move the data from reg2 to
        lie beside the data from reg1.

        If arr3 is an array on entry, its boundslist must contain the
        region in which data are to be stored.


--- $popvision/help/array_adjoin
--- Copyright University of Sussex 2002. All rights reserved.