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

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

                               All-in version

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

        {parameter$ | parameter%}
        parameter$ can either be a string$ or an integer%,
        representing the ascii code of a single character


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% = 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

        inst2: \ p% = INSTR%(' ', " start"\) ; p% -> 's' (faster than ALTSTR%)
        (\-option not implemented yet)


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


        Take the fiddle out of string slicing with these handy commands!

In the following, parameters have a slightly different meaning:

        if start% > end% the parameters are reversed
        if end% < 1 or start% > len, no action taken (see individually)
        if start% < 1 start set to 1
        if end% > len, end set to len


s$ = REMOVE$(start%, end%, string$)
        Copys string$ into s$, with chars start% to end%, inclusive, removed.
        If start% & end% outside range, string is returned intact


s$ = EXTRACT$(start% to end%, string$)
        Extracts slice of string$ from start% to end%
        If start% & end% outside range, a nul string is returned


s$ = INSERT$(at%, substring$, mainstring$)
        Inserts a substring in mainstring after position at%
        If at% < 0: at% = 0. If at% > len(mainstring$): at% = len

Simple string parameter


s$ = DESPACE$(string$)
        Returns string$ with leading spaces removed

s$ = DETAB$(string$)
        Returns string$ with leading spaces and tabs removed


s$ = REVERSE$(string$)
        Returns string$ reversed


s$ = LOWER$(string$)
        Returns lowercased string$


s$ = UPPER$(string$)
        Returns uppercased string$


Misc parameters


s$ = INSERT$(position%, substring$, mainstring$)
        Returns mainstring$ with substring$ inserted at position%


r% = CMP%(str1$, str2$ [, comptype% [, table]])
        Returns comparison of two strings using Qdos comparison types
        0..3 and/or table, where table is a 256 byte translation table
        (see CMP_txt for details)

s$ = JUST$(jst%, width%, text$)
        Justify text in a field
     where
        jst% = -1 => left justified
        jst% =  0 => centered
        jst% =  1 => right justified

        width% = field width 0..32k - 2
     and
        text$ is string to be justified


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:
-----------------
To re-assemble this toolkit you need to download the following toolkits
from the string section. They contain all the source files for this
toolkit.

CMP
JUST
Str1TK
Str2TK
Str3TK

And dont forget the library! lib03

Unzip them all into the same directory, preferably the root
directory of some drive like ram1_ or dos7_. Dont mind any overwrite
issues with zip: Either overwrite all or skip all duplicates. Then set
your designated device to dev4, ie DEV_USE 4, 'ram1_'

Then use the dev4_tks_str_StrTK_link link file to assemble the lot.

                  See here for help!

Software status
---------------
V0.01, pjw, 10 Mar 2001
V0.02, pjw, 16 Nov 2003, various times: improvements and additions
V0.03, pjw, 20 May 2019, modularised and improved
V0.04, pjw, 2020 Feb 18, added DESPACE$, JUST$, & INSERT$

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