PHP Classes
elePHPant
Icontem

Comparator Tools: Compare and sort objects of many types

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Info   View files View files (27)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings  
2010-09-08 (4 years ago) RSS 2.0 feedNot yet rated by the usersTotal: 418 All time: 5,919 This week: 1,173Up
Version License PHP version Categories  
comparator-tools 0.9BSD License5.1PHP 5, Data types, Language
Description Author  

This package can be used to Sort and compare objects of many types.

It defines the comparable interface that is implemented by several different objects meant to compare common types of values like as files by any of their attributes such as name, size, creation or modification time.

Additionally it provides classes that take advantage of objects that implement the Comparable interface to sort arrays of objects.

Innovation Award  
PHP Programming Innovation award nominee
October 2010
Number 2


Prize: One subscription to the PDF edition of the PHP Architect magazine
Most sorting algorithms determine the order by which a set of elements is stored by comparing pairs of elements.

This package implements a comparable interface that can be implemented by any objects of any classes that you may need to be sorted.

Manuel Lemos
Picture of Fabian Schmengler
Name: Fabian Schmengler is available for providing paid consulting. Contact Fabian Schmengler .
Classes: 6 packages by
Country: Germany Germany
Age: 32
All time rank: 108971 in Germany Germany
Week rank: 572 Up24 in Germany Germany Up
Innovation award
Innovation award
Nominee: 4x

Details provided by the author  
+-----------------------------------------------------------------------------+
|                            ComparatorTools                                  |
+-----------------------------------------------------------------------------+

- Synopsis
- Requirements
- Files
- Simple Usage
- Procedural Interface
- Error Handling

Synopsis
--------
This package provides sorting of objects that have a Comparable interface and
other useful functions with comparison of objects. With these tools the
"Comparable" and "Comparator" interfaces can be used like known from Java.


Requirements
------------
The package requires PHP 5.1 or later.

To use the package, just include comparatortools.lib.php. If you do not want the
additional procedural interface, remove the inclusion of functions.inc.


Files
-----
readme.txt - the file you are reading right now
license.txt - BSD license
comparatortools.lib.php - library loader, include this file to use the package
ComparatorTool.php - class file: abstract tool class
ObjectSorter.php - class file: tool class for sorting
ObjectArrayModifier.php - class file: tool class for other array modifications (diff, intersect, unique)
Comparator.php- class file: comparator interface
Comparable.php - class file: comparable interface
ComparatorException.php - class file: comparator exception
functions.inc - functions file: procedural interface (osort, orsort etc.)
Iterators/ObjectSortingIterator.php - class file: ObjectSorter functionality for iterators
Comparators/ComparableComparator.php - class file: comparator for Comparable interface
Comparators/ObjectComparator.php - class file: comparator for object identity
Comparators/ReverseComparator.php - class file: decorator class to revert comparator outcome
Comparators/SplFileInfoComparator.php - class file: abstract comparator for SplFileInfo objects
Comparators/SplFileInfoComparatorATime.php - class file: compare SplFileInfo objects by access time
Comparators/SplFileInfoComparatorCTime.php - class file: compare SplFileInfo objects by creation time
Comparators/SplFileInfoComparatorMTime.php - class file: compare SplFileInfo objects by modification time
Comparators/SplFileInfoComparatorName.php - class file: compare SplFileInfo objects by file name
Comparators/SplFileInfoComparatorSize.php - class file: compare SplFileInfo objects by file size
Comparators/SplFileInfoComparatorType.php - class file: compare SplFileInfo objects by file type
example/ExampleData.php - example: an implementation of the Comparable interface, used by the examples
example/ExampleComparator.php - example: an implementation of the Comparator interface, used by the examples
example/sort.php - example: some sorting
example/sort_procedural.php - example: same example but with the procedural interface
example/advanced.php - example: more examples


Simple Usage
------------

To give your classes the comparable functionality, just implement the Comparable
interface:

	class Foo implements Comparable
	{
		public function compareTo($object)
		{
		}
	}
	
