CMP

                                 CMP%
                                 ====

This command compares two values of the same type, integers, floats or
strings, and returns the result.

For strings it can use the various internal string comparison methods
(see below) or user-defined tables.

The numeric comparisons are just standard.

The reason for including standard numeric comparison in this function is
so that no special steps are needed in, for example, routine loops
to cater for one type of variable or another, and no coersion (conversion
from one type to another) is done, thus making comparisons faster for
mixed-type comparison routines.

See the included example program ..rsc_BSearch_bas


Usage
-----

      result% = CMP%(str1$, str$, [comptype% [,table]])
or
      result% = CMP%(<expr>[%], <expr>[%]) - any comptype and table ignored

where
      result%  =      -1 => <expr1> < <expr2>
                       0 => <expr1> = <expr2>
                       1 => <expr1> > <expr2>

      <expr>   = string or numeric expression
      comptype = Qdos comparison types 0..3            - ignored unless string
      table    = address of 256 byte translation table - ignored unless string

Note: The type of the first parameter determins the type of the second! If
      the second parameter doesnt conform to the rules of the first a Bad
      Parameter error is thrown.

Note: If table is specified, comptype% is ignored. The comparison is done
      on a character by character basis using the character correspondence
      given by the table. This may be useful for, for example, equating
      accented variants with their non-accented character.



Order of Strings
----------------

The bulk of the following text comes from the QDOS/SMS Reference Manual
v. 4.4 10/06/2018, Section 16 - 19. This may not apply to Minerva, which
has its own ideas on string comparison!

Since comparison may be used to sort strings into order as well as checking
for equality or equivalence, the order must be well defined. A form of
dictionary order is attempted - this will require to be modified for foreign
character sets.

Space is the first character. Punctuation is in ASCII order (except "." which
is the last). All punctuation is defined to be before all letters or digits
(e.g. A. before AA. ). Optionally, embedded numbers may be taken in numerical
order (e.g. Case5A before Case10A, and also Case5.10 before Case5.5).

All digits or numbers are defined to be before all letters (e.g. bat1 before
bath1). An upper case letter comes before the corresponding lower case
letter but after the previous lower case letter (e.g. Bath is before bath but
after axe). Optionally, an upper case letter is treated as equivalent to a
lower-case letter.

SPACE

!"#$%&'()*+,-/:;<=>?@[\]^_£{|}~©

Digits or numbers

AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

Foreign characters


Comparisons
-----------
The relationship of one string to another may be

Equal   All characters or numbers are the same or equivalent.

Lesser  The first part of the first string, which is different from the
        corresponding character in the second string, is before it in the
        defined order.
Greater The first part of the first string, which is different from the
        corresponding character in the second string, is after it in the
        defined order.


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

Type 0  Made directly on a character by character basis (in lexical order)

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.


Translation table
-----------------
An optional 256 byte translation table may be used in addition to the four
comparison types described above. This could be based on a different
character set or, for example, to equate accented characters to their
un-accented counterparts. See a crude example in ..rsc_AccentTab_bas.

The lexically ordered table as used by SMSQ/E is included as ..rsc_tab1_asm
and ..rsc_tab1_bin.


Status of This software
-----------------------

Note: This Pick'n'Mix toolkit command has been relocated from
      dev4_str_cmp_ to dev4_soc_cmp_gen_ (SOC => Sort, Order, Compare)

V0.01, pjw, 2019 May 19, first release
V0.02 & V0.03 not released
V0.04, pjw, 2026 Apr 27, bugfixes + updated to include numeric comparison.

               Conditions of use and DISCLAIMER as per Knoware.no
Generated by QuickHTM, 2026 Apr 27
<-Back
ToP