[boost] [Boost.Range] Documentation

12 Jul 2017

      I had a need to try and understand Boost.Range. I don't know what to say,
did this documentation pass a review?

Introduction first "example":

Example - Iterate over the values in a map

using namespace boost;
using namespace boost::adaptors;
for_each( my_map | map_values, fn );

3 lines, out of which 2 'using' lines, that make this "example" even less
informative than it might have been without them, in wich case I would at
least have known in which namespace(s) these things are living.

Ah, wait, there's also an example section, so I'll copy the first example
<http://www.boost.org/doc/libs/1_64_0/libs/range/test/string.cpp> in here:

// Boost.Range library
//
//  Copyright Thorsten Ottosen 2003-2004. Use, modification and
//  distribution is subject to the Boost Software License, Version
//  1.0. (See accompanying file LICENSE_1_0.txt or copy at
//  http://www.boost.org/LICENSE_1_0.txt)
//
// For more information, see http://www.boost.org/libs/range/
<http://www.boost.org/doc/libs/1_64_0/libs/range/>
//

//#define _MSL_USING_NAMESPACE 1

#include <boost/detail/workaround.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/detail/workaround.hpp>>

#if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x564))
#  pragma warn -8091 // suppress warning in Boost.Test
#  pragma warn -8057 // unused argument argc/argv in Boost.Test
#endif

#include <boost/array.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/array.hpp>>
#include <boost/range/as_array.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/range/as_array.hpp>>
#include <boost/range/as_literal.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/range/as_literal.hpp>>
#include <boost/range/functions.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/range/functions.hpp>>
#include <boost/range/metafunctions.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/range/metafunctions.hpp>>
#include <boost/static_assert.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/static_assert.hpp>>
#include <boost/type_traits.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/type_traits.hpp>>
#include <boost/test/test_tools.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/test/test_tools.hpp>>
#include <boost/config.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/config.hpp>>
#include <vector>
#include <fstream>
#include <algorithm>

namespace
{
    template< class CharT, std::size_t Length >
    class test_string
    {
    public:
        typedef CharT value_type;
        typedef value_type* pointer;
        typedef const value_type* const_pointer;
        typedef std::size_t size_type;
        typedef value_type array_t[Length];
        typedef const value_type const_array_t[Length];

        explicit test_string(const CharT literal_sz[])
        {
            std::copy(literal_sz, literal_sz + Length, m_buffer.data());
            m_buffer[Length] = value_type();
        }

        const_pointer const_sz() const { return m_buffer.data(); }
        pointer mutable_sz() { return m_buffer.data(); }

    private:
        typedef boost::array<value_type, Length + 1> buffer_t;
        buffer_t m_buffer;
    };
}

template< class T >
inline BOOST_DEDUCED_TYPENAME boost::range_iterator<T>::type
str_begin( T& r )
{
    return boost::begin( boost::as_literal(r) );
}

template< class T >
inline BOOST_DEDUCED_TYPENAME boost::range_iterator<T>::type
str_end( T& r )
{
    return boost::end( boost::as_literal(r) );
}

template< class T >
inline BOOST_DEDUCED_TYPENAME boost::range_difference<T>::type
str_size( const T& r )
{
    return boost::size( boost::as_literal(r) );
}

template< class T >
inline bool
str_empty( T& r )
{
    return boost::empty( boost::as_literal(r) );
}

template< typename Container, typename T >
BOOST_DEDUCED_TYPENAME boost::range_iterator<Container>::type
find( Container& c,  T value )
{
    return std::find( str_begin(c), str_end(c),
                      value );
}

template< typename Container, typename T >
BOOST_DEDUCED_TYPENAME boost::range_iterator<const Container>::type
find( const Container& c, T value )
{
    return std::find( str_begin(c), str_end(c),
                      value );
}

template< typename Container, typename T >
BOOST_DEDUCED_TYPENAME boost::range_iterator<Container>::type
find_mutable( Container& c,  T value )
{
    str_size( c );
    return std::find( str_begin(c), str_end(c),
                      value );
}

template< typename Container, typename T >
BOOST_DEDUCED_TYPENAME boost::range_iterator<const Container>::type
find_const( const Container& c, T value )
{
    str_size( c );
    return std::find( str_begin(c), str_end(c),
                      value );
}

