.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Math::GSL::Combination 3pm"
.TH Math::GSL::Combination 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Math::GSL::Combination \- Combinations
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    use Math::GSL qw/:all/;
\&    use Math::GSL::Combination qw/:all/;
\&
\&    my $c   = Math::GSL::Combination\->new(6,3);
\&    print join (" ", $c\->as_list) . "\en";
\&    $c\->next;
\&    print join (" ", $c\->as_list) . "\en";
\&
\&    my $fd = gsl_fopen(\*(Aqcombination.dat\*(Aq, \*(Aqw\*(Aq);
\&    gsl_combination_fwrite($fd, $c\->raw);
\&    gsl_fclose($fd);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Here is a list of all the functions in this module :
.IP \(bu 4
\&\f(CW\*(C`gsl_combination_alloc($n, $k)\*(C'\fR
.Sp
This function allocates memory for a new combination with parameters \f(CW$n\fR, \f(CW$k\fR.
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.
.IP \(bu 4
\&\f(CW\*(C`gsl_combination_calloc($n, $k)\*(C'\fR
.Sp
This function allocates memory for a new combination with parameters \f(CW$n\fR, \f(CW$k\fR and
initializes it to the lexicographically first combination.
.IP \(bu 4
\&\f(CWgsl_combination_init_first($c)\fR
.Sp
This function initializes the combination \f(CW$c\fR to the lexicographically first
combination, i.e. (0,1,2,...,k\-1).
.IP \(bu 4
\&\f(CWgsl_combination_init_last($c)\fR
.Sp
This function initializes the combination \f(CW$c\fR to the lexicographically last
combination, i.e. (n\-k,n\-k+1,...,n\-1).
.IP \(bu 4
\&\f(CWgsl_combination_free($c)\fR
.Sp
This function frees all the memory used by the combination \f(CW$c\fR.
.IP \(bu 4
\&\f(CW\*(C`gsl_combination_memcpy($dest, $src)\*(C'\fR
.Sp
This function copies the elements of the combination \f(CW$src\fR into the combination
\&\f(CW$dest\fR. The two combinations must have the same size.
.IP \(bu 4
\&\f(CW\*(C`gsl_combination_get($c, $i)\*(C'\fR
.Sp
This function returns the value of the i\-th element of the combination \f(CW$c\fR. If
\&\f(CW$i\fR lies outside the allowed range of 0 to k\-1 then the error handler is invoked
and 0 is returned.
.IP \(bu 4
\&\f(CW\*(C`gsl_combination_fwrite($stream, $c)\*(C'\fR
.Sp
This function writes the elements of the combination \f(CW$c\fR to the stream \f(CW$stream\fR,
opened with the gsl_fopen function from the Math::GSL module, in binary format.
The function returns \f(CW$GSL_EFAILED\fR 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.
.IP \(bu 4
\&\f(CW\*(C`gsl_combination_fread($stream, $c)\*(C'\fR
.Sp
This function reads elements from the open stream \f(CW$stream\fR, opened with the
gsl_fopen function from the Math::GSL module, into the combination \f(CW$c\fR in binary
format. The combination \f(CW$c\fR must be preallocated with correct values of n and k
since the function uses the size of \f(CW$c\fR to determine how many bytes to read. The
function returns \f(CW$GSL_EFAILED\fR 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.
.IP \(bu 4
\&\f(CW\*(C`gsl_combination_fprintf($stream, $c, $format)\*(C'\fR
.Sp
This function writes the elements of the combination \f(CW$c\fR line-by-line to the
stream \f(CW$stream\fR, opened with the gsl_fopen function from the Math::GSL module,
using the format specifier \f(CW$format\fR, which should be suitable for a type of
size_t. In ISO C99 the type modifier z represents size_t, so "%zu\en" is a
suitable format. The function returns \f(CW$GSL_EFAILED\fR if there was a problem
writing to the file.
.IP \(bu 4
\&\f(CW\*(C`gsl_combination_fscanf($stream, $c)\*(C'\fR
.Sp
This function reads formatted data from the stream \f(CW$stream\fR into the combination
\&\f(CW$c\fR. The combination \f(CW$c\fR must be preallocated with correct values of n and k
since the function uses the size of \f(CW$c\fR to determine how many numbers to read.
The function returns \f(CW$GSL_EFAILED\fR if there was a problem reading from the file.
.IP \(bu 4
\&\f(CWgsl_combination_n($c)\fR
.Sp
This function returns the range (n) of the combination \f(CW$c\fR.
.IP \(bu 4
\&\f(CWgsl_combination_k($c)\fR
.Sp
This function returns the number of elements (k) in the combination \f(CW$c\fR.
.IP \(bu 4
\&\f(CWgsl_combination_data($c)\fR
.Sp
This function returns a pointer to the array of elements in the combination \f(CW$c\fR.
.IP \(bu 4
\&\f(CWgsl_combination_valid($c)\fR
.Sp
This function checks that the combination \f(CW$c\fR 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.
.IP \(bu 4
\&\f(CWgsl_combination_next($c)\fR
.Sp
This function advances the combination \f(CW$c\fR to the next combination in
lexicographic order and returns \f(CW$GSL_SUCCESS\fR. If no further combinations are
available it returns \f(CW$GSL_FAILURE\fR and leaves \f(CW$c\fR unmodified. Starting with the
first combination and repeatedly applying this function will iterate through
all possible combinations of a given order.
.IP \(bu 4
\&\f(CWgsl_combination_prev($c)\fR
.Sp
This function steps backwards from the combination \f(CW$c\fR to the previous
combination in lexicographic order, returning \f(CW$GSL_SUCCESS\fR. If no previous
combination is available it returns \f(CW$GSL_FAILURE\fR and leaves \f(CW$c\fR unmodified.
.SH "MORE INFO"
.IX Header "MORE INFO"
For more information on the functions, we refer you to the GSL official
documentation: <http://www.gnu.org/software/gsl/manual/html_node/>
.SH AUTHORS
.IX Header "AUTHORS"
Jonathan "Duke" Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2008\-2023 Jonathan "Duke" Leto and Thierry Moisan
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.