List Commands Library for 50g

[DavidM]

Although I was initially skeptical about adding stack manipulation commands to the library, I've considered that it can be rationalized somewhat by recognizing that it's often necessary to construct list contents on the stack during the building and editing process. As such, I've revisited some commands that I worked on in the early stages of the library, but subsequently decided to remove as "non-list-centric" commands.

I've got the following in a "test build" version of the library, and would greatly appreciate feedback concerning their potential inclusion into another release sometime in the future. I should add that these are generally good performers -- NMDUP can create 174 replications of 174 stack items (30276 total items) on a 50g in 0.26 second. Are the below commands worth including in the library? Here's their descriptions:

______________________________________________________________________________

NMDUP (Duplicate a Group of Stack Items Multiple Times)

Input:
N+2: <object 1>
...
3: <object N>
2: N (the size of the group of objects to replicate)
1: M (the number of replications after execution)

Output:
<NxM objects on the stack>

Using the first N objects at the bottom of the stack as the basis, creates a total of M copies of the entire group. Any objects above the identified group when the command is executed are left intact above the replicated output of the command. If M is 0, the identified group is deleted (similar to DROPN). If M is 1, the original group is left in place.

Examples:
1 2 3 4 5 3 0 NMDUP => 1 2
1 2 3 4 5 3 1 NMDUP => 1 2 3 4 5
1 2 3 4 5 3 2 NMDUP => 1 2 3 4 5 3 4 5
5 6 7 8 4 4 NMDUP => 5 6 7 8 5 6 7 8 5 6 7 8 5 6 7 8


______________________________________________________________________________

NMROT (Rotate a Group of Stack Items)

Input:
N+2: <object 1>
...
3: <object N>
2: N (the size of the group of objects to rotate)
1: M (the number of positions to shift)

Output:
<the same N objects, rotated as indicated>

Rotates the lowest N objects on the stack through M positions. Positive M shifts stack levels up, negative M shifts down. A value of 0 for N makes no changes to object positions. Likewise, a value of 0 for M leaves all stack levels intact. Using 1 or -1 for M is the equivalent of ROLL or ROLLD, which are more efficient in that situation. NMROT is best used when the rotation count is 2 or greater.

The standard UserRPL ROT command is equivalent to 3 1 NMROT.

Examples:
1 2 3 4 5 0 0 NMROT => 1 2 3 4 5
1 2 3 4 5 3 0 NMROT => 1 2 3 4 5
1 2 3 4 5 3 1 NMROT => 1 2 4 5 3 (Note: same as ROT)
1 2 3 4 5 3 -1 NMROT => 1 2 5 3 4 (Note: same as UNROT)
1 2 3 4 5 6 7 8 9 5 2 NMROT => 1 2 3 4 7 8 9 5 6


______________________________________________________________________________

SWPXY (Swap Two Individual Stack Levels)

Input:
<objects on stack>
2: Y (second stack level to swap)
1: X (first stack level to swap)

Output:
<same objects that were previously above SL2, with the indicated levels swapped>

Swaps two arbitrary stack levels as indicated by the stack level numbers given in SL1 and SL2. The X and Y values are the level numbers before adding X and Y to the stack. Both stack levels given as input must have something in them or an error will be generated. If X and Y are equal, no changes to stack items are made.

Examples:
5 4 3 2 1 5 5 SWPXY => 5 4 3 2 1
5 4 3 2 1 1 3 SWPXY => 5 4 1 2 3
5 4 3 2 1 3 4 SWPXY => 5 3 4 2 1
5 4 3 2 1 4 2 SWPXY => 5 2 3 4 1


______________________________________________________________________________

DRPXY (Drop a Range of Stack Levels)

Input:
2: Y (last stack level to drop)
1: X (first stack level to drop)

Output:
<the same stack data with the indicated levels dropped>

Drops the range of stack levels indicated, leaving all others intact. The indicated stack levels are inclusive; they and all levels in between will be dropped upon executing the command. The X and Y values are the level numbers before adding X and Y to the stack.

Examples:

5 4 3 2 1 1 1 DRPXY => 5 4 3 2
5 4 3 2 1 5 5 DRPXY => 4 3 2 1
5 4 3 2 1 1 5 DRPXY => <empty stack>
5 4 3 2 1 4 2 DRPXY => 5 1


______________________________________________________________________________

REVN (Reverse Stack Entries)

Input:
N+1: <object 1>
...
2: <object N>
1: N (the size of the group of objects to reverse)

Output:
<the same objects 1-N as above, reversed>

Reverses the order of the lowest N objects on the stack. N of 0 or 1 has no effect on the stack objects.

Examples:
1 2 3 4 5 0 REVN => 1 2 3 4 5
1 2 3 4 5 1 REVN => 1 2 3 4 5
1 2 3 4 5 4 REVN => 1 5 4 3 2
1 2 3 4 5 5 REVN => 5 4 3 2 1


______________________________________________________________________________

...and finally, there's another one that is list-specific. I've used this during my testing of many of the commands in the library, and thought that it might be useful to others as well.

______________________________________________________________________________

SLST→ (Safe LIST→)

Input:
1: { list of 0 or more objects }

Output:
<list objects, 1 per stack level>
1: count of objects in the list

SLST→ essentially does the same thing as LIST→, with one difference: the exploded list objects are no longer embedded in the original list object in the TEMPOB area of the calculator's memory, and are thus no longer subject to causing extended pauses when the calculator processes a Garbage Collection event. SLST→ is less efficient with memory than LIST→, so it is slightly slower to process. But with large lists, the extra time required to complete SLST→ is minor when compared to the delay caused by any subsequent Garbage Collection event after the list has been exploded.

The Garbage Collection issue can be avoided by saving the list to a global variable first (ie. put it in a saved variable somewhere in HOME), but you don't always want to do that. SLST→ can be useful when you don't want to save/delete a list just to process its contents.

Examples:
12345 1000 NDUPN →LIST LIST→ « MEM » TEVAL => 33.3s on a 50g
12345 1000 NDUPN →LIST SLST→ « MEM » TEVAL => 0.3s on a 50g

Note: the above times are only for the MEM command. MEM always triggers a Garbage Collection event, and that's what I was looking to isolate above. Similar timings just for LIST→ and SLST→ in the above sequences show results of 0.05s and 0.31s, respectively. So while SLST→ is definitely slower than LIST→, the difference is minor when compared to the delay caused by the GC event.