Boost.Range

概要及參考

簡介

本庫當前支持四種對像類型：

雖然主模板的缺省行為是要正確提供對標準容器的支持，但是其要求要低於標準容器的要求。例如，工具類 iterator_range 實現了滿足 前向區間 的 最小接口。

更多細節請參見 區間概念。

概要

namespace boost
{
    //
    // 單遍區間的元函數
    //
                   
    template< class T >
    struct range_iterator;
    
    template< class T >
    struct range_value;
  
    template< class T >
    struct range_reference;

    template< class T >
    struct range_pointer;
    
    template< class T >
    struct range_category;

    //
    // 前向區間的元函數
    //
    
    template< class T >
    struct range_difference;
    
    //
    // 雙向區間的元函數
    //
    
    template< class T >
    struct range_reverse_iterator;
    
    //
    // 單遍區間的函數
    //
    
    template< class T >
    typename range_iterator<T>::type
    begin( T& r );
    
    template< class T >
    typename range_iterator<const T>::type
    begin( const T& r );
        
    template< class T >
    typename range_iterator<T>::type
    end( T& r );
                      
    template< class T >
    typename range_iterator<const T>::type
    end( const T& r );
    
    template< class T >
    bool
    empty( const T& r );
               
    //
    // 前向區間的函數
    //
    
    template< class T >
    typename range_difference<T>::type
    distance( const T& r );
                            
    //
    // 雙向區間的函數
    //
                     
    template< class T >
    typename range_reverse_iterator<T>::type
    rbegin( T& r );
    
    template< class T >
    typename range_reverse_iterator<const T>::type
    rbegin( const T& r );
        
    template< class T >
    typename range_reverse_iterator<T>::type
    rend( T& r );
                      
    template< class T >
    typename range_reverse_iterator<const T>::type
    rend( const T& r );
    
    //
    // 隨機訪問區間的函數
    //
    
    template< class T >
    typename range_difference<T>::type
    size( const T& r );
    
    //
    // 特殊的常量區間函數
    // 
    
    template< class T >
    typename range_iterator<const T>::type 
    const_begin( const T& r );
    
    template< class T >
    typename range_iterator<const T>::type 
    const_end( const T& r );
    
    template< class T >
    typename range_reverse_iterator<const T>::type 
    const_rbegin( const T& r );
    
    template< class T >
    typename range_reverse_iterator<const T>::type 
    const_rend( const T& r );

    //
    // 字符串工具
    //
    
    template< class T >
    iterator_range<...see below...> 
    as_literal( T& r );

    template< class T >
    iterator_range<...see below...> 
    as_literal( const T& r );

    template< class T >
    iterator_range< typename range_iterator<T>::type > 
    as_array( T& r );

    template< class T >
    iterator_range< typename range_iterator<const T>::type > 
    as_array( const T& r );

} // namespace 'boost'

語義

符號

類型 對像 說明
X x 任意類型
T t 表示主模板的行為
P p 表示 std::pair<iterator,iterator>
A[sz] a 表示一個類型 A 的大小為 sz 的數組
Char* s 表示 char* 或 wchar_t*

請留意，下表中有些單元格有四行文字，其中第一行代表主模板，第二行代表迭代器對，第三行代表數組，最後一行代表空字符結尾的字符串。

元函數

表達式 返回類型 複雜度
range_iterator<X>::type T::iterator
P::first_type
A*
 編譯時間
range_iterator<const X>::type T::const_iterator
P::first_type
const A*
 編譯時間
range_value<X>::type boost::iterator_value<range_iterator<X>::type>::type 編譯時間
range_reference<X>::type boost::iterator_reference<range_iterator<X>::type>::type 編譯時間
range_pointer<X>::type boost::iterator_pointer<range_iterator<X>::type>::type 編譯時間
range_category<X>::type boost::iterator_category<range_iterator<X>::type>::type 編譯時間
range_difference<X>::type boost::iterator_difference<range_iterator<X>::type>::type 編譯時間
range_reverse_iterator<X>::type boost::reverse_iterator<range_iterator<X>::type>
 編譯時間
range_reverse_iterator<const X>::type boost::reverse_iterator<range_iterator<const X>::type>
編譯時間

函數

表達式 返回類型 返回 複雜度
begin(x) range_iterator<X>::type p.first 如果 p 為類型 std::pair<T>
a 如果 a 為數組
s 如果 s 為字符串字面值
boost_range_begin(x) 如果該表達式由 ADL 執行函數查找
否則 t.begin()   		常量時間
end(x) range_iterator<X>::type p.second 如果 p 為類型 std::pair<T>
a + sz 如果 a 是大小為 sz 的數組
s + std::char_traits<X>::length( s ) 如果 s 是 Char*
s + sz - 1 如果 s 是大小為 sz 的字符串字面值
boost_range_end(x) 如果該表達式由 ADL 執行函數查找
否則 t.end()   		常量時間
empty(x) bool boost::begin(x) == boost::end(x)
 常量時間 
