INSERT by Joe Horn

PURPOSE: Inserts an object into a list at any desired position.

SYNTAX: {list} <position> <object>  -->  { new list }

        Note: The syntax is identical to the PUT command's syntax, and
        the result is similar to PUT, with one difference: instead of
        *replacing* the old object at <position>, the new <object> is
        *inserted* there, pushing the old object (and everything after
        it) further down the list.  Therefore INSERT makes a list's
        SIZE grow by 1, whereas PUT leaves it the same.

Note:   Although this program allows you to "insert" an object at the
        beginning or end of a list, it is faster to use + or SWAP +.

EXAMPLE: Insert 'X' into { 9 8 7 6 5 } at the 2nd position.

         { 9 8 7 6 5 }  2  'X'
         INSERT  -->  { 9 X 8 7 6 5 }

         How does this differ from PUT?

         { 9 8 7 6 5 }  2  'X'
         PUT  -->  { 9 X 7 6 5 }   notice that the 8 got replaced.

THEORY: There is a System RPL word designed to do this job, but it
        uses local variables, which makes it rather slow.  The INSERT
        program here is written in User RPL but is faster than the
        System RPL word, because it uses only fast stack operations.
        Herein lies a moral.  Software development time can be saved
        by the use of local variables, but program execution time is
        sacrificed.  Use only stack operations if you have the time
        and patience to do the step-by-step stack analysis required.

STACK ANALYSIS:

<<        { L1 L2 ... Ln }  pos  obj
ROT       pos  obj  { L1 L2 ... Ln }
OBJ\->    pos  obj  L1 L2 ... Ln  n
1 +       pos  obj  L1 L2 ... Ln  n+1
DUP       pos  obj  L1 L2 ... Ln  n+1  n+1
1 +       pos  obj  L1 L2 ... Ln  n+1  n+2
ROLL      pos  L1 L2 ... Ln  n+1  obj
OVER      pos  L1 L2 ... Ln  n+1  obj  n+1
DUP       pos  L1 L2 ... Ln  n+1  obj  n+1  n+1
3 +       pos  L1 L2 ... Ln  n+1  obj  n+1  n+4
ROLL      L1 L2 ... Ln  n+1  obj  n+1  pos
-         L1 L2 ... Ln  n+1  obj  n+1-pos
2 +       L1 L2 ... Ln  n+1  obj  n+3-pos
ROLLD     L1 L2 ... Ln  n+1
\->LIST   { L1 L2 ... Ln }
\>>