pod/Combination.pod

   1 %perlcode %{
   2 @EXPORT_OK = qw/
   3                gsl_combination_alloc
   4                gsl_combination_calloc
   5                gsl_combination_init_first
   6                gsl_combination_init_last
   7                gsl_combination_free
   8                gsl_combination_memcpy
   9                gsl_combination_fread
  10                gsl_combination_fwrite
  11                gsl_combination_fscanf
  12                gsl_combination_fprintf
  13                gsl_combination_n
  14                gsl_combination_k
  15                gsl_combination_data
  16                gsl_combination_get
  17                gsl_combination_valid
  18                gsl_combination_next
  19                gsl_combination_prev
  20              /;
  21 %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
  22
  23 =head1 NAME
  24
  25 Math::GSL::Combination - Combinations
  26
  27 =head1 SYNOPSIS
  28
  29     use Math::GSL qw/:all/;
  30     use Math::GSL::Combination qw/:all/;
  31
  32     my $c   = Math::GSL::Combination->new(6,3);
  33     print join (" ", $c->as_list) . "\n";
  34     $c->next;
  35     print join (" ", $c->as_list) . "\n";
  36
  37     my $fd = gsl_fopen('combination.dat', 'w');
  38     gsl_combination_fwrite($fd, $c->raw);
  39     gsl_fclose($fd);
  40
  41 =head1 DESCRIPTION
  42
  43 Here is a list of all the functions in this module :
  44
  45 =over
  46
  47 =item * C<gsl_combination_alloc($n, $k)>
  48
  49 This function allocates memory for a new combination with parameters $n, $k.
  50 The combination is not initialized and its elements are undefined. Use the
  51 function gsl_combination_calloc if you want to create a combination which is
  52 initialized to the lexicographically first combination.
  53
  54 =item * C<gsl_combination_calloc($n, $k)>
  55
  56 This function allocates memory for a new combination with parameters $n, $k and
  57 initializes it to the lexicographically first combination.
  58
  59 =item * C<gsl_combination_init_first($c)>
  60
  61 This function initializes the combination $c to the lexicographically first
  62 combination, i.e. (0,1,2,...,k-1).
  63
  64 =item * C<gsl_combination_init_last($c)>
  65
  66 This function initializes the combination $c to the lexicographically last
  67 combination, i.e. (n-k,n-k+1,...,n-1).
  68
  69 =item * C<gsl_combination_free($c)>
  70
  71 This function frees all the memory used by the combination $c.
  72
  73 =item * C<gsl_combination_memcpy($dest, $src)>
  74
  75 This function copies the elements of the combination $src into the combination
  76 $dest. The two combinations must have the same size.
  77
  78 =item * C<gsl_combination_get($c, $i)>
  79
  80 This function returns the value of the i-th element of the combination $c. If
  81 $i lies outside the allowed range of 0 to k-1 then the error handler is invoked
  82 and 0 is returned.
  83
  84 =item * C<gsl_combination_fwrite($stream, $c)>
  85
  86 This function writes the elements of the combination $c to the stream $stream,
  87 opened with the gsl_fopen function from the Math::GSL module, in binary format.
  88 The function returns $GSL_EFAILED if there was a problem writing to the file.
  89 Since the data is written in the native binary format it may not be portable
  90 between different architectures.
  91
  92 =item * C<gsl_combination_fread($stream, $c)>
  93
  94 This function reads elements from the open stream $stream, opened with the
  95 gsl_fopen function from the Math::GSL module, into the combination $c in binary
  96 format. The combination $c must be preallocated with correct values of n and k
  97 since the function uses the size of $c to determine how many bytes to read. The
  98 function returns $GSL_EFAILED if there was a problem reading from the file. The
  99 data is assumed to have been written in the native binary format on the same
 100 architecture.
 101
 102 =item * C<gsl_combination_fprintf($stream, $c, $format)>
 103
 104 This function writes the elements of the combination $c line-by-line to the
 105 stream $stream, opened with the gsl_fopen function from the Math::GSL module,
 106 using the format specifier $format, which should be suitable for a type of
 107 size_t. In ISO C99 the type modifier z represents size_t, so "%zu\n" is a
 108 suitable format. The function returns $GSL_EFAILED if there was a problem
 109 writing to the file.
 110
 111 =item * C<gsl_combination_fscanf($stream, $c)>
 112
 113 This function reads formatted data from the stream $stream into the combination
 114 $c. The combination $c must be preallocated with correct values of n and k
 115 since the function uses the size of $c to determine how many numbers to read.
 116 The function returns $GSL_EFAILED if there was a problem reading from the file.
 117
 118 =item * C<gsl_combination_n($c)>
 119
 120 This function returns the range (n) of the combination $c.
 121
 122 =item * C<gsl_combination_k($c)>
 123
 124 This function returns the number of elements (k) in the combination $c.
 125
 126 =item * C<gsl_combination_data($c)>
 127
 128 This function returns a pointer to the array of elements in the combination $c.
 129
 130 =item * C<gsl_combination_valid($c)>
 131
 132 This function checks that the combination $c is valid. The k elements should
 133 lie in the range 0 to n-1, with each value occurring once at most and in
 134 increasing order.
 135
 136 =item * C<gsl_combination_next($c)>
 137
 138 This function advances the combination $c to the next combination in
 139 lexicographic order and returns $GSL_SUCCESS. If no further combinations are
 140 available it returns $GSL_FAILURE and leaves $c unmodified. Starting with the
 141 first combination and repeatedly applying this function will iterate through
 142 all possible combinations of a given order.
 143
 144 =item * C<gsl_combination_prev($c)>
 145
 146 This function steps backwards from the combination $c to the previous
 147 combination in lexicographic order, returning $GSL_SUCCESS. If no previous
 148 combination is available it returns $GSL_FAILURE and leaves $c unmodified.
 149
 150 =back
 151
 152 =cut
 153
 154 sub new {
 155     my ($class, $n, $k) = @_;
 156     my $this = {};
 157     $this->{_length} = $n;
 158     $this->{_combination} = gsl_combination_calloc($n, $k);
 159     bless $this, $class;
 160 }
 161
 162 sub as_list {
 163     my $self=shift;
 164     $self->get( [ 0 .. $self->elements - 1  ] );
 165 }
 166
 167 sub get {
 168     my ($self, $indices) = @_;
 169     return map {  gsl_combination_get($self->{_combination}, $_ ) } @$indices ;
 170 }
 171
 172 sub raw { (shift)->{_combination} }
 173 sub length { (shift)->{_length} }
 174
 175 sub elements {
 176     my $self = shift;
 177     return gsl_combination_k($self->{_combination});
 178 }
 179
 180 sub status {
 181     my ($self,$status) = @_;
 182     if (defined $status) {
 183         $self->{status} = $status;
 184         return $self;
 185     } else {
 186         return $self->{status};
 187    }
 188 }
 189
 190 sub next {
 191     my $self = shift;
 192     my $status = gsl_combination_next($self->{_combination});
 193     $self->status($status);
 194     return $self;
 195 }
 196
 197 sub prev {
 198     my $self = shift;
 199     my $status = gsl_combination_prev($self->{_combination});
 200     $self->status($status);
 201     return $status;
 202 }
 203
 204 =head1 MORE INFO
 205
 206 For more informations on the functions, we refer you to the GSL offcial
 207 documentation: L<http://www.gnu.org/software/gsl/manual/html_node/>
 208
 209  Tip : search on google: site:http://www.gnu.org/software/gsl/manual/html_node/ name_of_the_function_you_want
 210
 211
 212 =head1 AUTHORS
 213
 214 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 215
 216 =head1 COPYRIGHT AND LICENSE
 217
 218 Copyright (C) 2008-2009 Jonathan Leto and Thierry Moisan
 219
 220 This program is free software; you can redistribute it and/or modify it
 221 under the same terms as Perl itself.
 222
 223 =cut
 224
 225 %}