distance(x) range_difference<X>::type std::distance(boost::begin(x),boost::end(x)) -
size(x) range_difference<X>::type boost::end(x) - boost::begin(x) 常量時間
rbegin(x) range_reverse_iterator<X>::type range_reverse_iterator<X>::type( boost::end(x) )
常量時間
rend(x) range_reverse_iterator<X>::type range_reverse_iterator<X>::type( boost::begin(x) ) 常量時間
const_begin(x) range_iterator<const X>::type range_iterator<const X>::type( boost::begin(x) )
常量時間
const_end(x) range_iterator<const X>::type range_iterator<const X>::type( boost::end(x) ) 常量時間
const_rbegin(x) range_reverse_iterator<const X>::type range_reverse_iterator<const X>::type( boost::rbegin(x) )
常量時間
const_rend(x) range_reverse_iterator<const X>::type range_reverse_iterator<const X>::type( boost::rend(x) ) 常量時間
as_literal(x) iterator_range<U> 其中 U 為 Char* 如果 x 是一個字符串指針，否則 U 為 range_iterator<X>::type  [s,s + std::char_traits<X>::length(s)) 如果 s 為 Char*
否則返回 [boost::begin(x),boost::end(x)) 		對於字符串指針為線性時間，否則為常量時間
as_array(x) iterator_range<X> [boost::begin(x),boost::end(x)) 否則為常量時間

特定的 const_ 函數可用於示意你的代碼為只讀。

as_literal() 可在能夠正確處理字符數組的字符串算法庫內部使用。

as_array() 可用於字符串算法庫，可以清晰表明字符數組的處理類似於數組而非字符串。

注意以上函數總是要以限定方式(boost::)來調用，以防止無意的ADL。

擴展本庫

方法 1: 提供成員函數和嵌套類型

這個方法假定你可以控制要改編以符合區間概念的類型。如果不是這樣，請看 方法 2。

本庫的主模板的實現是要使得標準容器可以自動工作，也包括 boost::array. 以下給出一個概覽，一個類要可以作為區間概念使用，必須指定哪些成員函數和成員類型。

成員函數 相關概念
begin() 單遍區間
end() 單遍區間

注意，rbegin() 和 rend() 成員函數不是必須的，即使該容器支持雙向迭代。

要求的成員類型有：

成員類型 相關概念
iterator 單遍區間
const_iterator 單遍區間

再次提醒，成員類型 reverse_iterator 和 const_reverse_iterator 是不需要的。

方法 2: 提供獨立函數和特化的元函數

這一方法假定你不能(或不願)修改要改編以符合區間概念的類型。如果不是這樣，請看 方法 1。

本庫的主模板實現是要使得特定的函數可以被ADL查找得到。以下給出一個概覽，一個類要可以作為區間概念使用，必須指定哪些獨立函數。其中 x 是該類的一個變量(const 或 mutable)。

函數 相關概念
range_begin(x) 單遍區間
range_end(x) 單遍區間

boost_range_begin() 和 boost_range_end() 必須同時為常量和非常量引用參數進行重載。

你還必須為你的類型 X 特化2個元函數：

元函數 相關概念
boost::range_mutable_iterator 單遍區間
boost::range_const_iterator 單遍區間

這裡給出一個完整的例子：  

#include <boost/range.hpp>
#include <iterator>         // for std::iterator_traits, std::distance()

namespace Foo
{
    //
    // 我們的 UDT 例子。一個 'Pair' 保存了
    // 一對迭代器，可用為一個區間來使用。
    //
    template< class T >
    struct Pair
    {
        T first, last;  
    };

} // namespace 'Foo'

namespace boost
{
    //
    // 特化元函數。我們必須包含 range.hpp 頭文件。
    // 我們必須打開 'boost' 名字空間。
    //

    template< class T >
    struct range_mutable_iterator< Foo::Pair<T> >
    {
        typedef T type;
    };

    template< class T >
    struct range_const_iterator< Foo::Pair<T> >
    {
        //
        // 註：這個定義與 'range_mutable_iterator' 相同，因為 'Pair' 類型
        //    無法區分 iterator 和 const_iterator.
        //
        typedef T type;
    };

} // namespace 'boost'

namespace Foo
{
    //
    // 要求的函數。應定義於 'Pair' 所在的名字空間，
    // 在本例中即名字空間 'Foo'.
    //
    
    template< class T >
    inline T range_begin( Pair<T>& x )
    { 
        return x.first;
    }

    template< class T >
    inline T range_begin( const Pair<T>& x )
    { 
        return x.first;
    }

    template< class T >
    inline T range_end( Pair<T>& x )
    { 
        return x.last;
    }

    template< class T >
    inline T range_end( const Pair<T>& x )
    { 
        return x.last;
    }

} // namespace 'Foo'

#include <vector>

int main()
{
    typedef std::vector<int>::iterator  iter;
    std::vector<int>                    vec;
    Foo::Pair<iter>                     pair  = { vec.begin(), vec.end() };
    const Foo::Pair<iter>&              cpair = pair; 
    //
    // 注意，我們以帶限定符的方式調用 'begin' 等函數。
    //
    iter i = boost::begin( pair );
    iter e = boost::end( pair );
    i      = boost::begin( cpair );
    e      = boost::end( cpair );
    boost::range_difference< Foo::Pair<iter> >::type s = boost::size( pair );
    s      = boost::size( cpair );
    boost::range_reverse_iterator< const Foo::Pair<iter> >::type
    ri     = boost::rbegin( cpair ),
    re     = boost::rend( cpair );
}

c Copyright Thorsten Ottosen 2008.

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)