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 ) 如果 sChar*
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> 其中 UChar* 如果 x 是一個字符串指針,否則 Urange_iterator<X>::type  [s,s + std::char_traits<X>::length(s)) 如果 sChar*
否則返回 [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_iteratorconst_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)