File: readme.txt

Readme for the Advanced Array Sort Software
===========================================

Topics
------

1. Setup
2. Using the Advanced Array Sort Software
2.1. Building a Valid Sort String
2.2. Restrictions
2.3. Error Handling
3. Understanding the Examples
4. Disclaimer


1. Setup
--------

Insert the following code snippet into the source code file
where you want the functionality of array_sort.class.inc to be
available.

function sort_array($arr, $sort_string, $sort_function = "strcasecmp"){
  require("array_sort.class.inc");
  $array_sort = new array_sort($arr, $sort_string, $sort_function);
  if(!$array_sort->error["flag"]) return $array_sort->get_sorted_array();
  else return $arr;
  }

Replace the URI in the require statement to whereever you stored
the file array_sort.class.inc.

That's it! Now you can use the functionality as described in
Step 2.


2. Using the Advanced Array Sort Software
-----------------------------------------

After going through Step 1 you can generally use the
functionality this way:

$some_array = array(0 => array(0 => "some_string_1",
							   1 => "some_string_2"),
					1 => array(0 => "some_string_3",
							   1 => "some_string_4"));

$sort_string = "<[0]><asc>";
$some_array = sort_array($some_array, $sort_string);

This would result in the same array as the given array, because
some_string_1 is lower than some_string_3 and the sort direction
is ascending.

To sort the array reversively use:

$sort_string = "<[0]><desc>";

instead.

In addition to the $some_array and $sort_string arguments the
sort_array() function accepts an optional third argument. This
is the name of one of the various PHP string comparison functions.
The preset function name is strcasecmp as you can see in the
function header in Step 1. For other available comparison
functions please consult your PHP manual.


2.1. Building a Valid Sort String
---------------------------------

Any sort string is made up of various parts. These parts are

1. the Index Specification
2. the Sort Direction Specification
3. - optional - the Separator


2.1.1. Index Specification
--------------------------

Any Index Specification starts with an html tag opener (<)
followed by a php index opener ([). Next comes a valid index
of the array to be sorted followed by a php index closer (]).

Thus we have the following: <[0]

What follows now depends on the dimensions of the array to be
sorted. Either you add some more indexes encased in [].

For example: <[0][0][0]

Or, if no more indexes need to be added, you close the Index
Specification with an html tag closer (>).

Thus we have the following: <[0][0][0]>

This would be a valid Index Specification for sorting a 4-
dimensional array.

Note: Always use one index less than the dimension of the array
to be sorted as the Index Specification layout. This is basically
the same requirement as for the native php sort functions.


2.1.2. Sort Direction Specification
-----------------------------------

In addition to specifying the indexes the array is to be sorted
by you can also specify a sorting direction.

As you may know the two available directions are ascending and
descending.

If you want your array to be sorted ascendingly either use

<asc> (case insensitive)

or leave the Sort Direction Specification away.

If you want your array to be sorted descendingly use

<desc> (case insensitive)

accordingly.

Any Sort Direction Specification follows directly after the
closer of the Index Specification, without any character in
between. The two Specifications put together look like this:

<[0]><asc> or <[0]>

or

<[0]><desc>


2.1.3. Separator
----------------

All Sort Strings previously stated sort by only one column. To
sort by more than one column you have to put several Index
Specification / Sort Direction Specification couples together
using the Separator.

The Separator sign is the pipe sign (|).

Thus a Sort String for sorting a three-dimensional array by
column 1 ascendingly and column 5 descendingly using the second
property for each would look like this:

<[0][1]><asc>|<[4][1]><desc>

or

<[0][1]>|<[4][1]><desc>

Note: For this explanation it is assumed that array indexes are
understood in the way that the first index specifies the row,
the second index the column and the third index the property.

Example: $some_array[0][0][0]
                     |  |  ^
                     |  ^  property
                     ^  column
                     row


2.2. Restrictions
-----------------

As you can see in the explanations abovementioned the Sort
String is quite dynamic. However some restrictions apply.


2.2.1. Invalid Indexes
----------------------

You may not use any Index Specification that doesn't result in
valid indexes for the array to be sorted. Clearly you cannot
sort an array by an index that doesn't exist.


2.2.2. Multiple Index Dimensions
--------------------------------

You may not use multiple index dimensions in Sort Strings
intended to sort an array by multiple columns. An invalid
Sort String would be

<[0]>|<[1][2]>

To change it into a valid one you'd have to restate it that way:

<[0][2]>|<[1][2]> or <[0]>|<[1]>

and adjust your array accordingly.

Note: The index 2 following the index 0 in <[0][2]>|<[1][2]>
could of course be any valid index.


2.2.3. Using Duplicate Specifications
-------------------------------------

You may not use duplicate Index Specification / Sort Direction
Specification couples in Sort Strings intended to sort an array
by multiple columns. This is invalid:

<[0]>|<[0]>|<[1]>

It just makes no sense sorting an array twice by the exact same
column. However you may sort your array by the same Index
Specification, but a different Sort Order Specification:

<[0]>|<[0]><desc>|<[1]>

Although it may not make much sense, it's nonetheless a valid
Sort String.


2.2.4. Index Types
------------------

As of this version the only supported index type is the numeric
index ([some_integer]). Therefore you cannot use any alphanumeric
indexes (["some_string"]).


2.3. Error Handling
-------------------

Should your Sort String contain any errors, be they syntactical
or semantical, the returned array will always be the given array
that was to be sorted. For debugging purposes you can access the
$array_sort->error["msg"] property of the $array_sort object in
the sort_array function introduced in Step 1 (Setup). This is
normally turned off.

You may either output the error string contained in the property
aforementioned directly to the browser or to some log file. For
any help on either see the PHP Documentation or send me an email.


3. Understanding the Examples
-----------------------------

There are two examples provided with the distribution of the
Advanced Array Sort Software. Functionally they both almost do
the same. However, the example given in the file

array_sort_example1.php

is written to conform with this readme.txt file you're just
reading. That means it includes a wrapper function like the one
introduced in Step 1 (Setup). Furthermore it doesn't return any
error messages, but only returns the array that was to be sorted
unchanged should any error occur.

To the contrary the example given in the file

array_sort_example2.php

doesn't have a wrapper function and outputs any error messages
instead of displaying the unchanged array that was to be sorted.

You may manipulate the Sort Strings (in both examples stored in
the variable $sort_string) of either example to see the effects
on the produced output. That way you can also get a "feeling"
for how to use the Advanced Array Sort Software properly.


4. Disclaimer
-------------

This software product is provided "as is". The producer and any
distributor are not in any way liable for any damage incurred by
the use of or failure to use this product. For more information
see the license.txt file.

This software product has been developed by

Matthias Rothe
Altenzeller Str. 2
01069 Dresden

Germany

and is licensed to you according to the license.txt file.

For help, encouragement, comments and the like please send me an
email to matthias.rothe@gmx.com.

Thanks for using my software!

--

Advanced Array Sort
(C)opyright 2005, Matthias Rothe