Procedure

     LNKILA ( LNK, insert list after node )

     SUBROUTINE LNKILA ( PREV, LIST, POOL )

Abstract

     Insert the list containing a specified node into a another list,
     following a specified node.

Required_Reading

     None.

Keywords

     LIST

Declarations

     IMPLICIT NONE

     INTEGER               LBPOOL
     PARAMETER           ( LBPOOL = -5 )

     INTEGER               PREV
     INTEGER               LIST
     INTEGER               POOL ( 2,  LBPOOL : * )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     PREV       I   Node after which a new list is to be inserted.
     LIST       I   Node in the list to be inserted.
     POOL      I-O  A doubly linked list pool.
     LBPOOL     P   Lower bound of pool column indices.

Detailed_Input

     PREV     is a node in a list. PREV is permitted to be
              nil, in which case POOL is not modified.

     LIST     is a node in the list to be inserted. The entire
              list containing the node LIST is to be inserted
              into the list containing PREV. The inserted list
              will be located between PREV and its successor,
              if any.

     POOL     is a doubly linked list pool.

Detailed_Output

     POOL     is the input pool, with the following
              modifications:

                 Let HEAD and TAIL be the head and tail nodes of
                 the list containing LIST. Then on output

                    -- The successor of PREV is HEAD.
                    -- The predecessor of HEAD is PREV.


                 Let NEXT be the node that on input was the
                 successor of PREV; if NEXT exists, then on
                 output

                    -- The successor of TAIL is NEXT.
                    -- The predecessor of NEXT is TAIL.

                 If NEXT is nil, the forward pointer of the
                 inserted sublist is set to the negative of
                 the head of the list containing PREV.

Parameters

     LBPOOL   is the lower bound of the column indices of the POOL
              array. The columns indexed LBPOOL to 0 are reserved
              as a control area for the pool.

Exceptions

     1)  If LIST is not a valid node number, the error
         SPICE(INVALIDNODE) is signaled. POOL will not be
         modified.

     2)  If PREV is positive but is not a valid node number, the error
         SPICE(INVALIDNODE) is signaled. POOL will not be
         modified.

     3)  It is not an error for PREV to be non-positive; if it is,
         the call to this routine does not affect the pool.

     4)  If either of PREV or LIST are valid node numbers but are not
         allocated, the error SPICE(UNALLOCATEDNODE) is signaled. POOL
         will not be modified.

     5)  If LIST belongs to the same list as does PREV, this routine
         may fail in mysterious ways. For efficiency, this error
         condition is not checked.

Files

     None.

Particulars

     This routine is used for augmenting lists by inserting other
     lists into them. The case of insertion of a single allocated
     node is not special: this is insertion of a singleton list.

     To insert a list into a list BEFORE a specified element, use the
     routine LNKILB.

Examples

     1)  Let POOL be a doubly linked list pool that contains the lists

             3 <--> 7 <--> 1    and    500 <--> 2 <--> 80

         To insert the second list into the first after node 7, use the
         call

             CALL LNKILA ( 7, 500, POOL )

         The resulting list will be:

             3 <--> 7 <--> 500 <--> 2 <--> 80 <--> 1


     2)  Let POOL be a doubly linked list pool that contains 5 nodes.
         The sequence of calls

            TAIL = 0

            DO I = 1, 5
               CALL LNKAN  ( POOL, NODE       )
               CALL LNKILA ( TAIL, NODE, POOL )
               TAIL = NODE
            END DO

         builds the list

             1 <--> 2 <--> 3 <--> 4 <--> 5

         Note that the first call to LNKILA does not cause an error
         to be signaled, even though TAIL is 0 at that point.

Restrictions

     1)  Linked list pools must be initialized via the routine
         LNKINI. Failure to initialize a linked list pool
         will almost certainly lead to confusing results.

     2)  For efficiency, discovery check-in is used in this routine.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 1.0.1, 24-NOV-2021 (JDR)

        Edited the header to comply with NAIF standard.

        Added note about efficiency in $Restrictions section.

    SPICELIB Version 1.0.0, 19-DEC-1995 (NJB) (WLT)