Skip to content
Browse files

update readme

  • Loading branch information...
1 parent 41f9ca8 commit 1ed0210a21ea0908bd45678dfb173ba1a58df268 Nicolas Rochelemagne committed
Showing with 229 additions and 4 deletions.
  1. +209 −1 README
  2. +2 −3 t/99_benchmark.t
  3. +18 −0 t/99_readme.t
View
210 README
@@ -1 +1,209 @@
-Simple operations
+NAME
+ Sort::XS - a ( very ) fast XS sort alternative for one dimension list
+
+SYNOPSIS
+ use Sort::XS qw/xsort/;
+
+ # use it simply
+ my $sorted = xsort([1, 5, 3]);
+ $sorted = [ 1, 3, 5 ];
+
+ # personalize your xsort with some options
+ my $list = [ 1..1000, 200..1100 ]
+ my $sorted = xsort( $list )
+ or xsort( list => $list )
+ or xsort( list => $list, algorithm => 'quick' )
+ or xsort( $list, algorithm => 'quick', data => integer )
+ or xsort( list => $list, algorithm => 'heap', data => 'integer' )
+ or xsort( list => $list, algorithm => 'merge', data => 'string' );
+
+ # if you [ mainly ] use very small arrays ( ~ 10 rows )
+ # prefer using directly one of the XS subroutines
+ $sorted = Sort::XS::quick_sort( $list )
+ or Sort::XS::heap_sort($list)
+ or Sort::XS::merge_sort($list)
+ or Sort::XS::insertion_sort($list);
+
+DESCRIPTION
+ This module provides several common sort algorithms implemented as XS.
+ Sort can only be used on one dimension list of integers or strings.
+
+ It's goal is not to replace the internal sort subroutines, but to
+ provide a better alternative in some specifics cases :
+
+ - no need to specify a comparison operator
+ - sorting a mono dimension list
+
+ALGORITHMS
+ I've chosen to use quicksort as the default method ( even if it s not a
+ stable algorithm ), you can also consider to use heapsort which provides
+ a worst case in "n log n".
+
+ Chosing the correct algorithm depends on distribution of your values and
+ size of your list. Quicksort provides an average good solution, even if
+ in some case it will be better to use a different choice.
+
+ quick sort
+ This is the default algorithm. In pratice it provides the best results
+ even if in worst case heap sort will be a better choice.
+
+ read http://en.wikipedia.org/wiki/Quicksort for more informations
+
+ heap sort
+ A little slower in practice than quicksort but provide a better worst
+ case runtime.
+
+ read http://en.wikipedia.org/wiki/Heapsort for more informations
+
+ merge sort
+ Stable sort algorithm, that means that in any case the time to compute
+ the result will be similar. It's still a better choice than the internal
+ perl sort.
+
+ read http://en.wikipedia.org/wiki/Mergesort for more informations
+
+ insertion sort
+ Provide one implementation of insertion sort, but prefer using either
+ any of the previous algorithm or even the perl internal sort.
+
+ read http://en.wikipedia.org/wiki/Mergesort for more informations
+
+ perl
+ this is not an algorithm by itself, but provides an easy way to disable
+ all XS code by switching back to a regular sort.
+
+ Perl 5.6 and earlier used a quicksort algorithm to implement sort. That
+ algorithm was not stable, so could go quadratic. (A stable sort
+ preserves the input order of elements that compare equal. Although
+ quicksort's run time is O(NlogN) when averaged over all arrays of length
+ N, the time can be O(N**2), quadratic behavior, for some inputs.)
+
+ In 5.7, the quicksort implementation was replaced with a stable
+ mergesort algorithm whose worst-case behavior is O(NlogN). But
+ benchmarks indicated that for some inputs, on some platforms, the
+ original quicksort was faster.
+
+ 5.8 has a sort pragma for limited control of the sort. Its rather blunt
+ control of the underlying algorithm may not persist into future Perls,
+ but the ability to characterize the input or output in implementation
+ independent ways quite probably will.
+
+ use default perl version
+
+METHODS
+ xsort
+ API that allow you to use one of the XS subroutines. Prefer using this
+ method. ( view optimization section for tricks )
+
+ list
+ provide a reference to an array if only one argument is provided can
+ be ommit
+
+ my $list = [ 1, 3, 2, 5, 4 ];
+ xsort( $list ) or xsort( list => $list )
+
+ algorithm [ optional, default = quick ]
+ default value is quick you can use any of the following choices
+
+ quick # quicksort
+ heap # heapsort
+ merge
+ insertion # not recommended ( slow )
+ perl # use standard perl sort method instead of c implementation
+
+ data [ optional, default = integer ]
+ You can specify which kind of sort you are expecting ( i.e. '<=>' or
+ 'cmp' ) by setting this attribute to one of these two values
+
+ integer # <=>, is the default operator if not specified
+ string # cmp, do the compare on string
+
+ quick_sort
+ XS subroutine to perform the quicksort algorithm. No type checking
+ performed. Accept only one single argument as input.
+
+ my $list = [1, 6, 4, 2, 3, 5 ]
+ Sort::XS::quick_sort($list);
+
+ heap_sort
+ XS subroutine to perform the heapsort algorithm. No type checking
+ performed. Accept only one single argument as input.
+
+ my $list = [1, 6, 4, 2, 3, 5 ]
+ Sort::XS::heap_sort($list);
+
+ merge_sort
+ XS subroutine to perform the mergesort algorithm. No type checking
+ performed. Accept only one single argument as input.
+
+ my $list = [1, 6, 4, 2, 3, 5 ]
+ Sort::XS::merge_sort($list)
+
+ insertion_sort
+ XS subroutine to perform the insertionsort algorithm. No type checking
+ performed. Accept only one single argument as input.
+
+ my $list = [1, 6, 4, 2, 3, 5 ]
+ Sort::XS::insertion_sort($list);
+
+OPTIMIZATION
+ xsort provides an api to call xs subroutines to easy change sort
+ preferences and an easy way to use it ( adding data checking ) as it
+ provides an extra layer on the top of xs subroutines it has a cost...
+ and adds a little more slowness... This extra cost cannot be noticed on
+ large arrays ( > 100 rows ), but for very small arrays ( ~ 10 rows ) it
+ will not a good idea to use the api ( at least at this stage ). In this
+ case you will prefer to do a direct call to one of the XS methods to
+ have pure performance.
+
+ Note that all the XS subroutines are not exported by default.
+
+ my $list = [1, 6, 4, 2, 3, 5 ]
+ Sort::XS::quick_sort($list);
+ Sort::XS::heap_sort($list);
+ Sort::XS::merge_sort($list)
+ Sort::XS::insertion_sort($list);
+
+ Once again, if you use large arrays, it will be better to use :
+
+ xsort([100..1]);
+
+BENCHMARK
+ Here is a glance of what you can expect using this module :
+
+ These results have been computed on a set of multiple random arrays
+ generated by the benmark test included in the dist testsuite.
+
+ # sorting an ( integer ) array of 10 rows - quicksort is 12 % faster
+ than a regular perl sort
+
+ # sorting an ( integer ) array of 100 rows - quicksort is 46 % faster
+ than a regular perl sort
+
+ # sorting an ( integer ) array of 1_000 rows - quicksort is 82 % faster
+ than a regular perl sort
+
+ # sorting an ( integer ) array of 10_000 rows - quicksort is 2 x times
+ faster than a regular perl sort ( 112 % )
+
+ # sorting an ( integer ) array of 100_000 rows - quicksort is 2.5 x
+ times faster than a regular perl sort
+
+ # sorting an ( integer ) array of 1_000_000 rows - quicksort is 3.4 x
+ times faster than a regular perl sort
+
+TODO
+ Implementation of float, string comparison... At this time only
+ implement sort of integers
+
+ Improve API performance for small set of arrays
+
+AUTHOR
+ Nicolas R., <me@eboxr.com>
+
+COPYRIGHT AND LICENSE
+ This software is copyright (c) 2011 by eboxr.
+
+ This is free software; you can redistribute it and/or modify it under
+ the same terms as the Perl 5 programming language system itself.
+
View
5 t/99_benchmark.t
@@ -1,10 +1,9 @@
#!/usr/bin/env perl
BEGIN {
- unless ( $ENV{RELEASE_TESTING} ) {
+ unless ( $ENV{DEVEL_TESTS} ) {
require Test::More;
- Test::More::plan( skip_all =>
-'these tests are for release candidate testing ( set RELEASE_TESTING=1 )'
+ Test::More::plan( skip_all => 'Enable DEVEL_TESTS environment variable'
);
}
}
View
18 t/99_readme.t
@@ -0,0 +1,18 @@
+use strict;
+use warnings;
+
+BEGIN {
+ use Test::More;
+ plan(skip_all => "Enable DEVEL_TESTS environment variable")
+ unless ( $ENV{DEVEL_TESTS} );
+
+ eval "use Pod::Readme";
+ plan(skip_all => "Pod::Readme required for updating README")
+ if $@;
+}
+
+my $parser = Pod::Readme->new();
+ok $parser->parse_from_file( 'lib/Sort/XS.pm', 'README' );
+
+done_testing();
+

0 comments on commit 1ed0210

Please sign in to comment.
Something went wrong with that request. Please try again.