Procedure

     LNKXSL ( LNK, extract sublist from list  )

     SUBROUTINE LNKXSL ( HEAD, TAIL, POOL )

Abstract

     Extract a specified sublist from a list.

Required_Reading

     None.

Keywords

     LIST

Declarations

     IMPLICIT NONE

     INTEGER               LBPOOL
     PARAMETER           ( LBPOOL = -5 )

     INTEGER               HEAD
     INTEGER               TAIL
     INTEGER               POOL ( 2,  LBPOOL : * )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HEAD,
     TAIL       I   Head and tail nodes of a sublist to be extracted.
     POOL      I-O  A doubly linked list pool.

Detailed_Input

     HEAD,
     TAIL     are, respectively, the head and tail nodes of a
              sublist to be extracted.

     POOL     is a doubly linked list pool.

Detailed_Output

     POOL     is the input pool, with the following
              modifications:

                 -- The sublist bounded by HEAD and
                    by TAIL is now a separate list from
                    the list that originally contained it.

                 If on input, HEAD was preceded by the node
                 PREV, and tail was followed by the node
                 NEXT, then on output

                 -- The successor of PREV is NEXT.
                 -- The predecessor of NEXT is 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 either of HEAD or TAIL are not valid node numbers, the
         error SPICE(INVALIDNODE) is signaled. POOL will not be
         modified.

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

     3)  If TAIL cannot be reached by forward traversal of the list
         containing HEAD, the error SPICE(INVALIDSUBLIST) is signaled.
         POOL will not be modified.

Files

     None.

Particulars

     Extracting a sublist from a list is necessary when a list is
     to be re-arranged in some way. For example, to move a node
     in a list to the head of the list, the node (which is a
     singleton sublist) is first extracted from the list containing
     it, then inserted before the head of the list.

Examples

     1)  Let POOL be a doubly linked list pool, and let

            9 <--> 8 <--> 4 <--> 2000 <--> 1

         be a list in POOL. To extract the sublist

            4 <--> 2000

         the call

            CALL LNKXSL ( 4, 2000, POOL )

         can be used. After the call is made, POOL will contain the
         separate lists

            9 <--> 8 <--> 1

         and

            4 <--> 2000


     2)  Let POOL be a doubly linked list pool, and let

            9 <--> 8 <--> 4 <--> 2000 <--> 1

         be a list in POOL. To move the node 2000 to the
         head of the list, the code fragment

            CALL LNKXSL ( 2000, 2000, POOL )
            CALL LNKILB ( 2000, 9,    POOL )

         can be used. The resulting list will be

            2000 <--> 9 <--> 8 <--> 4 <--> 1

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.

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.

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