README file for BuubbleSort utility. Release 0.0.02
Copyright 2025-____ by The Software Samurai
Software released under GPL3+, and documentation released under FDL1.3+
=======================================================================

OVERVIEW
========
Perform a bidirectional bubble sort on a randomized array of strings or 
a randomized array of integer values.

1) The "bubble sort" is the simplest (and slowest) of the common sorting 
   algorithms. It's great flexibility is its strength, but it is recommend 
   that it be used only if the total number of records is "relatively small".
2) This application uses a bi-directional bubble sort, also known as the 
   "cocktail sort", presumably because its inventor was sipping a martini 
   at the time.
3) Sorting record _pointers_ is much faster than sorting the actual records, 
   regardless of record content, and therefore, except for pure numeric data, 
   pointer sorting is recommended whenever practical.


Download and unpack the distribution archive:
=============================================

Navigate to the base directory where package will be installed (example):
   cd ~/SoftwareDesign
Move the archive file to the base directory:
   mv ~/Dowloads/bubblesort-0.0.02.tar.bz2 .
Unpack the tar archive:
   tar -xjvf bubblesort-0.0.02.tar.bz2
Navigate to the target directory:
   cd BubbleSort

After unpacking the archive, the directory will look something like this:

.../SoftwareDesign/BubbleSort/
      BubbleSort.hpp  <== Application definition
      BubbleSort.cpp  <== Application implementation
      gString.hpp     <== gString class definition (text analysis and formatting)
      gString.cpp     <== gString class implementation 
      Makefile        <== Build the 'bubsort' application
      README          <== Package description, release notes (this file)


Building the application:
=========================

To build the application, type:
   gmake all

This will remove any stale object files or executable, and then will build 
and link the application to create the executable.
The application should build without errors and without warnings.

To test the build, type:
   ./bubsort --version

For invocation options, type:
   ./bubsort --help
or simply:
   ./bubsort


Commend-line Options
====================

Usage: bubsort --dir==[a | d] [OPTIONAL ARGS]
 '--dir' : sort direction: 'a':ascending, 'd':descending
 '--type': type of source data (optional)
           't':text pointers (default), 'T':text data direct
           'r':complex record pointers, 'R':complex records direct
           'n':numeric (integer) data
 '--case': specify case sensitivity for sorting (optional)
           'y' yes, case-sensitive sort (default)
           'n' no,  case-insensitive sort
 '--src' : source-data filename (optional)
           a plain-text file containing the data to be sorted
 '--help': (or '-h') display command-line help
 '--version': display version number and copyright message

1) One invocation option is mandatory: '--dir'
   This option specifies whether the sort is to be low-to-high or high-to-low.
2) The remaining options will take default values if not specified.
3) The '--type' option specifies the dataset to be used for the sort AND 
   the method of accessing the data:
     a) via an array of pointers to the data records, (default), or
        The 't' and 'r' options invoke pointer sorting for text and complex 
        records, respectively.
     b) direct evaluation of the records.
        The 'T' and 'T' options invoke direct sorting of the data records 
        for text and complex records, respectively.
     c) The 'n' option specifies sorting of the numeric data records.
        Note that because pointers ARE numeric data, there is no practical 
        difference between sorting pointers to numeric data and sorting 
        the numeric data directly.
4) The '--case' option specifies whether text records are to be evaluated:
     a) using a case sensitive sort, (default), or
     b) using a case-insensitive sort.
   -- Please note that "case sensitivity" for the text sorting algorithems is 
      strictly numeric, and is based on the value of the individual Unicode 
      codepoints for the characters.
   -- This is the standard method used by the C/C++ libbrary functions, where 
      ASCII 'A' ==41 (hex) and ASCII 'a' == 61 (hex). Thus, by comparing 
      codepoints, 'A' is less than 'a'.
   -- This is in contrast to "locale aware" sorting where (for English at least) 
      lowercase 'a' is less than uppercase 'A'.
   -- Please see the note below about application locale.
5) The '--src' option many be used to specify a file whose contents are to be 
   used as the source data records (one record per line).
   -- The file data must be encoded as plain text, presumably UTF-8 data.
   -- The file may contain any reasonable number of records (lines).
   -- The data will be sorted as text data. 
      (Note that ASCII numeric data are also text data.)
   -- The '--dir' and '--case' options will be applied to the sort.
   -- The '--type' option is ignored for external source dats. and _pointers_ 
      to the captured data records are used to perform the sort.
   -- The sorted records will be written to 'stdout' and if desired the 
      output can be redirected to a target file. Example:
         bubsort --dir=a --src='source_file' 1>>'target_file'

For a more detailed explanation of each command-line option, please refer to 
the web-page version of this readme file at:
http://www.softwaresam.us/docs/html_doc/BubbleSort_Notes.html


Application "locale"
====================
On startup, the Bubblesort application sets the application locale (if any) 
from the environment. While this locale has no direct effect of the standard 
sorting processes used by this application, it does come into play for the 
"--compcoll" debugging option.
The author recommends that each non-trivial application should explicitly 
initialize the locale on startup. This is accomplished by creating an 
instance of the std::locale object as shown:
      #include <locale>
      std::locale* ioLocale = new std::locale ( "" ) ;
      ioLocale->global( *ioLocale ) ;
For information on performing a "collated" (locale-aware) sort, please see 
the standard library 'strcoll' and 'wcscoll' functions.
For a simple example of this sort, see the 'SortCollated' method in 
BubbleSort.cpp, which in turn calls the 'compcoll' method of the gString class. 
The author has found this type of sort to be almost entirely worthless, but 
your mileage may vary.


Known bugs and other issues:
============================
None identified at this time.
