Declarations of public functions associated with group_C.
Version of Sunday 15 September 2024.

    /* C1 */ template <typename sii> requires std::input_iterator<sii>
                 permzbi (sii begin, sii end);
    /* C1 */ explicit permzbi (SVI const & v);  
    /* C1 */ explicit permzbi (SVI && v); 
    /* C1 */ permzbi (std::initializer_list<int> const & i);
    /* C1 */ permzbi (int const Z, std::initializer_list<int> const i);
    /* C1 */ int size () const;

The next four declarations pertain to output and input formatting, with put_text supporting operator<< and get_text supporting operator>>. Function get_text (hence operator>>) will read anything produced by put_text (hence operator<<).

Some permzbis have an internal structure of sorts, and the spacing_s in function put_text allow text_divider characters to be inserted periodically to make that structure clearer. Of course, a parameter of zero means to omit the text_dividers.

    /* C2 */ void put_text (
                 std::ostream & text_out, 
                 int const spacing_a = 0,
                 int const spacing_b = 0,
                 int const spacing_c = 0
             ) const;
    /* C2 */ static void text_filler (std::ostream & text_out, int const Z);
    static char constexpr text_divider {':'};

    /* C3 */ static permzbi get_text (std::istream & text_in);
    /* C3 */ friend permzbi operator""_pz (char const* const s, size_t const);

The formatting of text input and output is explained on its own page.

Some useful permutations:

    /* C4 */ static permzbi first_perm (int const Z);
    /* C4 */ static permzbi last_perm_lex (int const Z); // lexicographical
    /* C4 */ static permzbi last_perm_SJT (int const Z); // Steinhaus–Johnson–Trotter

random, below, provides different permzbis (almost) every time the program is executed. By contrast, random_seeded will provide the same permzbi every time that it is executed with the same parameters in the same environment. Differing compilers, operating systems, and hardware may affect this value. These two functions are convenient for generating "random-looking" permzbis for testing, but are not claimed to be cryptographically secure.

    /* C4 */ static permzbi random (int const Z);
    /* C4 */ static permzbi random_seeded (int const Z, int const seed);

The next three declarations are for component lookup. Each v_at_i returns the value at an index; it is equivalent to the at function found in the Standard Library's containers. This includes the checking of bounds when permzbi_lib_safe == true. v_all returns a constant reference to p_guts. i_of_v performs a search to return the index where a value is stored.

    /* C4 */ int v_at_i (int const index) const;
    /* C4 */ SVI const & v_all () const;
    /* C4 */ int i_of_v (int const value) const;

operator== and its five counterparts are not declared as the defaults of operator<=> because these throw an exception if the permzbis have different numbers of elements. Comparisons, when made, are lexicographical, as is the C++ default.

By contrast, key_equal_to and key_less, also lexicographical, will compare any two permzbis; these function objects are proved for use with unordered associative containers and ordered associative containers respectively. These key_ functions allow a container to hold permzbis of different sizes.

Although this program does not use associative containers except for testing its support of the same, a user might need them. The other four customary comparisons for key_ are easy to define if needed.

    /* C5 */ bool operator== (permzbi const & b) const;        
    /* C5 */ bool operator!= (permzbi const & b) const;        
    /* C5 */ bool operator<= (permzbi const & b) const;        
    /* C5 */ bool operator>= (permzbi const & b) const;        
    /* C5 */ bool operator<  (permzbi const & b) const;        
    /* C5 */ bool operator>  (permzbi const & b) const;        
    /* C5 */ struct key_equal_to;
    /* C5 */ struct key_less;

These comparisons are implemented as class members, but some users might opt to make them non-members.