
		The GX Library


Brought to an HP48S/SX near you by

    Werner Huysegoms (werner.huysegoms@dg11.cec.be)

 0. Disclaimer

Use this library at your own risk.  The author can in no way be held responsible
for any damage or loss of information due to the use of this library.  The product
is provided as is, etc.  As with all unofficial software:
*** BACK UP YOUR MEMORY BEFORE INSTALLING THIS LIBRARY ***

 1. Abstract

Although called 'GX', this library will only work for an S/SX type of calculator.
It implements the most useful or most widely used new G/GX commands.  More commands
may be added in the future, but don't hold your breath over it.

 2. Installation/Purge

Use the following short program to correctly install the library (courtesy of
John H. Meyers):

    /<< -36 SF 1 /-> a /<< 'a' RECN CLOSEIO a />> SWAP STO />>

    checksum : #2809h
    bytes    : 59

Store it in a variable, such as LRECP (short for Library Receive in Port)
Then, do the following:

    1. hook up your HP to your PC
    2. On the PC, start your communications program. Make sure you're
       ready for step 4.
    3. On the HP, do <port> LRECP, with <port> = 0,1 or 2
    4. Start the transmit of the library
    5. When the library is transferred, do OFF/ON or ON-C to enable the library to attach.

libid : #3AB or 939
bytes : 2457.0
check : # 3CE3h

To purge, do the following:

:&:939 DUP DETACH PURGE


