Comment out some more free() calls, which need to be turned on per-subsystem to weed...
[Math-GSL.git] / pod / Combination.pod
blobb5e278caaadebd6f8b669ecccff144657e6708d9
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 ] );
23 =head1 NAME
25 Math::GSL::Combination - Combinations
27 =head1 SYNOPSIS
29     use Math::GSL qw/:all/;
30     use Math::GSL::Combination qw/:all/;
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";
37     my $fd = gsl_fopen('combination.dat', 'w');
38     gsl_combination_fwrite($fd, $c->raw);
39     gsl_fclose($fd);
41 =head1 DESCRIPTION
43 Here is a list of all the functions in this module :
45 =over
47 =item * C<gsl_combination_alloc($n, $k)>
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.
54 =item * C<gsl_combination_calloc($n, $k)>
56 This function allocates memory for a new combination with parameters $n, $k and
57 initializes it to the lexicographically first combination.
59 =item * C<gsl_combination_init_first($c)>
61 This function initializes the combination $c to the lexicographically first
62 combination, i.e. (0,1,2,...,k-1). 
64 =item * C<gsl_combination_init_last($c)>
66 This function initializes the combination $c to the lexicographically last
67 combination, i.e. (n-k,n-k+1,...,n-1). 
69 =item * C<gsl_combination_free($c)>
71 This function frees all the memory used by the combination $c.
73 =item * C<gsl_combination_memcpy($dest, $src)>
75 This function copies the elements of the combination $src into the combination
76 $dest. The two combinations must have the same size.
78 =item * C<gsl_combination_get($c, $i)>
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.
84 =item * C<gsl_combination_fwrite($stream, $c)>
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.
92 =item * C<gsl_combination_fread($stream, $c)>
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.
102 =item * C<gsl_combination_fprintf($stream, $c, $format)>
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.
111 =item * C<gsl_combination_fscanf($stream, $c)>
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.
118 =item * C<gsl_combination_n($c)>
120 This function returns the range (n) of the combination $c.
122 =item * C<gsl_combination_k($c)>
124 This function returns the number of elements (k) in the combination $c.
126 =item * C<gsl_combination_data($c)>
128 This function returns a pointer to the array of elements in the combination $c.
130 =item * C<gsl_combination_valid($c)>
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.
136 =item * C<gsl_combination_next($c)>
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.
144 =item * C<gsl_combination_prev($c)>
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.
150 =back
152 =cut
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;
162 sub as_list {
163     my $self=shift;
164     $self->get( [ 0 .. $self->elements - 1  ] );
167 sub get {
168     my ($self, $indices) = @_;
169     return map {  gsl_combination_get($self->{_combination}, $_ ) } @$indices ;
172 sub raw { (shift)->{_combination} }
173 sub length { (shift)->{_length} }
175 sub elements { 
176     my $self = shift;
177     return gsl_combination_k($self->{_combination});
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    }
190 sub next {
191     my $self = shift;
192     my $status = gsl_combination_next($self->{_combination});
193     $self->status($status);
194     return $self;
197 sub prev {
198     my $self = shift;
199     my $status = gsl_combination_prev($self->{_combination});
200     $self->status($status);
201     return $status;
204 =head1 MORE INFO
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/>
209  Tip : search on google: site:http://www.gnu.org/software/gsl/manual/html_node/ name_of_the_function_you_want
212 =head1 AUTHORS
214 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
216 =head1 COPYRIGHT AND LICENSE
218 Copyright (C) 2008-2009 Jonathan Leto and Thierry Moisan
220 This program is free software; you can redistribute it and/or modify it
221 under the same terms as Perl itself.
223 =cut