Procedure

     INSLAC ( Insert at location in a character array )

     SUBROUTINE INSLAC ( ELTS, NE, LOC, ARRAY, NA )

Abstract

     Insert one or more elements into a character array at the
     indicated location.

Required_Reading

     None.

Keywords

     ARRAY
     ASSIGNMENT

Declarations

     IMPLICIT NONE

     CHARACTER*(*)    ELTS  ( * )
     INTEGER          NE
     INTEGER          LOC
     CHARACTER*(*)    ARRAY ( * )
     INTEGER          NA

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     ELTS       I   Elements to be inserted.
     NE         I   Number of elements to be inserted.
     LOC        I   Location of the first inserted element.
     ARRAY     I-O  Input/output array.
     NA        I-O  Number of elements in the input/output array.

Detailed_Input

     ELTS     contains one or more elements which are to be
              inserted into the input array.

     NE       is the number of elements to be inserted.

     LOC      is the location in the array at which the first
              element of ELTS is to be inserted. LOC must be
              within the interval [1, NA+1]. To append to
              ARRAY, set LOC equal to NA+1.

     ARRAY    on input, is the original array.

     NA       on input, is the number of elements in ARRAY.

Detailed_Output

     ARRAY    on output, is the original array with the elements
              of ELT inserted into positions LOC through LOC+NE-1.
              The original elements in these positions are moved
              back to make room for the inserted elements. If the
              new elements are longer than the declared lengths
              of the elements of ARRAY, the new elements are
              truncated on the right.

     NA       on output, is the number of elements in ARRAY.

Parameters

     None.

Exceptions

     1)  The dimension of the array is set equal to zero if its
         input value is less than one.

     2)  If LOC is not in the interval [1, NA+1], the error
         SPICE(INVALIDINDEX) is signaled.

     3)  If the number of elements to be inserted is less than one,
         the array is not modified.

Files

     None.

Particulars

     The elements in positions LOC through LOC+NE-1 are moved back
     by NE spaces to make room for the new elements, which are then
     inserted into the vacated spaces.

Examples

     Let

           ELTS(1) = 'very'       NA = 4      ARRAY(1) =  'I'
           ELTS(2) = 'big'                    ARRAY(2) =  'saw'
           ELTS(3) = 'brown'                  ARRAY(3) =  'a'
                                              ARRAY(4) =  'dog'

     Then the call

           CALL INSLAC ( ELTS, 3, 4, ARRAY, NA )

     yields the following result:

           NA = 7      ARRAY(1) = 'I'
                       ARRAY(2) = 'saw'
                       ARRAY(3) = 'a'
                       ARRAY(4) = 'very'
                       ARRAY(5) = 'big'
                       ARRAY(6) = 'brown'
                       ARRAY(7) = 'dog'


     The following calls to INSLAC signal errors.

     CALL INSLAC ( ELTS, 3, -1, ARRAY, NA )
     CALL INSLAC ( ELTS, 3,  6, ARRAY, NA )
     CALL INSLAC ( ELTS, 3,  2, ARRAY, -1 )
     CALL INSLAC ( ELTS, 3, -1, ARRAY, -1 )

Restrictions

     1)  The array must be large enough to contain both the original
         and the inserted elements.

Literature_References

     None.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)

Version

    SPICELIB Version 1.1.0, 05-JUN-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 1.0.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.0.0, 31-JAN-1990 (IMU)