From 9f57159500880b945e96e99616da4de10cb23c7d Mon Sep 17 00:00:00 2001 From: Jonathan Leto Date: Fri, 10 Oct 2008 00:03:43 -0700 Subject: [PATCH] Refactor and improve Combination docs --- Combination.i | 186 +++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 132 insertions(+), 54 deletions(-) diff --git a/Combination.i b/Combination.i index eb4da1b..7c280f1 100644 --- a/Combination.i +++ b/Combination.i @@ -31,7 +31,136 @@ /; %EXPORT_TAGS = ( all => [ @EXPORT_OK ] ); -### wrapper interface ### +=head1 NAME + +Math::GSL::Combination - Functions for creating and manipulating combinations + +=head1 SYNOPSIS + + use Math::GSL qw/:all/; + use Math::GSL::Combination qw/:all/; + + my $c = Math::GSL::Combination->new(6,3); + print join (" ", $c->as_list) . "\n"; + $c->next; + print join (" ", $c->as_list) . "\n"; + + my $fd = gsl_fopen('combination.dat', 'w'); + gsl_combination_fwrite($fd, $c->raw); + gsl_fclose($fd); + +=head1 DESCRIPTION + +Here is a list of all the functions in this module : + +=over + +=item * C + +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. + +=item * C + +This function allocates memory for a new combination with parameters $n, $k and +initializes it to the lexicographically first combination. + +=item * C + +This function initializes the combination $c to the lexicographically first +combination, i.e. (0,1,2,...,k-1). + +=item * C + +This function initializes the combination $c to the lexicographically last +combination, i.e. (n-k,n-k+1,...,n-1). + +=item * C + +This function frees all the memory used by the combination $c. + +=item * C + +This function copies the elements of the combination $src into the combination +$dest. The two combinations must have the same size. + +=item * C + +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. + +=item * 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. + +=item * 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. + +=item * C + +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. + +=item * 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. + +=item * C + +This function returns the range (n) of the combination $c. + +=item * C + +This function returns the number of elements (k) in the combination $c. + +=item * C + +This function returns a pointer to the array of elements in the combination $c. + +=item * 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. + +=item * 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. + +=item * 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. + +=back + +=cut sub new { my ($class, $n, $k) = @_; @@ -48,7 +177,7 @@ sub as_list { sub get { my ($self, $indices) = @_; - return map { gsl_combination_get($self->{_combination}, $_ ) } @$indices ; + return map { gsl_combination_get($self->{_combination}, $_ ) } @$indices ; } sub raw { (shift)->{_combination} } @@ -83,58 +212,7 @@ sub prev { return $status; } -__END__ - -=head1 NAME - -Math::GSL::Combination - Functions for creating and manipulating combinations - -=head1 SYNOPSIS - -use Math::GSL::Combination qw /:all/; - -=head1 DESCRIPTION - -Here is a list of all the functions in this module : - -=over - -=item * C - 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. - -=item * C - This function allocates memory for a new combination with parameters $n, $k and initializes it to the lexicographically first combination. - -=item * C - This function initializes the combination $c to the lexicographically first combination, i.e. (0,1,2,...,k-1). - -=item * C - This function initializes the combination $c to the lexicographically last combination, i.e. (n-k,n-k+1,...,n-1). - -=item * C - This function frees all the memory used by the combination $c. - -=item * C - This function copies the elements of the combination $src into the combination $dest. The two combinations must have the same size. - -=item * C - 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. - -=item * 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. - -=item * 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. - -=item * C - 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. - -=item * 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. - -=item * C - This function returns the range (n) of the combination $c. - -=item * C - This function returns the number of elements (k) in the combination $c. - -=item * C - This function returns a pointer to the array of elements in the combination $c. - -=item * 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. - -=item * 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. - -=item * 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. - -=back - +=head1 MORE INFO For more informations on the functions, we refer you to the GSL offcial documentation: L -- 2.11.4.GIT