pod/Sort.pod

   1 %perlcode %{
   2 @EXPORT_plain = qw/
   3                 gsl_sort gsl_sort_index
   4                 gsl_sort_smallest gsl_sort_smallest_index
   5                 gsl_sort_largest gsl_sort_largest_index
   6                 /;
   7 @EXPORT_vector= qw/
   8                 gsl_sort_vector gsl_sort_vector_index
   9                 gsl_sort_vector_smallest gsl_sort_vector_smallest_index
  10                 gsl_sort_vector_largest gsl_sort_vector_largest_index
  11                 /;
  12 @EXPORT_OK    = ( @EXPORT_plain, @EXPORT_vector );
  13 %EXPORT_TAGS  = (
  14                  all    => [ @EXPORT_OK     ],
  15                  plain  => [ @EXPORT_plain  ],
  16                  vector => [ @EXPORT_vector ],
  17                 );
  18 __END__
  19
  20 =head1 NAME
  21
  22 Math::GSL::Sort - Functions for sorting data
  23
  24 =head1 SYNOPSIS
  25
  26     use Math::GSL::Sort qw/:all/;
  27     my $x       = [ 2**15, 1.67, 20e5, -17, 6900, 1/3 , 42e-10 ];
  28     my $sorted  = gsl_sort($x, 1, $#$x+1 );
  29     my $numbers = [ map { rand(100) } (1..100) ];
  30     my ($status, $smallest10) = gsl_sort_smallest($array, 10, $x, 1, $#$x+1);
  31
  32
  33 =head1 DESCRIPTION
  34
  35 Here is a list of all the functions included in this module :
  36
  37 =over
  38
  39 =item * gsl_sort_vector($v)
  40
  41  This function sorts the elements of the vector $v into ascending numerical order.
  42
  43 =item * gsl_sort_vector_index($p, $v)
  44
  45  This function indirectly sorts the elements of the vector $v into ascending
  46  order, storing the resulting permutation in $p. The elements of $p give the
  47  index of the vector element which would have been stored in that position if
  48  the vector had been sorted in place. The first element of $p gives the index
  49  of the least element in $v, and the last element of $p gives the index of the
  50  greatest element in $v. The vector $v is not changed.
  51
  52 =item * gsl_sort_vector_smallest($array, $k, $vector)
  53
  54  This function outputs 0 if the operation succeeded, 1 otherwise and then the
  55  $k smallest elements of the vector $v. $k must be less than or equal to the
  56  length of the vector $v.
  57
  58 =item * gsl_sort_vector_smallest_index($p, $k, $v)
  59
  60  This function outputs 0 if the operation succeeded, 1 otherwise and then the
  61  indices of the $k smallest elements of the vector $v. $p must be a prealocated
  62  array reference. This should be removed in further versions. $k must be less
  63  than or equal to the length of the vector $v.
  64
  65 =item * gsl_sort_vector_largest($array, $k, $vector)
  66
  67  This function outputs 0 if the operation succeeded, 1 otherwise and then the
  68  $k largest elements of the vector $v. $k must be less than or equal to the
  69  length of the vector $v.
  70
  71 =item * gsl_sort_vector_largest_index($p, $k, $v)
  72
  73  This function outputs 0 if the operation succeeded, 1 otherwise and then the
  74  indices of the $k largest elements of the vector $v. $p must be a prealocated
  75  array reference. This should be removed in further versions. $k must be less
  76  than or equal to the length of the vector $v.
  77
  78 =item * gsl_sort($data, $stride, $n)
  79
  80  This function returns an array reference to the sorted $n elements of the
  81  array $data with stride $stride into ascending numerical order.
  82
  83 =item * gsl_sort_index($p, $data, $stride, $n)
  84
  85  This function indirectly sorts the $n elements of the array $data with stride
  86  $stride into ascending order, outputting the permutation in the foram of an
  87  array. $p must be a prealocated array reference. This should be removed in
  88  further versions. The array $data is not changed.
  89
  90 =item * gsl_sort_smallest($array, $k, $data, $stride, $n)
  91
  92  This function outputs 0 if the operation succeeded, 1 otherwise and then the
  93  $k smallest elements of the array $data, of size $n and stride $stride, in
  94  ascending numerical. The size $k of the subset must be less than or equal to
  95  $n. The data $src is not modified by this operation. $array must be a
  96  prealocated array reference. This should be removed in further versions.
  97
  98 =item * gsl_sort_smallest_index($p, $k, $src, $stride, $n)
  99
 100  This function outputs 0 if the operation succeeded, 1 otherwise and then the
 101  indices of the $k smallest elements of the array $src, of size $n and stride
 102  $stride. The indices are chosen so that the corresponding data is in ascending
 103  numerical order. $k must be less than or equal to $n. The data $src is not
 104  modified by this operation. $p must be a prealocated array reference. This
 105  should be removed in further versions.
 106
 107 =item * gsl_sort_largest($array, $k, $data, $stride, $n)
 108
 109  This function outputs 0 if the operation succeeded, 1 otherwise and then the
 110  $k largest elements of the array $data, of size $n and stride $stride, in
 111  ascending numerical. The size $k of the subset must be less than or equal to
 112  $n. The data $src is not modified by this operation. $array must be a
 113  prealocated array reference. This should be removed in further versions.
 114
 115 =item * gsl_sort_largest_index($p, $k, $src, $stride, $n)
 116
 117  This function outputs 0 if the operation succeeded, 1 otherwise and then the
 118  indices of the $k largest elements of the array $src, of size $n and stride
 119  $stride. The indices are chosen so that the corresponding data is in ascending
 120  numerical order. $k must be less than or equal to $n. The data $src is not
 121  modified by this operation. $p must be a prealocated array reference. This
 122  should be removed in further versions.
 123
 124 =back
 125
 126  Here is a complete list of all tags for this module :
 127
 128 =over
 129
 130 =item all
 131
 132 =item plain
 133
 134 =item vector
 135
 136 =back
 137
 138  For more informations on the functions, we refer you to the GSL offcial documentation:
 139  L<http://www.gnu.org/software/gsl/manual/html_node/>
 140
 141  Tip : search on google: L<http://www.gnu.org/software/gsl/manual/html_node/name_of_the_function_you_want>
 142
 143 =head1 PERFORMANCE
 144
 145  In the source code of Math::GSL, the file "examples/benchmark/sort" compares
 146  the performance of gsl_sort() to Perl's builtin sort() function. It's first
 147  argument is the number of iterations and the second is the size of the array
 148  of numbers to sort. For example, to see a benchmark of 1000 iterations for
 149  arrays of size 50000 you would type
 150
 151     ./examples/benchmark/sort 1000 50000
 152
 153  Initial benchmarks indicate just slightly above a 2x performance increase
 154  over sort() for arrays of between 5000 and 50000 elements. This may mostly
 155  be due to the fact that gsl_sort() takes and returns a reference while sort()
 156  takes and returns a plain list.
 157
 158 =head1 AUTHORS
 159
 160 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 161
 162 =head1 COPYRIGHT AND LICENSE
 163
 164 Copyright (C) 2008 Jonathan Leto and Thierry Moisan
 165
 166 This program is free software; you can redistribute it and/or modify it
 167 under the same terms as Perl itself.
 168
 169 =cut
 170
 171 %}
 172