PHP Classes

File: readme.txt

Recommend this page to a friend!
  Classes of Matthias Rothe   Advanced Array Sort   readme.txt   Download  
File: readme.txt
Role: Documentation
Content type: text/plain
Description: A brief Manual to the Class
Class: Advanced Array Sort
Sorts multidimensional arrays by multiple columns
Author: By
Last change: added documentation of the provided examples
Date: 19 years ago
Size: 8,514 bytes
 

Contents

Class file image Download
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