SELECT
                                    ======

Given a number of strings, return the number of the first string matching item


Note: The command has been named CHOICE% as SELECT would be unacceptable
to S*BASIC. To confuse matters further, I have lumped CHOICE% together
with another command, written years ago, called CHOICE, as they are
similar in some respects. See CHOICE_txt for information on CHOICE.

Still, you have the source code and can call them whatever you like!


Usage:
------
item% = CHOICE%(cmptype%, term$, choice1$, choice2$, .. choiceN$)

Where item% is the result, 0 => not found, 1..N => found
      cmptype% refers to Qdos comparison types 0..3 (see below)
      term$ is the comparison item
  and choice1$..choiceN$ are the items to compare with

Note: term$ and choice..$ are fetched and treated as strings. Normal
coercion rules apply.


In Use
------
Qdos and SMSQ/E currently dont support a string version of SELect ON, so I
knocked up this hack to work around it:

Ideally it would look something like this

SELect ON item$
 = 'abc': Do_abc
 = 'def': Do_def
 = 'rst': Do_rst
 = 'xyz': Do_xyz
 = remainder: Do_nothing
END SELect

Here is an alternative:
item$ = 'rst'
..
it% = CHOICE%(0, item$, 'abc', 'def', 'rst', 'xyz')
:
SELect ON it%
 = 0: Do_nothing
 = 1: Do_abc
 = 2: Do_def
 = 3: Do_rst            <- this is what the above example will do
 = 4: Do_xyz
END SELect

This simple hack doesnt do ranges or some of the other fancy stuff SELect
can do with numbers, but for many cases it should be sufficient.

Savages may still like to use the following construct (I know I would):

item$ = 'rst'
..
it% = CHOICE%(0, item$, 'abc', 'def', 'rst', 'xyz')
:
ON it% + 1 GO TO 1000, 100, 200, 300, 400, 500
(Where 1000 is the not found routine)


CHOICE% has one finesse up its sleeve: You can specify the comparison
type: Qdos types 0..3:


Types of Comparison
-------------------
Comparisons may be:

Type 0  Made directly on a character by character basis

Type 1  Made ignoring the case of the letters

Type 2  Made using the value of any embedded numbers

Type 3  Both ignoring the case of letters and using the value of embedded
        numbers.

More details may be found in the QDOS/SMS Reference Manual, sections 16 - 19.
This may not apply to Minerva, which has its own ideas on string comparison!


Software Status
---------------
V0.01, pjw, 2020 Jun 20
V0.02, pjw, 2020 Jun 22, renamed to CHOICE%

               Conditions of use and DISCLAIMER as per Knoware.no