共用方式為

<ranges> 函式

  • 發行項

<ranges>C++20 標頭包含下列非成員協助程式函式。

非成員函式 說明
beginC++20 取得範圍中第一個專案的反覆運算器。
cbeginC++20 取得範圍中第一個專案 const 的反覆運算器。
cendC++20 取得限定範圍結尾的 constsentinel。
cdataC++20 取得連續範圍中第一個專案 const 的指標。
crbeginC++20 取得範圍開頭的反向 const 反覆運算器。
crendC++20 取得傳回內容 crbegin() 結尾的 sentinel。
dataC++20 取得連續範圍中第一個專案的指標。
emptyC++20 測試範圍是否為空白。
endC++20 取得範圍結尾的 sentinel。
rbeginC++20 取得範圍開頭的反向反覆運算器。
rendC++20 取得範圍結尾之 sentinel 的反向反覆運算器。
sizeC++20 取得範圍的大小做為不帶正負號的值。
ssizeC++20 取得範圍的大小做為帶正負號的值。

其中許多「函式」會實作為 自定義點物件。 自定義點對像是可在 使用者定義型別上多載的函式對象 ，同時強制執行可傳遞至函式物件之類型的條件約束。 net 效果是編譯程式會找出是否有有效的自定義函式要針對傳入的 型別呼叫，或是否應該使用默認實作，或呼叫的格式不正確。

其中許多函式在命名空間中 std 都有對應的函式。 但是，使用範圍時，請改用這些協助程式函式。 這些函式會使用 C++20 概念，以提供更佳的編譯時間錯誤。 因為它們會實作為自定義點，因此會避免與自變數相依查閱 （ADL） 和 const 正確性相關的問題。

begin

取得範圍中第一個專案的反覆運算器。

template<class T>
constexpr std::input_or_output_iterator auto begin(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

範圍中第一個專案的反覆運算器：

具有元素 10、20 和 30 的向量圖片。第一個元素包含 10，且標示為 'begin（）'。最後一個專案包含 30 個，且標示為「最後一個專案」。最後一個專案後面的虛方塊表示 sentinel 且標示為 end（）。

如果範圍是陣列，則傳回的 rg + 0對等 。 如果 auto(rg.begin()) 產生反覆運算器，則傳回的 auto(rg.begin())對等專案。 如果該表達式的格式不正確， auto(begin(rg)) 則當該表達式產生反覆運算器時會使用。

備註

ranges::begin() 適用於所有範圍，但 std::begin() 可能無法運作。

範例: begin

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector<int> v = {10, 20, 30};
    auto vi = std::ranges::begin(v);
    std::cout << *vi << ' ' << *++vi; // outputs 10 20
}

cbegin

取得範圍 const 中第一個專案的反覆運算器。 反覆運算器可以存取範圍中的專案，但無法加以修改。

template<class T>
constexpr std::input_or_output_iterator auto cbegin(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

範圍 const 中第一個專案的反覆運算器：

具有元素 10、20 和 30 的向量圖片。第一個元素包含 10，且標示為 'cbegin（）'。最後一個專案包含 30 個，且標示為「最後一個專案」。最後一個專案後面的虛方塊表示 sentinel，並標示為 cend（）。

如果範圍是陣列，則傳回的 rg + 0對等 。 如果 auto(rg.cbegin()) 產生反覆運算器，則傳回的 auto(rg.cbegin())對等專案。 如果該表達式的格式不正確， auto(cbegin(rg)) 則當該表達式產生反覆運算器時會使用。

備註

ranges::cbegin() 適用於所有範圍，但 std::cbegin() 可能無法運作。

範例: cbegin

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector<int> v = {10, 20, 30};
    auto vi = std::ranges::cbegin(v);
    std::cout << *vi; // outputs 10
    // *vi = 100; // error because the iterator is const
}

cdata

取得連續範圍中第一個專案 const 的指標。

template<class T>
constexpr std::add_pointer_t<ranges::range_reference_t<const T>> cdata(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

const以範圍類型為基礎的指標，指向連續範圍中的第一個項目數據。 例如，如果範圍是整數的向量，則傳回值的型別為 const int *。

範例: cdata

#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    std::string src{ "a string" };
   
    auto c_charPtr = std::ranges::cdata(src); // ptr is a const char *
    auto c_intPtr = std::ranges::cdata(v); // ptr2 is a const int *
    std::cout << c_charPtr << ", " << *c_intPtr << '\n'; // outputs a string, 10

    // *c_intPtr = 100; // error - cannot assign to a const pointer
    // *charPtr = 'A'; // error - cannot assign to a const pointer
}