3.Command Overview

  The G/GX Differences apply only to *behaviour*.  In almost all cases, the coding is
  substantially different from the G/GX originals.  I do not think I would be allowed
  to just copy the code..

  HEAD
	Stack Diagram:

		In	Out
		------- -------
		list	first object in list
		string	string consisting of first character of input string

	Error Conditions: an empty list or an empty string result in an Invalid
                          Dimension Error
	G/GX Differences: None
	G/GX Improvement: constant execution time, much faster for long lists

	Example :
		{ 1.1 'X^2' #5 }
		HEAD
	->	1.1

  TAIL
	Stack Diagram:

		In	Out
		------- -------
		list	list without first object.  An empty list is simply returned.
		string  string without its first character.  An empty string is left
		 	unchanged.

	Example:
		"Wonderful"
		TAIL
	->	"onderful"

	Error Conditions: None
	G/GX Differences: None
	G/GX Improvement: None

  DOSUBS, NSUB, ENDSUB
	Stack Diagram:

		In		Out
		------- 	-------
		list prog1	list or empty
		list n prog2	list or empty

	prog1 may be:
	- a command that accepts 1-5 args of a specific type.  The command may be
	  builtin or reside in an add-on library.
	- a UserRPL program containing a single instruction equal to such a command
	- a User Defined Function
	prog2 may be:
	- any command
	- any UserRPL program
	For prog1, the HP48 can deduce the number of arguments.  For prog2, the number
	of arguments is explicitly specified.
	DOSUBS will take the first n elements of the list, and execute prog.  It will
	then take elements 2 .. n+1, and execute prog again, etc. till the subset that
	includes the last element in the list has been processed.  DOSUBS will then
	collect all results into a list, or return no result when there were none.
	In prog1 or prog2, you can use the variables NSUB and ENDSUB.  NSUB is a counter,
	and will be 1 for the first invocation of prog, 2 for the second, etc.  ENDSUB
	is the final value of NSUB.

	Error Conditions:
	- empty list -> Invalid Dimension Error
	- list size < n -> Invalid Dimension Error
	- n=0 -> Bad Argument Value
	- prog1 not as specified: Wrong Argument Count or Bad Argument Type
	G/GX Differences: None
	G/GX Improvement: separate and thus slightly faster code for n=1

	Example:
		{ 1 3 5 7 }
		\<< + \>>
		DOSUBS
	->	{ 4 8 12 }

  DOLIST
	Stack Diagram:

		In			Out
		------- 		-------
		list1 .. listn prog1	list or empty
		list1 .. listn n prog2	list or empty

	prog1 may be:
	- a command that accepts 1-5 args of a specific type.  The command may be
	  builtin or reside in an add-on library.
	- a UserRPL program containing a single instruction equal to such a command
	- a User Defined Function
	prog2 may be:
	- any command
	- any UserRPL program
	For prog1, the HP48 can deduce the number of arguments.  For prog2, the number
	of arguments is explicitly specified.  In fact, the definition of prog1 and prog2
	is identical to that of DOSUBS.  Moreover, for n=1, DOSUBS and DOLIST actually
	perform the same task - but DOSUBS lets you use NSUB and ENDSUB in the prog.

	Error Conditions:
	- lists not all the same size -> Invalid Dimension Error
	- empty list -> Invalid Dimension Error
	- n=0 -> Wrong Argument Count
	- prog1 not as specified: Wrong Argument Count or Bad Argument Type
	G/GX Differences: None
	G/GX Improvement: slightly faster overall; separate code for n=1

	Example: transpose a list of lists
		{ { 1 2 3 } { 4 5 6 } { 7 8 9 } }
		\<<
		  OBJ\->
		  \-> N
		  \<<
		    N
		    \<< N \->LIST \>>
		    DOLIST
		  \>>
		\>>
	->	{ { 1 4 7 } { 2 5 8 } { 3 6 9 } }

  STREAM
	Stack Diagram:

		In		Out
		------- 	-------
		list prog	results

	Stream extracts the first object from the list, and then enters the
	following loop:
	    do
	      extract next ob
	      execute prog
	    loop
	The results are left on the stack.

	Error Conditions: List contains less than 2 items -> Invalid Dimension
	G/GX Differences: None
	G/GX Improvement: None

	Example:
		{ 1 2 3 }
		\<< + \>>
		STREAM
	->	6

  SEQ
	Stack Diagram:

		In				Out
		------- 			-------
		object 'name' start end incr	list of results or nothing if no results

	The SEQ command is functionally equivalent too:
	    start end FOR name object EVAL incr STEP
	and collects all results into a list, if there were any.

	Error Conditions: None
	G/GX Differences:
        - this version of SEQ accepts a non-UserRPL program as 'object'.
        - it will work with programs stored in variables, and supplying the variable
          as 'object'.
	- 'name' can be either a local or a global name.  Be sure, however, that it is
          the same type in 'object'.
	G/GX Improvement: no UserRPL compile of level 5 argument any more, speeds up
        execution.

  DLIST
	Stack Diagram:

		In			Out
		------- 		-------
                { ob1 ob2 ob3 .. obn }	{ ob2-ob1 ob3-ob2 ob4-ob3 .. obn-obn-1 }

	Error Conditions: list size < 2 -> Invalid Dimension Error
	G/GX Differences: None

  SLIST
	Stack Diagram:

		In	Out
		------- -------
		list	sum of list elements

	Error Conditions: list size < 2 -> Invalid Dimension Error
	G/GX Differences: None

  PLIST
	Stack Diagram:

		In	Out
		------- -------
		list	product of list elements

	Error Conditions: list size < 2 -> Invalid Dimension Error
	G/GX Differences: None

  ADD
	Stack Diagram:

		In			Out
		------- 		-------
		list1 list2		list of sum of respective lists' objects
		ob  { ob1 ob2 .. obn }	{ ob+ob1 ob+ob2 .. ob+obn }
		{ ob1 ob2 .. obn }  ob	{ ob1+ob ob2+ob .. obn+ob }

	Error Conditions: empty list(s) -> Invalid Dimension Error
	G/GX Differences: None
	G/GX Improvement: None

  REVLIST
	Stack Diagram:

		In			Out
		------- 		-------
		{ ob1 ob2 .. obn }	{ obn .. ob2 ob2 }

	Error Conditions: None
	G/GX Differences: None
	G/GX Improvement: Much faster.

  SORT
	Stack Diagram:

		In	Out
		------- -------
		list	list sorted descendingly

	The list can contain the following items:
	. reals
	. units
	. UserRPL integers
	. strings
	. local/global names
	. list
	Every object in the list must be of the same type.  If that type is a list,
	the first object in that list is considered.  If that is again a list, *its*
	first object is considered and so on.
	
	Error Conditions:
	- List elements are not of the same type -> Bad Argument Type
	- Key is not 'comparable' -> Bad Argument Type
	G/GX Differences: None
	G/GX Improvement: Faster

	Example:

		1 64 START RAND NEXT 64 \->LIST
		SORT
	->	list of 64 random reals, sorted descendingly

		{ { A \<< A \>> }
		  { C \<< C \>> }
		  { B \<< B \>> }
		}
		SORT
	->	{ { A \<< A \>> }
		  { B \<< B \>> }
		  { C \<< C \>> }
		}

4.Command peculiarities

Some things you have to keep in mind:

ADD: When level 2 contains a tagged list, and level one any object save a (possibly
     tagged) list, ADD actually adds the object to the list.  This is a bug present
     in the G/GX version as well.
     Thus: TAG: { 1 2 } 5 ADD results in { 1 2 5 } where it should have been { 6 7 }

DOSUBS : { 1 2 3 } << DUP >> DOSUBS -> Wrong Argument Count
         { 1 2 3 } 1 << DUP >> DOSUBS -> { 1 1 2 2 3 3 }
         Commands which accept ANY type of argument need the argument count
         explicitly specified.

         { 1 2 3 } 1 1 DOSUBS -> Bad Argument Type
         { 1 2 3 } 1 << 1 >> DOSUBS -> { 1 1 2 1 3 1 }
         Only commands or RPL programs are accepted

         { list } 0 << CMD >> DOLIST -> Wrong Argument Count
         { list } 0 << CMD >> DOSUBS -> Bad Argument Value

STREAM accepts any object type, not just commands or RPL progs.

DOLIST, DOSUBS, SEQ give NO result (not even an empty list) when the stack
size after execution is smaller or equal to the start size.

SORT does not give an error for { [1] }, for instance, meaning that in the
case of a single object, its type is NOT checked!

5.Ramble

The library has been constructed with the following guidelines borne in mind:
- G/GX compatibility, even when the command's behaviour is not logical.
  See 'peculiarities' above.
- small code size
- speed of execution
- supported entries only
All of these guidelines have at times been disobeyed..
Also, I have tried to use SysRPL whenever possible, instead of Machine Language.
That's what the language was developed for in the first place..
It would be possible to speed up SORT considerably, for instance, at the
expense of a few Kbytes of machine language.  Usually, the current version
will do, however.

6.Comments

Comments, criticisms and praise may be addressed to:

    werner.huysegoms@dg11.cec.be
or  werner_huysegoms@my-dejanews.com

Enjoy!