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 ### wrapper interface ###
  35
  36 sub new {
  37     my ($class, $n, $k) = @_;
  38     my $this = {};
  39     $this->{_length} = $n;
  40     $this->{_combination} = gsl_combination_calloc($n, $k);
  41     bless $this, $class;
  42 }
  43
  44 sub as_list {
  45     my $self=shift;
  46     $self->get( [ 0 .. $self->elements - 1  ] );
  47 }
  48
  49 sub get {
  50     my ($self, $indices) = @_;
  51     return  map {  gsl_combination_get($self->{_combination}, $_ ) } @$indices ;
  52 }
  53
  54 sub raw { (shift)->{_combination} }
  55 sub length { (shift)->{_length} }
  56
  57 sub elements {
  58     my $self = shift;
  59     return gsl_combination_k($self->{_combination});
  60 }
  61
  62 sub status {
  63     my ($self,$status) = @_;
  64     if (defined $status) {
  65         $self->{status} = $status;
  66         return $self;
  67     } else {
  68         return $self->{status};
  69    }
  70 }
  71
  72 sub next {
  73     my $self = shift;
  74     my $status = gsl_combination_next($self->{_combination});
  75     $self->status($status);
  76     return $self;
  77 }
  78
  79 sub prev {
  80     my $self = shift;
  81     my $status = gsl_combination_prev($self->{_combination});
  82     $self->status($status);
  83     return $status;
  84 }
  85
  86 __END__
  87
  88 =head1 NAME
  89
  90 Math::GSL::Combination - Functions for creating and manipulating combinations
  91
  92 =head1 SYNOPSIS
  93
  94 use Math::GSL::Combination qw /:all/;
  95
  96 =head1 DESCRIPTION
  97
  98 Here is a list of all the functions in this module :
  99
 100 =over
 101
 102 =item * C<gsl_combination_alloc($n, $k)> - This function allocates memory for a new combination with parameters $n, $k. The combination is not initialized and its elements are undefined. Use the function gsl_combination_calloc if you want to create a combination which is initialized to the lexicographically first combination.
 103
 104 =item * C<gsl_combination_calloc($n, $k)> - This function allocates memory for a new combination with parameters $n, $k and initializes it to the lexicographically first combination.
 105
 106 =item * C<gsl_combination_init_first($c)> - This function initializes the combination $c to the lexicographically first combination, i.e. (0,1,2,...,k-1).
 107
 108 =item * C<gsl_combination_init_last($c)> - This function initializes the combination $c to the lexicographically last combination, i.e. (n-k,n-k+1,...,n-1).
 109
 110 =item * C<gsl_combination_free($c)> - This function frees all the memory used by the combination $c.
 111
 112 =item * C<gsl_combination_memcpy($dest, $src)> - This function copies the elements of the combination $src into the combination $dest. The two combinations must have the same size.
 113
 114 =item * C<gsl_combination_get($c, $i)> - This function returns the value of the i-th element of the combination $c. If $i lies outside the allowed range of 0 to k-1 then the error handler is invoked and 0 is returned.
 115
 116 =item * C<gsl_combination_fwrite($stream, $c)> - This function writes the elements of the combination $c to the stream $stream, opened with the gsl_fopen function from the Math::GSL module, in binary format. The function returns $GSL_EFAILED if there was a problem writing to the file. Since the data is written in the native binary format it may not be portable between different architectures.
 117
 118 =item * C<gsl_combination_fread($stream, $c)> - This function reads elements from the open stream $stream, opened with the gsl_fopen function from the Math::GSL module, into the combination $c in binary format. The combination $c must be preallocated with correct values of n and k since the function uses the size of $c to determine how many bytes to read. The function returns $GSL_EFAILED if there was a problem reading from the file. The data is assumed to have been written in the native binary format on the same architecture.
 119
 120 =item * C<gsl_combination_fprintf($stream, $c, $format)> - This function writes the elements of the combination $c line-by-line to the stream $stream, opened with the gsl_fopen function from the Math::GSL module, using the format specifier $format, which should be suitable for a type of size_t. In ISO C99 the type modifier z represents size_t, so "%zu\n" is a suitable format. The function returns $GSL_EFAILED if there was a problem writing to the file.
 121
 122 =item * C<gsl_combination_fscanf($stream, $c)> -This function reads formatted data from the stream $stream into the combination $c. The combination $c must be preallocated with correct values of n and k since the function uses the size of $c to determine how many numbers to read. The function returns $GSL_EFAILED if there was a problem reading from the file.
 123
 124 =item * C<gsl_combination_n($c)> - This function returns the range (n) of the combination $c.
 125
 126 =item * C<gsl_combination_k($c)> - This function returns the number of elements (k) in the combination $c.
 127
 128 =item * C<gsl_combination_data($c)> - This function returns a pointer to the array of elements in the combination $c.
 129
 130 =item * C<gsl_combination_valid($c)> - This function checks that the combination $c is valid. The k elements should lie in the range 0 to n-1, with each value occurring once at most and in increasing order.
 131
 132 =item * C<gsl_combination_next($c)> - This function advances the combination $c to the next combination in lexicographic order and returns $GSL_SUCCESS. If no further combinations are available it returns $GSL_FAILURE and leaves $c unmodified. Starting with the first combination and repeatedly applying this function will iterate through all possible combinations of a given order.
 133
 134 =item * C<gsl_combination_prev($c)> - This function steps backwards from the combination $c to the previous combination in lexicographic order, returning $GSL_SUCCESS. If no previous combination is available it returns $GSL_FAILURE and leaves $c unmodified.
 135
 136 =back
 137
 138
 139 For more informations on the functions, we refer you to the GSL offcial
 140 documentation: L<http://www.gnu.org/software/gsl/manual/html_node/>
 141
 142  Tip : search on google: site:http://www.gnu.org/software/gsl/manual/html_node/ name_of_the_function_you_want
 143
 144
 145 =head1 AUTHORS
 146
 147 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 148
 149 =head1 COPYRIGHT AND LICENSE
 150
 151 Copyright (C) 2008 Jonathan Leto and Thierry Moisan
 152
 153 This program is free software; you can redistribute it and/or modify it
 154 under the same terms as Perl itself.
 155
 156 =cut
 157
 158 %}