cend

取得限定範圍結尾的 constsentinel。 反覆運算器可以存取範圍中的專案，但無法加以修改。

template<class T>
constexpr std::sentinel_for<decltype(ranges::cbegin(std::declval<T>()))> auto cend(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

在限定範圍中最後一個項目之後的 constsentinel：

具有元素 10、20 和 30 的向量圖片。第一個元素包含 10，且標示為 cbegin（）。最後一個專案包含 30 個，且標示為「最後一個專案」。最後一個專案後面的虛方塊表示 sentinel，並標示為 cend（）。

備註

ranges::cend() 適用於所有範圍，但 std::cend() 可能無法運作。

範例: cend

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector<int> v = {10, 20, 30};
    auto i = std::ranges::cend(v);
    --i; // get off the sentinel and onto the last element in the range
    std::cout << *i; // outputs 30
    // *i = 300 // error because the iterator is const
}

crbegin

取得反轉範圍中第一個專案的反向 const 反覆運算器。 反向反覆運算器會以反向順序傳回範圍的元素。 範圍本身不會反轉;存取它為 。

template<class T>
constexpr std::input_or_output_iterator auto crbegin(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

範圍中第一個專案的反向 const 反覆運算器。 此反覆運算器會以反向順序傳回範圍的元素，從範圍結尾開始：

包含元素 10、20 和 30 的向量圖片。最左邊的元素前面有一個虛方塊（最左邊的元素包含數位 10），代表 sentinel。它標示為 crend（）。向量中的第一個專案包含數位 10，並標示為「最後一個專案」。向量中最右邊的元素包含 30 個，並標示為 crbegin（）。

如果範圍是陣列，則傳回的對等 reverse_iterator{rg + n} 專案 n 是陣列中的項目數目。 如果 auto(rg.crbegin()) 產生反覆運算器，則傳回的 auto(rg.crbegin())對等專案。 如果該表達式的格式不正確， auto(crbegin(rg)) 則當該表達式產生反覆運算器時會使用。

備註

ranges::crbegin() 適用於所有雙向範圍，但 std::crbegin() 可能無法運作。

範例: crbegin

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto vi = std::ranges::crbegin(v);
    std::cout << *vi << ' ' << *++vi << ' ' << *++vi; // outputs 30 20 10
    // vi[1] = 100; // error because the iterator is const
}

crend

取得傳回內容 crbegin() 結尾的 sentinel。 反向反覆運算器會以反向順序傳回範圍的元素。 範圍本身不會反轉;存取它為 。

template<class T>
std::sentinel_for<decltype(ranges::crbegin(declval<T>()))> auto crend(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

傳回內容 cbegin() 結尾的 sentinel。 sentinel 會遵循範圍反轉檢視中的最後一個專案：

包含元素 10、20 和 30 的向量圖片。最左邊的元素前面有一個虛方塊（最左邊的元素包含數位 10），代表 sentinel。它標示為 crend（）。向量中的第一個專案包含數位 10，並標示為「最後一個專案」。向量中最右邊的元素包含 30 個，並標示為 crbegin（）。

備註

ranges::crend() 適用於所有雙向範圍，但 std::crend() 可能無法運作。

crend 例

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto vi = std::ranges::crend(v);
    --vi; // get off the sentinel and onto the last element in the reversed range
    std::cout << *vi; // outputs 10
    // vi[0] = 300; // error because the iterator is const    
    std::cout << *vi << ' ' << *--vi << ' ' << *--vi; // outputs 10, 20, 30
}

data

取得連續範圍中第一個專案的指標。

template<class T>
constexpr std::add_pointer_t<ranges::range_reference_t<T>> data(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

以範圍類型為基礎的指標，指向連續範圍中的第一個專案。 例如，如果範圍是整數的向量，則傳回值的型別為 int *。

範例

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    std::string src{ "a string" };
   
    auto charPtr = std::ranges::data(src); // charPtr is a char *
    auto intPtr = std::ranges::data(v); // intPtr is an int *
    std::cout << charPtr << ", " << *intPtr << '\n'; // outputs a string, 10
    *intPtr = 100;
    *charPtr = 'A';
    std::cout << charPtr << ", " << *intPtr; // outputs A string, 100
}

