(49g) (48gii) (49g+) (50g) List Extensions Library

[DavidM]

ListExt (List Extensions) Library
(49g, 48gII, 49g+, 50g)

What is it?

The ListExt library contains a variety of list and string processing commands that are available for use within User RPL programs and/or direct execution from the library's menu. The commands are generally designed as utility functions that are meant to complement list commands that are built-in as well as those provided by other libraries such as GoferLists.

Background info

In April of 2017, Pier4r started a thread containing a collection of challenges intended to promote the use of list processing to solve a variety of problems. The challenges themselves were mixed in terms of difficulty, but they all proved to be a good way to force myself to use list-focused approaches to RPL problem-solving. The more I worked on the challenges, the more I started to see the potential usefulness of extending RPL's list-processing commands to include some additional standardized commands. Certain types of functions seemed to come up repeatedly as convenient intermediate steps when using a list-focused approach. Those common functions became the initial group of commands included in the ListExt library. Collaboration with other forum members resulted in new ideas for additional commands as well as different ideas about how the existing ones could be utilized.

Why do I need this?

If you don't write RPL programs that make use of lists, then you most likely don't need ListExt (although some of the string commands may still be useful for you). If you do use lists in your programs, there's almost certainly going to be a good use for many of the commands presented here. Some of the commands in the library will only save you a few steps, but they are still handy for maintaining readability and are generally faster than their User RPL counterparts. A few of the commands can replace large blocks of code, and some others are significantly faster than you could obtain even with the fastest "standard" RPL approaches. Finally, a few more commands are very similar to built-in functions, but are more forgiving of edge cases such as empty or single-element lists. A brief description of each command is included below, but more complete command syntax and examples are given in the attached documentation.

Performance focus

RPL lists can be quite useful for certain types of problems, but the inherent nature of how they are stored and accessed can sometimes make them slow to process. As a result, one of the common themes of the ListExt library is to put a higher priority on performance than code size. One consequence of this is that many of the commands contain either critical sections or are mostly written in Saturn assembly. While this has helped performance, it has also made the library fairly large when compared to others that don't contain as much Saturn code. The string commands are included in this as well, with most of them executing orders of magnitude faster than standard (or even System) RPL equivalents.

Thanks

The ListExt library has definitely been a collaboration of many individuals who have contributed in a variety of ways, and I'm grateful for the time and effort that others have put into this project. In particular, Pier4r provided the initial inspiration through his challenges and contributed greatly to the command list as well as putting in significant time for testing and trying out new ways to use the commands. John Keith helped to "push the envelope" a bit on an entire section of commands (the string ones, in particular), and spent a good amount of time doing some testing, suggesting more commands, and discussing options as well. Gilles59 contributed not only the ideas for DOCOMB and DOPERM (and pointed out some important issues with them), but also showed several great uses of some of the commands (particularly the cryptarithms). BruceH had some great ideas for commands as well as instigating the ideas that eventually grew into the current menu presentation for the library. Joe Horn threw in some great insight, especially related to the garbage collection issues with an exploded list. 3298 dropped by with some SysRPL optimizations, and David Hayden added a "voice of reason" to several discussions, including that of the ever-increasing scope. ttw noted the need (and proper edge-case handling) for LPROD, and several others contributed to various mini-discussions. Thanks to all for your ideas, participation, and support!

ListExt at hpcalc.org

______________________________________________________________________________
COMMAND SUMMARY

List Creation (CREAT menu)
LSEQ - creates a list of <count> integers as a sequence from 1..<count>
LSEQR - creates a list of integers for the range specified
LASEQ - creates a numeric sequence by repetitive addition of a constant
LMSEQ - creates a numeric sequence by repetitive multiplication by a constant
LDSEQ - creates a numeric sequence by repetitive division by a constant
LMRPT - repeats list contents as indicated by count

List Editing (EDIT menu)
LDDUP - removes duplicates from a list
LPOP - retrieves the first element in a list while leaving the rest on the stack
LPOPR - retrieves the last element in a list while leaving the rest on the stack
LPUSH - adds object to front of list
LPSHR - adds object to end of list
LPICK - returns a list containing identified elements in specified order

LREPL - replaces list elements with a substitute object as indicated
LINSR - inserts 1 or more elements into a list as indicated
LRMOV - removes 1 or more elements from a list as indicated
LFRST - returns the first <n> elements of a list
LLAST - returns the last <n> elements of a list
LRCL - recalls objects identified by variables in a list

Element Arrangement (ARRNG menu)
LROLL - rolls the list (equivalent to 1 LROT)
LRLLD - "roll down" the list (equivalent to -1 LROT)
LROT - rotates list elements left or right as indicated by count
LSWAP - swaps the positions of two list elements
LSSR - reverses the order of a sub-sequence within a list
LSHUF - shuffles the contents of a list

KSORT - Sorts a list based on keys from a separate list
REV - Reverses the individual elements of a list, string, or number

Element Grouping (GROUP menu)
LCLLT - collates a list of sublists
LDIST - distributes list items into sublists (reciprocal of LCLLT)
LGRP - replaces repeated elements with a single instance
LRPCT - list with LGRP elements and another list of the count of each element
LRPC→ - restores a list that was grouped with LRPCT
LSDIV - subdivides a list into <count> sublists

SPLIT - splits a list, string, or number as indicated into two parts
RSPLT - splits a list, string, or number as indicated from the right into two parts
LXIL - explodes inner sublists into individual elements (non-recursive)
LXILR - recursive version of LXIL
SLST→ - LIST→ that avoids Garbage Collection issues for large lists

List Testing (TEST menu)
LCNT - counts objects in a list
LEQ - checks list items to see if any do not match
MPOS - returns a list of all positions of an object in a list, or a substring in a string
MPOSL - returns a list of all positions of an object in a list or its sublists
LNRML - substitutes ROM opcodes in a list for numeric natural numbers in the range -9..9
LSAME - Executes LNRML on two lists then SAME

Combinatorics (COMB menu)
DOCOMB - feeds indicated combinations of a list to a user-supplied program
DOPERM - feeds indicated permutations of a list to a user-supplied program

List Math (LMATH menu)
LSUM - ΣLIST that also accepts lists with 0 or 1 element
LPROD - ΠLIST that also accepts lists with 0 or 1 element
LMAX - returns the maximum value contained in a list
LMIN - returns the minimum value contained in a list

String/Number Conversion (STRNG menu)
CHR+ - adds an offset to the CHR value of each character of a string
LCASE - converts upper case characters in a string to lower case
UCASE - converts lower case characters in a string to upper case
RPTCHR - creates a string of repeated characters
I→NL - converts an integer to a list of numbers
NL→I - converts a list of numbers to an integer

S→NL - converts a string to a list of numbers
NL→S - converts a list of character numbers to a string
S→SL - converts a string to a list of characters
SL→S - converts a list of characters to a string
I→BL - converts an integer into a list of remainders after repeated division by constant
BL→I - converts a list of remainders from base conversion into an exact integer

Stack Operations (STACK menu)
NMDUP - replicates a group of stack levels as indicated
NMROT - rotates stack items as indicated
SWPXY - swaps the indicated stack levels
DRPXY - drops the stack levels indicated in the range from X to Y
REVN - reverses the order of N stack levels
REVXY - reverses the order of stack levels X through Y

About1423 - Library short description and version information
Unins1423 - Detaches and deletes the ListExt library

Not included in the menu:
MENU1423 - activates the ListExt menu

[pier4r]

Finally, NICE !

Code:


NICE
  @takes a list in input
  \<< 
    SIZE ALOG 1 SWAP 
    START
       "nice!"
    END
  \>>