    hi(next_permutation)
    itemization(
        it() Header file: tt(<algorithm>)
        it() Function prototypes:
        itemization(
            itt(bool next_permutation(BidirectionalIterator first,
                BidirectionalIterator last);)
            itt(bool next_permutation(BidirectionalIterator first,
                BidirectionalIterator last, Comp comp);)
        )
        it() Description:
        itemization(
            it() The first prototype: the next permutation, given the sequence
of elements in the range rangett(first, last), is determined. For example, if
the elements tt(1, 2) and tt(3) are the range for which tt(next_permutation)
is called, then subsequent calls of tt(next_permutation) reorders the
following series:
        verb(
        1 2 3
        1 3 2
        2 1 3
        2 3 1
        3 1 2
        3 2 1
    )
    This example shows that the elements are reordered such that each new
permutation represents the next bigger value (132 is bigger than 123, 213 is
bigger than 132, etc.) using ti(operator<) of the data type to which the
iterators point.  The value ti(true) is returned if a reordering took place,
the value ti(false) is returned if no reordering took place, which is the case
if the sequence represents the last (biggest) value. In that case, the
sequence is also sorted using tt(operator<).
        it() The second prototype: the next permutation given the sequence of
elements in the range rangett(first, last) is determined, using the binary
predicate tt(comp) to compare elements. The elements in the range are
reordered. The value tt(true) is returned if a reordering took place, the
value tt(false) is returned if no reordering took place, which is the case if
the resulting sequence would haven been ordered using the binary predicate
tt(comp) to compare elements.
        )
    it() Example:
        verbinclude(-a examples/nextpermutation.cc)
    )