empty

測試範圍是否為空白。

template<class T>
constexpr bool empty(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

如果範圍沒有專案，則傳 true 回 ，否則 false傳回 。

範例

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
        std::vector v{10,20,30};
    std::vector<int> v2;

    std::cout << std::boolalpha << std::ranges::empty(v); // outputs false
    std::cout << std::boolalpha << ", " << std::ranges::empty(v2); // outputs true
}

end

取得範圍結尾的 sentinel。

template<class T>
std::sentinel_for<ranges::iterator_t<T>> auto end(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

在範圍中最後一個項目之後的 sentinel：

具有元素 10、20 和 30 的向量圖片。第一個元素包含 10，且標示為 begin（）。最後一個專案包含 30 個，且標示為「最後一個專案」。最後一個專案後面的虛方塊表示 sentinel 且標示為 end（）。

備註

ranges::end() 適用於所有範圍，但 std::end() 可能無法運作。

範例

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector<int> v = {10, 20, 30};
    auto i = std::ranges::end(v);
    --i; // get off the sentinel and onto the last element in the range
    std::cout << *i; // outputs 30
}

rbegin

取得反轉範圍中第一個專案的反向反覆運算器。 反向反覆運算器會以反向順序傳回範圍的元素。 範圍本身不會反轉;存取它為 。

template<class T>
constexpr std::input_or_output_iterator auto rbegin(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

範圍中第一個專案的反向反覆運算器。 此反覆運算器會以反向順序傳回範圍的元素，從反向範圍結尾開始：

包含元素 10、20 和 30 的向量圖片。最左邊的元素前面有一個虛方塊（最左邊的元素包含數位 10），代表 sentinel。它標示為 rend（）。向量中的第一個專案包含數位 10，並標示為「最後一個專案」。向量中最右邊的元素包含 30，且標示為 rbegin（）。

如果範圍是陣列，則傳回的對等 reverse_iterator{rg + n} 專案 n 是陣列中的項目數目。 如果 auto(rg.rbegin()) 產生反覆運算器，則傳回的 auto(rg.rbegin())對等專案。 如果該表達式的格式不正確， auto(rbegin(rg)) 則當該表達式產生反覆運算器時會使用。

備註

ranges::rbegin() 適用於所有雙向範圍，但 std::rbegin() 可能無法運作。

範例

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto vi = std::ranges::rbegin(v);
    std::cout << *vi << ' ' << *++vi << ' ' << *++vi; // outputs 30 20 10
}

rend

取得範圍反轉檢視結尾之 sentinel 的反向反覆運算器。 反向反覆運算器會以反向順序傳回範圍的元素。 範圍本身不會反轉;存取它為 。

template<class T>
constexpr 
std::sentinel_for<decltype(ranges::rbegin(std::declval<T>()))> auto rend(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

範圍結尾之 sentinel 的反向反覆運算器。 sentinel 會遵循範圍反轉檢視中的最後一個專案：

包含元素 10、20 和 30 的向量圖片。最左邊的元素前面有一個虛方塊（最左邊的元素包含數位 10），代表 sentinel。它標示為 rend（）。向量中的第一個專案包含數位 10，並標示為「最後一個專案」。向量中最右邊的元素包含 30，且標示為 rbegin（）。

備註

ranges::rend() 適用於所有雙向範圍，但 std::rend() 可能無法運作。

範例

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto vi = std::ranges::rend(v);
    --vi; // get off the sentinel and onto the last element in the reversed range
    std::cout << *vi; // outputs 10
    std::cout << *vi << ' ' << *--vi << ' ' << *--vi; // outputs 10, 20, 30
}

size

取得範圍中的項目數目做為不帶正負號的值。

template<class T>
constexpr /*unsigned integer-like type */ size(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

範圍中的項目數目，以不帶正負號的整數值表示。

備註

此函式會以常數時間執行。

範例

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto s = std::ranges::size(v); // s is a size_t
    std::cout << s; // outputs 3
}

ssize

取得範圍的大小做為帶正負號的值。

template<class T>
constexpr /* signed-integer-like type */ ssize(T&& rg);

參數

T
範圍的型別。

rg
範圍。

傳回值

範圍中的項目數目，以帶正負號的整數值表示。

備註

此函式會以常數時間執行。

範例

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto s = std::ranges::ssize(v);
    std::cout << s; // outputs 3
}

另請參閱

<ranges>
什麼是自定義物件