group_B: Utility declarations in namespace permsbi_lib.
Version of Wednesday 11 September 2024.

Appearing in file group_A/permzbi_A1.h are the following utility declarations. The comments /* B1 */, /* B2 */, etc indicate that the definitions appear in files group_B/permzbi_B1.h, group_B/permzbi_B2.h, etc. The same file-name convention is used throughout the entire program.

    using SVI   = std::vector<int>;
    using SVSVI = std::vector<SVI>;
    using SVB   = std::vector<bool>;

Remember the usual caution that std::vector<bool> is not actually a std::vector.

This is the only place in the program where std::vector<int> is mentioned by name. This localization is to aid the programmer who chooses to substitute some other container that is felt to be superior. Two well-known alternatives are:

• boost::container::static_vector, which provides a hard ceiling on size; and
• boost::container::small_vector, which provides a soft ceiling.

More contents:

    /* B1 */ struct prod_fail;
        // is thrown for errors in production code. 
        // When permzbi_lib_safe is false, nearly all the
        // tests will be omitted, at the programmer's risk. 

    /* B1 */ struct test_fail;
        // is thrown for errors in test code. 
        // The related tests will always be performed.

    // Either way, some errors will percolate up from the Standard Library. 

    /* B1 */ std::ostream & operator<< 
                 (std::ostream & o, SVI const & vec);
    /* B1 */ std::ostream & operator<< 
                 (std::ostream & o, SVSVI const & vec);
    /* B1 */ std::ostream & operator<< 
                 (std::ostream & text_out, SVB const & vec);
                 
    /* B1 */ bool all_in_range (SVI const & v);
    /* B1 */ bool any_two_equal (SVI const & v);
    /* B1 */ bool pre_verify (SVI const & v);

The last three functions assist in determining whether the components of an SVI are fit for use as a permzbi.

    /* B1 */ SVSVI transpose (SVSVI const & o);
        // similar to the transpose of a matrix

    /* B1 */ SVI flatten (SVSVI const & o);
        // converts an SVSVI into an SVI by catenating the component SVIs.

    /* B2 */ int mod (int const num, int const den);
    /* B2 */ int quo (int const num, int const den);
    /* B2 */ int gcd (int x, int y);
    /* B2 */ int lcm (int const x, int const y);

Functions mod and quo differ from the built-in operator% and operator/, while gcd and lcm differ from their Standard Library counterparts. This is because permzbi requires specific treatment of negative numbers.

    /* B2 */ bool is_even (int const i);
    /* B2 */ bool is_odd (int const i);
    /* B2 */ void view_bits (std::ostream & o, unsigned int const i);

The two safe_ functions manage concerns about signed and unsigned chars.

    /* B2 */ bool safe_isspace (char const c); 
    /* B2 */ bool safe_isdigit (char const c);

    /* B3 */ bool ranking_is_same (SVI const & a, SVI const & b);    
    /* B3 */ SVI deflate (
                 SVI const & old_upper
             );
    /* B3 */ SVI inflate (
                 SVI const & old_upper, 
                 SVI const & old_lower,
                 SVI const & new_lower
             );

    /* Z1 */ void web_page_support ();

    constexpr int max_int {std::numeric_limits::max()};
    constexpr int min_int {std::numeric_limits::min()};