sgh/comparable-arrays

Provides generic Comparators for arrays.

v1.0.2 2015-04-06 15:41 UTC

Requires

• php: >=5.4.0
• sgh/comparable: >=1.1.0

Requires (Dev)

• phpunit/phpunit: 4.*

MIT

• Fabian Schmengler

• arrays
• comparable
• comparator

README

This package provides Comparators for arrays and objects that implement the SPL ArrayAccess interface. They can be used with the sorting and comparing tools in the Comparable package.

Requirements

The package requires PHP 5.4 or later and the Comparable package in version 1.0 or later.

Install

Via Composer

$ composer require sgh/comparable-arrays

Usage

The following comparators are available:

• KeyComparator: Use array item with specific key for comparison
• MultiKeyComparator: The same, but with the option to sort by multiple keys (i.e. fall back in case of equality)

You can use all the methods in \SGH\Comparable\SortFunctions and \SGH\Comparable\SetFunctions with the comparators.

KeyComparator Example

use SGH\Comparable\SortFunctions;
use SGH\Comparable\Comparator\StringComparator;
use SGH\Comparable\Arrays\Comparator\KeyComparator;

$arrayOfBooks = array(
    [ 'title' => 'Design Patterns', 'author' => 'Gang of Four', 'year' => 1995 ],
    [ 'title' => 'Clean Code', 'author' => 'Uncle Bob', 'year' => 2008 ],
    [ 'title' => 'Refactoring', 'author' => 'Martin Fowler', 'year' => 1999 ],
    [ 'title' => 'Patterns of Enterprise Application Architecture', 'autor' => 'Martin Fowler', 'year' => 2002 ],
);

// Sort the array of books by year:
SortFunctions::sort($arrayOfBooks, new KeyComparator('year'));

// Sort the array of books by title:
SortFunctions::sort($arrayOfBooks, new KeyComparator('title', new StringComparator));

The default comparator used to compare the array items is NumericComparator, which compares any scalar values and treats them as numbers. To sort by title we needed to specify the comparator explicitly.

If you prefer, you can also use the factory method ::callback() to retrieve a comparison callback, that can be used in any function that expects a user defined comparison callback:

usort($arrayOfBooks, KeyComparator::callback('title', new StringComparator));

MultiKeyComparator Example

use SGH\Comparable\SortFunctions;
use SGH\Comparable\Comparator\ReverseComparator;
use SGH\Comparable\Comparator\StringComparator;
use SGH\Comparable\Arrays\Comparator\MultiKeyComparator;

$arrayOfBooks = array(
    [ 'title' => 'Design Patterns', 'author' => 'Gang of Four', 'year' => 1995 ],
    [ 'title' => 'Clean Code', 'author' => 'Uncle Bob', 'year' => 2008 ],
    [ 'title' => 'Refactoring', 'author' => 'Martin Fowler', 'year' => 1999 ],
    [ 'title' => 'Patterns of Enterprise Application Architecture', 'autor' => 'Martin Fowler', 'year' => 2002 ],
);

// Sort the array of books by author, then by year, descending:
SortFunctions::sort($arrayOfBooks, new MultiKeyComparator([
	'author' => new StringComparator,
	'year'   => new ReverseComparator(new NumericComparator)
]));

Configuration

Both, KeyComparator and MultiKeyComparator accept arrays and objects that implement ArrayAccess as parameters. This default behavior can be changed such that they only accept arrays:

$comparator->setAcceptArrayAccessObject(false);

By default array keys must exist to compare their values. Both comparators have a non-strict mode, where missing items are treated as smaller than everything else. Two missing items are treated as equal.

$comparator->setStrict(false);

Testing

$ phpunit

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Fabian Schmengler(https://github.com/schmengler)
• All Contributors

License

The MIT License (MIT). Please see License File for more information.