std::vector<char>
check_rvalue_return()
{
    return std::vector<char>( 10, 'm' );
}

using namespace boost;

void check_char()
{
    typedef boost::range_difference<std::string>::type diff_t;
    typedef char*                  char_iterator_t;
    typedef char                   char_array_t[10];

    test_string<char, 8> a_string("a string");
    test_string<char, 14> another_string("another string");

    const char*      char_s = a_string.const_sz();
    char             my_string[] = "another_string";
    const char       my_const_string[] = "another string";
    const diff_t     my_string_length = 14;
    char*            char_s2 = a_string.mutable_sz();

    BOOST_STATIC_ASSERT(( is_same<  range_value<char_iterator_t>::type,

detail::iterator_traits<char_iterator_t>::value_type>::value ));
    BOOST_STATIC_ASSERT(( is_same<
range_iterator<char_iterator_t>::type, char_iterator_t >::value ));

    BOOST_STATIC_ASSERT(( is_same<  range_difference<char_iterator_t>::type,
                                    ::std::ptrdiff_t >::value ));
    BOOST_STATIC_ASSERT(( is_same<  range_size<char_iterator_t>::type,
std::size_t >::value ));
    BOOST_STATIC_ASSERT(( is_same<
range_iterator<char_iterator_t>::type, char_iterator_t >::value ));
    BOOST_STATIC_ASSERT(( is_same<  range_iterator<const char*>::type,
const char* >::value ));

    BOOST_STATIC_ASSERT(( is_same< range_value<char_array_t>::type,
                                    char>::value ));
    BOOST_STATIC_ASSERT(( is_same< range_iterator<char_array_t>::type,
char* >::value ));
    BOOST_STATIC_ASSERT(( is_same< range_iterator<const
char_array_t>::type, const char* >::value ));
    BOOST_STATIC_ASSERT(( is_same< range_difference<char_array_t>::type,
                                    ::std::ptrdiff_t >::value ));
    BOOST_STATIC_ASSERT(( is_same< range_size<char_array_t>::type,
std::size_t >::value ));
    BOOST_STATIC_ASSERT(( is_same< range_iterator<char_array_t>::type,
char* >::value ));
    BOOST_STATIC_ASSERT(( is_same< range_iterator<const
char_array_t>::type, const char* >::value ));

    BOOST_CHECK_EQUAL( str_begin( char_s ), char_s );
    const diff_t sz = str_size(char_s);
    const char* str_end1 = str_begin( char_s ) + sz;
    BOOST_CHECK_EQUAL( str_end( char_s ), str_end1 );
    BOOST_CHECK_EQUAL( str_empty( char_s ), (char_s == 0 || char_s[0]
== char()) );
    BOOST_CHECK_EQUAL( sz,
static_cast<diff_t>(std::char_traits<char>::length(char_s)) );

    BOOST_CHECK_EQUAL( str_begin( my_string ), my_string );
    range_iterator<char_array_t>::type str_end2 = str_begin( my_string
) + str_size(my_string);
    range_iterator<char_array_t>::type str_end3 = str_end(my_string);
    BOOST_CHECK_EQUAL( str_end3, str_end2 );
    BOOST_CHECK_EQUAL( str_empty( my_string ), (my_string == 0 ||
my_string[0] == char()) );
    BOOST_CHECK_EQUAL( str_size( my_string ), my_string_length );
    BOOST_CHECK_EQUAL( str_size( my_string ),
static_cast<diff_t>(std::char_traits<char>::length(my_string)) );

    char to_search = 'n';
    BOOST_CHECK( find_mutable( char_s, to_search ) != str_end( char_s ) );
    BOOST_CHECK( find_const( char_s, to_search ) != str_end(char_s) );

    BOOST_CHECK( find_mutable( my_string, to_search ) != str_end(my_string) );
    BOOST_CHECK( find_const( my_string, to_search ) != str_end(my_string) );

    BOOST_CHECK( find_mutable( char_s2, to_search ) != str_end(char_s) );
    BOOST_CHECK( find_const( char_s2, to_search ) != str_end(char_s2) );

    BOOST_CHECK( find_const( as_array( my_string ), to_search ) !=
str_end(my_string) );
    BOOST_CHECK( find_const( as_array( my_const_string ), to_search )
!= str_end(my_string) );

    //
    // Test that as_literal() always scan for null terminator
    //
    char an_array[] = "foo\0bar";
    BOOST_CHECK_EQUAL( str_begin( an_array ), an_array );
    BOOST_CHECK_EQUAL( str_end( an_array ), an_array + 3 );
    BOOST_CHECK_EQUAL( str_size( an_array ), 3 );

    const char a_const_array[] = "foobar\0doh";
    BOOST_CHECK_EQUAL( str_begin( a_const_array ), a_const_array );
    BOOST_CHECK_EQUAL( str_end( a_const_array ), a_const_array + 6 );
    BOOST_CHECK_EQUAL( str_size( a_const_array ), 6 );

}

