#
# = Combinations
# Contents:
# 1. {Combination allocation}[link:rdoc/combi_rdoc.html#label-Combination+allocation]
# 1. {Methods}[link:rdoc/combi_rdoc.html#label-Methods]
#    1. {Accessing combination elements}[link:rdoc/combi_rdoc.html#label-Accessing+combination+elements]
#    1. {Combination properties}[link:rdoc/combi_rdoc.html#label-Combination+properties]
#    1. {Combination functions}[link:rdoc/combi_rdoc.html#label-Combination+functions]
#    1. {Reading and writing combinations}[link:rdoc/combi_rdoc.html#label-Reading+and+writing+combinations]
#
# == Combination allocation
# ---
# * GSL::Combination.alloc(n, k)
#
#   These create a new combination with parameters <tt>n, k</tt>.
#   The combination is not initialized and its elements are undefined.
#   Use the method <tt>GSL::Combination.calloc</tt> if you want to create a
#   combination which is initialized to the lexicographically first combination.
#
# ---
# * GSL::Combination.calloc(n, k)
#
#   This creates a new combination with parameters <tt>n, k</tt> and initializes
#   it to the lexicographically first combination.
#
# == Methods
#
# ---
# * GSL::Combination#init_first
#
#   This method initializes the combination <tt>self</tt> to the lexicographically
#   first combination, i.e. (0,1,2,...,k-1).
#
# ---
# * GSL::Combination#init_last
#
#   This method initializes the combination <tt>self</tt> to the lexicographically last
#   combination, i.e. (n-k,n-k+1,...,n-1).
#
# === Accessing combination elements
# ---
# * GSL::Combination#get(i)
# * \GSL::Combination#[i]
#
#   This returns the value of the <tt>i</tt>-th element of the combination <tt>self</tt>.
#
# === Combination properties
# ---
# * GSL::Combination#n
#
#   Returns the <tt>n</tt> parameter of the combination <tt>self</tt>.
#
# ---
# * GSL::Combination#k
#
#   Returns the <tt>k</tt> parameter of the combination <tt>self</tt>.
#
# ---
# * GSL::Combination#data
#
#   Returns the vector of elements in the combination <tt>self</tt>.
#
# ---
# * GSL::Combination#valid
#
#   This method checks that the combination <tt>self</tt> is valid.
#   The <tt>k</tt> elements should contain numbers from range 0 .. n-1,
#   each number at most once. The numbers have to be in increasing order.
#
# ---
# * GSL::Combination#valid?
#
#   Thie returns true if the combination is valid, and false otherwise.
#
# === Combination functions
# ---
# * GSL::Combination#next
#
#   This method advances the combination <tt>self</tt> to the next combination in
#   lexicographic order and returns <tt>GSL::SUCCESS</tt>. If no further combinations are
#   available it returns <tt>GSL::FAILURE</tt> and leaves <tt>self</tt> unmodified.
#   Starting with the first combination and repeatedly applying this function will
#   iterate through all possible combinations of a given order.
#
# ---
# * GSL::Combination#prev
#
#   This method steps backwards from the combination <tt>self</tt> to the previous
#   combination in lexicographic order, returning <tt>GSL::SUCCESS</tt>.
#   If no previous combination is available it returns <tt>GSL::FAILURE</tt>
#   and leaves <tt>self</tt> unmodified.
#
# === Reading and writing combinations
# ---
# * GSL::Combination#fwrite(filename)
# * GSL::Combination#fwrite(io)
# * GSL::Combination#fread(filename)
# * GSL::Combination#fread(io)
# * GSL::Combination#fprintf(filename, format = "%u")
# * GSL::Combination#fprintf(io, format = "%u")
# * GSL::Combination#fscanf(filename)
# * GSL::Combination#fscanf(io)
#
#
# == Example
#      #!/usr/bin/env ruby
#      require("gsl")
#
#      printf("All subsets of {0,1,2,3} by size:\n") ;
#      for i in 0...4 do
#        c = GSL::Combination.calloc(4, i);
#        begin
#          printf("{");
#          c.fprintf(STDOUT, " %u");
#          printf(" }\n");
#        end while c.next == GSL::SUCCESS
#      end
#
# {prev}[link:rdoc/perm_rdoc.html]
# {next}[link:rdoc/sort_rdoc.html]
#
# {Reference index}[link:rdoc/ref_rdoc.html]
# {top}[link:index.html]
#
#