Procedure

     INSSUB ( Insert a substring )

     SUBROUTINE INSSUB ( IN, SUB, LOC, OUT )

Abstract

     Insert a substring into a character string at a specified
     location.

Required_Reading

     None.

Keywords

     ASSIGNMENT
     CHARACTER
     STRING

Declarations

     IMPLICIT NONE

     CHARACTER*(*)    IN
     CHARACTER*(*)    SUB
     INTEGER          LOC
     CHARACTER*(*)    OUT

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     IN         I   Input string.
     SUB        I   Substring to be inserted.
     LOC        I   Position at which substring is to be inserted.
     OUT        O   Output string.

Detailed_Input

     IN       is an input character string, into which a substring
              is to be inserted.

     SUB      is the substring to be inserted. Leading and trailing
              blanks are significant.

     LOC      is the index in the input string at which the substring
              is to be inserted. The range of LOC is 1:LEN(IN). To
              append to the string, set LOC equal to LEN(IN)+1.

Detailed_Output

     OUT      is the output string. This is equivalent to the
              string that would be created by the concatenation

                 OUT = IN(1:LOC-1) // SUB // IN(LOC: )

              If the output string is too long, it is truncated
              on the right.

              OUT may overwrite IN. OUT may NOT overwrite SUB.

Parameters

     None.

Exceptions

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

Files

     None.

Particulars

     Shift the end of the input string, beginning with LOC, to the
     right, leaving space for the substring. Then insert the substring
     into the vacated space in the middle of the string. This has
     the same effect as the concatenation

        OUT = IN(1:LOC-1) // SUB // IN(LOC: )

     Because this operation is not standard for strings of length (*),
     this routine does not use concatenation.

Examples

     The numerical results shown for these examples may differ across
     platforms. The results depend on the SPICE kernels used as
     input, the compiler and supporting libraries, and the machine
     specific arithmetic implementation.

     1) The following table illustrates the use of INSSUB.

           IN                SUB      LOC    OUT
           ----------------- -------  ---    ------------------------
           'ABCDEFGHIJ'      ' YXZ '    3    'AB XYZ CDEFGHIJ'
           'The rabbit'      'best '    5    'The best rabbit'
           ' other woman'    'The'      1    'The other woman'
           'An Apple a day'  ' keeps'  15    'An Apple a day keeps'
           'Apple a day'     'An '      0     An error is signaled.
           'Apple a day'     'An '     -3     An error is signaled.
           'An Apple a day'  ' keeps'  16     An error is signaled.


     2) INSSUB could be used to insert substrings at any position
        within the declared length of the input string. Use it to
        add an ascii arrow (--->) at the end of the string.


        Example code begins here.


              PROGRAM INSSUB_EX2
              IMPLICIT NONE

        C
        C     Local parameters.
        C
              INTEGER               STRSZ
              PARAMETER           ( STRSZ = 20 )

        C
        C     Local variables.
        C
              CHARACTER*(STRSZ)     STRIN
              CHARACTER*(STRSZ)     STROUT

        C
        C     Assign the input string.
        C
              DATA                  STRIN / '0123456789         .' /


        C
        C     Insert a substring at index 17. This should leave 5
        C     blanks after the sequence of numbers. Note that the
        C     resulting string is truncated.
        C
              CALL INSSUB ( STRIN, '--->', 17, STROUT )

              WRITE(*,*) 'Input string:  ', STRIN
              WRITE(*,*) 'Output string: ', STROUT

              END


        When this program was executed on a Mac/Intel/gfortran/64-bit
        platform, the output was:


         Input string:  0123456789         .
         Output string: 0123456789      --->

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     H.A. Neilan        (JPL)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)

Version

    SPICELIB Version 1.2.0, 01-OCT-2021 (JDR) (NJB)

        Added IMPLICIT NONE statement.

        Updated long error message for LOC out of range check,
        providing valid range of values.

        Edited the header to comply with NAIF standard. Added complete
        code example.

    SPICELIB Version 1.1.0, 24-OCT-1994 (NJB)

        Bug fixes made. Now does discovery check-in. Header sections
        re-arranged. Some clean-up of header format done.

    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) (HAN)