PHP Classes
elePHPant
Icontem

Advanced Array Sort: Sorts multidimensional arrays by multiple columns

Recommend this page to a friend!
  Info   View files View files (6)   DownloadInstall with Composer Download .zip   Reputation   Support forum (1)   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2005-12-16 (10 years ago) RSS 2.0 feedStarStarStar 53%Total: 2,548 All time: 1,458 This week: 1,043Up
Version License Categories
array_sort 1.0GNU General Publi...Data types
Description Author

This class sorts two- or multidimensional arrays by one or multiple columns. The assumed array format is always [row][column]([property]).

Sorting works ascending as well as descending.

There are no limits to either the dimensions of the array or the columns it is sorted by.

All that's necessary to pass to the class is the array to be sorted and a sort string specifying how the array is to be sorted. This sort string is checked for syntactical and semantical errors. Should any error occur an appropriate error message is returned.

Picture of Matthias Rothe
Name: Matthias Rothe <contact>
Classes: 1 package by
Country: Germany Germany

Details
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
  Files folder image Files  
File Role Description
Plain text file array_sort.class.inc Class The full, uncommented source code
Plain text file array_sort.commented_class.inc Class The full source code with German comments
Accessible without login Plain text file array_sort_example1.php Example Example of the Class in Use (readme.txt conform)
Accessible without login Plain text file array_sort_example2.php Example Example of the Class in Use (Outputs Error Msgs)
Accessible without login Plain text file license.txt Lic. License
Accessible without login Plain text file readme.txt Doc. A brief Manual to the Class

 Version Control Unique User Downloads Download Rankings  
 0%
Total:2,548
This week:0
All time:1,458
This week:1,043Up
User Ratings User Comments (1)
 All time
Utility:70%StarStarStarStar
Consistency:70%StarStarStarStar
Documentation:58%StarStarStar
Examples:54%StarStarStar
Tests:-
Videos:-
Overall:53%StarStarStar
Rank:1753
 
Could not get it to work
6 years ago (Don Proshetsky)
35%StarStar