S*Basic String Parsing Toolkit
                      ==============================

            A number of string-related functions to help with
                            parsing text strings


They should be compatible with Qdos, Minerva and SMSQ/E, although, since
they use internal routines for some capabilities, there may be small
differences in their results depending on the OS used. Most of these
commands will be compatible with popular S*BASIC compilers, except in cases
where results are returned via the parameters. In some cases a small speedup
could have been achieved by writing them specifically for compilers and
SMSQ/E. Well, you have the source code, so its still possible to do that,
if you can and choose!


Usage:
------
In the section below, where a start% and end% par required: end% > start% in
which case the operation occurs from end to start instead:

        If no start/end given: starts first left to end right
        If start < 1 start = 1
        If end > len end = len
        If end < start go right to left

        If end < first char or start > last char, then do nothing

        ! as seperator after pattern => case-dependent


p% = INSTR%(pattern${, | !} string$ [{, | \} start% [, end%]])
        , Returns (abs) pos of next occ of pat in string
        \ Returns (abs) pos of first non-match of pat in str
        if start% > end% the search is reversed
        nul patterns or strings dont match anything!

        (\-option not implemented yet)


p% = QINSTR%(pattern${, | !} string$ [{, | \} start% [, end%]])
        , Returns (abs) pos of next occ of pat in string not in a quote
        \ Returns (abs) pos of next occ of pat in quoted string only
        if start% > end% the search is reversed


p% = ALTSTR%(list_of_alternative_chars${, | !} string$ [{, | \} start% [, end%]])
        , Returns (abs) pos of first match of alt chars in string
        \ Returns (abs) pos of first non-match of alt chars in string
        if start% > end% the search is reversed


Note: Case translation uses simple routine that only includes some of the
"foreign" characters. Basically it goes like this for lowercase (and
opposite for uppercase):

ut_lchr

        cmpi.b  #'A',d0
        blo.s   notran
        cmpi.b  #'Z',d0
        bls.s   mklo
        cmpi.b  #'Ä',d0         chr(160)
        blo.s   notran
        cmpi.b  #'Œ',d0         chr(171)
        bhi.s   notran

mkhi
        subi.b  #' ',d0
        bra.s   notran

mklo
        addi.b  #' ',d0

notran
        move.b d0,2(a6,a1.l)



Programmers notes:
------------------
Not all functions will be required in all cases in compiled programs,
therefore they have been re-written in a relatively modular fashion, so
that unwanted commands and their functional code may easily be removed. See
the link files for details. Most individual commands can be compiled on
their own, but since they rely on common library files, they may be
relatively bulky. If only one or two commands are required in a compiled
program, it is often better to omit the library files and insert your own
routines, eg to fetch and return parameters, etc.


Additional notes:
-----------------
Two link file versions are provided:

1. Str3TK_link provides for the use of the simple case translation scheme
described above.

2. StrTK3t provides for an alternative case translation scheme using a
lowercase table. This could be used if you have particular character case
translation needs. The code base is basically the same as for 1., above,
with the replacement of one file, lcstk_asm with lcstktt_asm, plus the
addition of a 256 byte translation table. (The table given here is just a
sample; if you need this facility, youll probably want to make your own!)

Note: lcstktt is labelled the same as lcstk so as be able to use the same
code base without change. The lcstktt version, however, smashes a0, and
this is not mentioned elsewhere in the code..


Software status
---------------
V0.01, pjw, 10 Mar 2001
V0.02, pjw, 16 Nov 2003, various times: improvements and additions
V0.03, pjw, 23 May 2019, modularised and improved

You may use these routines in your own QL-related programs, provided you
suitably and proportionally accredit the author(s). See otherwise the
conditions set out on my web site www.knoware.no

Note: This software is not finished, and may not behave in all
circumstances as described! Please ensure that it works to your
satisfaction for your specific purposes! (It works for me ;) If you are
able to improve the code, I should be very glad to have a copy!

pjw