The compareTo method will be called with another instance of Foo as parameter
and must return a negative value if ($this < $object) applies and a positive
value if ($this > $object) applies, 0 otherwise (the objects are considered
equal)

To use the tools - i.e. sort objects - instantiate a tool class (currently
available: ObjectSorter, ObjectArrayModifier):

	$tool = new ObjectSorter;
	$tool->sort($array_of_foo_objects);

For detailed description of the functions see phpDoc documentation inside the
tool class files.

It is also possible to implement separate comparator classes:

	class FooComparator implements Comparator
	{
		public function compare($object1, $object2)
		{
		}
	}

The compare method behaves just like the compareTo method but both objects are
passed as parameters.

To use a comparator, call the setComparator() method of the tool or pass the
comparator in the constructor:

	$fooTool = new ObjectSorter(new FooComparator);
	$fooTool->sort($array_of_foo_objects);


Procedural Interface
--------------------

There is also a procedural interface with functions much like sort, array_diff
and so on from the PHP core. This way the Comparable interface can be used in
a convenient, familiar way.

	osort($array_of_foo_objects);
	
Currently available:

	osort
	orsort
	oarsort
	oasort
	array_omultisort
	array_ounique
	array_odiff
	array_ointersect

For detailed description of the functions see phpDoc documentation inside 
functions.inc


Error Handling
--------------

You are encouraged to throw a ComparatorException if your compare() or compareTo()
methods fail, i.e. in case of wrong parameters. The tools will catch and handle
them.
By default most functions return false and trigger a E_USER_WARNING if such an
exception was thrown. But it is also possible to change this behaviour:

	ComparatorTool::setThrowExceptions(true);

so that the exceptions are carried on to your application.
  Files folder image Files  
File Role Description
Files folder imageIterators (1 file)
Files folder imageComparators (10 files)
Files folder imageexample (6 files)
Plain text file license.txt Lic. BSD License
Accessible without login Plain text file readme.txt Doc. Documentation
Plain text file comparatortools.lib.php Aux. library loader, include this file to use the package
Plain text file ComparatorTool.php Class abstract tool class
Plain text file ObjectArrayModifier.php Class tool class for other array modifications (diff, intersect, unique)
Plain text file ObjectSorter.php Class tool class for sorting
Plain text file Comparable.php Class comparable interface
Plain text file Comparator.php Class comparator interface
Plain text file ComparatorException.php Class comparator exception
Plain text file functions.inc Aux. procedural interface (osort, orsort etc.)

  Files folder image Files  /  Iterators  
File Role Description
  Plain text file ObjectSortingIterator.php Class ObjectSorter functionality for iterators

  Files folder image Files  /  Comparators  
File Role Description
  Plain text file ComparableComparator.php Class comparator for Comparable interface
  Plain text file ObjectComparator.php Class comparator for object identity
  Plain text file ReverseComparator.php Class decorator class to revert comparator outcome
  Plain text file SplFileInfoComparator.php Class abstract comparator for SplFileInfo objects
  Plain text file SplFileInfoComparatorATime.php Class compare SplFileInfo objects by access time
  Plain text file SplFileInfoComparatorCTime.php Class compare SplFileInfo objects by creation time
  Plain text file SplFileInfoComparatorMTime.php Class compare SplFileInfo objects by modification time
  Plain text file SplFileInfoComparatorName.php Class compare SplFileInfo objects by file name
  Plain text file SplFileInfoComparatorSize.php Class compare SplFileInfo objects by file size
  Plain text file SplFileInfoComparatorType.php Class compare SplFileInfo objects by file type

  Files folder image Files  /  example  
File Role Description
  Plain text file ExampleComparator.php Example an implementation of the Comparator interface, used by the examples
  Plain text file ExampleData.php Example an implementation of the Comparable interface, used by the examples
  Plain text file randomdata.inc Example generation of a randomized object array
  Plain text file sort.php Example some sorting
  Plain text file sort_procedural.php Example same example but with the procedural interface
  Plain text file advanced.php Example more examples

 Version Control Unique User Downloads Download Rankings  
 0%Total:418All time:5,919
 This week:0This week:1,173Up