void check_string()
{
    check_char();

#ifndef BOOST_NO_STD_WSTRING
    typedef wchar_t*               wchar_iterator_t;

    test_string<wchar_t, 13> a_wide_string(L"a wide string");
    test_string<wchar_t, 19> another_wide_string(L"another wide string");

    const wchar_t*  char_ws      = a_wide_string.const_sz();
    wchar_t         my_wstring[] = L"another wide string";
    wchar_t*        char_ws2     = a_wide_string.mutable_sz();

    BOOST_STATIC_ASSERT(( is_same< range_value<wchar_iterator_t>::type,

detail::iterator_traits<wchar_iterator_t>::value_type>::value ));
    BOOST_STATIC_ASSERT(( is_same<
range_iterator<wchar_iterator_t>::type, wchar_iterator_t >::value ));
    BOOST_STATIC_ASSERT(( is_same< range_iterator<const
wchar_t*>::type, const wchar_t* >::value ));
    BOOST_STATIC_ASSERT(( is_same< range_difference<wchar_iterator_t>::type,

detail::iterator_traits<wchar_iterator_t>::difference_type >::value
));
    BOOST_STATIC_ASSERT(( is_same< range_size<wchar_iterator_t>::type,
std::size_t >::value ));
    BOOST_STATIC_ASSERT(( is_same<
range_iterator<wchar_iterator_t>::type, wchar_iterator_t >::value ));
    BOOST_STATIC_ASSERT(( is_same< range_iterator<const
wchar_t*>::type, const wchar_t* >::value ));

    typedef boost::range_difference<std::wstring>::type diff_t;
    const diff_t sz = str_size( char_ws );
    BOOST_CHECK_EQUAL( str_begin( char_ws ), char_ws );
    BOOST_CHECK_EQUAL( str_end(char_ws), (str_begin( char_ws ) + sz) );
    BOOST_CHECK_EQUAL( str_empty( char_ws ), (char_ws == 0 ||
char_ws[0] == wchar_t()) );
    BOOST_CHECK_EQUAL( sz,
static_cast<diff_t>(std::char_traits<wchar_t>::length(char_ws)) );

    wchar_t to_search = L'n';
    BOOST_CHECK( find( char_ws, to_search ) != str_end(char_ws) );
    BOOST_CHECK( find( char_ws2, to_search ) != str_end(char_ws2) );

#if BOOST_WORKAROUND(_MSC_VER, BOOST_TESTED_AT(1300))

    BOOST_CHECK( find( my_wstring, to_search ) != str_end(my_wstring) );

#else

    boost::ignore_unused_variable_warning( my_wstring );

#endif
#endif

    find( check_rvalue_return(), 'n' );

}

#include <boost/test/unit_test.hpp
<http://www.boost.org/doc/libs/1_64_0/boost/test/unit_test.hpp>>
using boost::unit_test::test_suite;

test_suite* init_unit_test_suite( int argc, char* argv[] )
{
    test_suite* test = BOOST_TEST_SUITE( "Range Test Suite" );

    test->add( BOOST_TEST_CASE( &check_string ) );

    return test;
}

Well, that obviously got me up and running, thanks.

Is there any other documentation/examples to have a look at?

degski
-- 
"*Ihre sogenannte Religion wirkt bloß wie ein Opiat reizend, betäubend,
Schmerzen aus Schwäche stillend.*" - Novalis 1798