Combination.i

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