add documentation for combinations (#5390)

Author: mjrodgers

docs/doc.main

@@ -291,6 +291,7 @@
     "Combinatorics/simplicialcomplexes.md",
     "Combinatorics/phylogenetic_trees.md",
     "Enumerative combinatorics" => [
+      "Combinatorics/EnumerativeCombinatorics/combinations.md",
       "Combinatorics/EnumerativeCombinatorics/partitions.md",
       "Combinatorics/EnumerativeCombinatorics/multipartitions.md",
       "Combinatorics/EnumerativeCombinatorics/tableaux.md",

docs/src/Combinatorics/EnumerativeCombinatorics/combinations.md

@@ -0,0 +1,43 @@
+```@meta
+CurrentModule = Oscar
+CollapsedDocStrings = true
+DocTestSetup = Oscar.doctestsetup()
+```
+
+# Combinations
+
+A **combination** from a set $S$ is a selection $\lambda_1, \lambda_2 \dots \lambda_r$ of elements of $S$ taken without repetition; the order of the elements is considered not to matter. A $k$-combination is a combination consisting of $k$ elements.
+A general reference on combinations is [Knu11](@cite), Section 7.2.1.3.
+
+A combination can be encoded as an array with elements $\lambda_i$.
+In OSCAR, the parametric type `Combination{T}` is provided which is a subtype of `AbstractVector{T}`.
+Here, `T` can be any subtype of `IntegerUnion`.
+The parametric type allows one to increase performance by using smaller integer types.
+```julia
+julia> @time collect(combinations(20,10));
+  0.010399 seconds (184.76 k allocations: 26.782 MiB)
+
+julia> @time collect(combinations(Int8(20),10));
+  0.008780 seconds (184.76 k allocations: 12.686 MiB)
+```
+
+
+## Generating
+
+```@docs
+combinations(n::IntegerUnion, k::IntegerUnion)
+combinations(v::AbstractVector, k::IntegerUnion)
+```
+
+Because `Combination` is a subtype of `AbstractVector`, many functions that can be used for vectors (1-dimensional arrays) can be used for combinations as well.
+For example:
+```jldoctest
+julia> C = Combination([6, 4, 4, 2])
+[6, 4, 4, 2]
+
+julia> length(C)
+4
+
+julia> C[1]
+6
+```

docs/src/Combinatorics/EnumerativeCombinatorics/partitions.md

@@ -13,7 +13,6 @@ General references on partitions are [Ful97](@cite) and [Knu11](@cite), Section
 A partition can be encoded as an array with elements $\lambda_i$.
 In OSCAR, the parametric type `Partition{T}` is provided which is a subtype of `AbstractVector{T}`.
 Here, `T` can be any subtype of `IntegerUnion`.
-There is no performance impact by using an own type for partitions rather than simply using arrays.
 The parametric type allows to increase performance by using smaller integer types.
 
 ```@docs

src/Combinatorics/EnumerativeCombinatorics/combinations.jl

@@ -1,5 +1,5 @@
 @doc raw"""
-    combinations(n::Int, k::Int)
+    combinations(n::IntegerUnion, k::IntegerUnion)
 
 Return an iterator over all $k$-combinations of ${1,...,n}$, produced in
 lexicographically ascending order.
@@ -18,10 +18,10 @@ julia> collect(C)
  [2, 3, 4]
 ```
 """
-combinations(n::Int, k::Int) = Combinations(Base.OneTo(n), k)
+combinations(n::IntegerUnion, k::IntegerUnion) = Combinations(Base.OneTo(n), k)
 
 @doc raw"""
-    combinations(v::AbstractVector, k::Int)
+    combinations(v::AbstractVector, k::IntegerUnion)
 
 Return an iterator over all `k`-combinations of a given vector `v` produced in
 lexicographically ascending order of the indices.
@@ -40,11 +40,11 @@ julia> collect(C)
  ['b', 'c', 'd']
 ```
 """
-function combinations(v::AbstractVector{T}, k::Int) where T
+function combinations(v::AbstractVector{T}, k::IntegerUnion) where T
   return Combinations(v, k)
 end
 
-Combinations(v::AbstractArray{T}, k::Int) where T = Combinations(v, length(v), k)
+Combinations(v::AbstractArray{T}, k::IntegerUnion) where T = Combinations(v, length(v), Int(k))
 
 @inline function Base.iterate(C::Combinations, state = [min(C.k - 1, i) for i in 1:C.k])
   if C.k == 0 # special case to generate 1 result for k = 0