<iterator> funktioner

advance

Ökar en iterator med ett angivet antal positioner.

template <class InputIterator, class Distance>
void advance(InputIterator& InIt, Distance Off);

Parameters

InIt
Iteratorn som ska ökas och som måste uppfylla kraven för en indata-iterator.

Off
En integrerad typ som kan konverteras till iteratorns skillnadstyp och som anger antalet steg som iteratorns position ska avanceras.

Remarks

Intervallet måste vara icke-singulärt, där iteratorerna måste vara avrefererbara eller förbi slutet.

Om uppfyller InputIterator kraven för en dubbelriktad iteratortyp kan det Off vara negativt. Om InputIterator är en indata- eller vidarebefordrare-iteratortyp Off måste den vara icke-aktiv.

Funktionen advance har konstant komplexitet när InputIterator den uppfyller kraven för en iterator med slumpmässig åtkomst. Annars har den linjär komplexitet och är därför potentiellt dyr.

Exempel

// iterator_advance.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>

int main()
{
    using namespace std;

    list<int> L;
    for (int i = 1; i < 9; ++i)
    {
        L.push_back(i);
    }
    list<int>::iterator LPOS = L.begin();

    cout << "The list L is: ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;

    cout << "The iterator LPOS initially points to the first element: "
        << *LPOS << "." << endl;

    advance(LPOS, 4);
    cout << "LPOS is advanced 4 steps forward to point"
        << " to the fifth element: "
        << *LPOS << "." << endl;

    advance(LPOS, -3);
    cout << "LPOS is moved 3 steps back to point to the "
        << "2nd element: " << *LPOS << "." << endl;
}

The list L is: ( 1 2 3 4 5 6 7 8 ).
The iterator LPOS initially points to the first element: 1.
LPOS is advanced 4 steps forward to point to the fifth element: 5.
LPOS is moved 3 steps back to point to the 2nd element: 2.

back_inserter

Skapar en iterator som kan infoga element på baksidan av en angiven container.

template <class Container>
back_insert_iterator<Container> back_inserter(Container& Cont);

Parameters

Cont
Containern som den bakre infogningen ska köras i.

Returvärde

En back_insert_iterator associerad med containerobjektet Cont.

Remarks

I C++-standardbiblioteket måste argumentet referera till en av de tre sekvenscontainrar som har medlemsfunktionen push_back: deque Klass, list Klass eller vector Klass.

Exempel

// iterator_back_inserter.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>

int main()
{
    using namespace std;

    vector<int> vec;
    for (int i = 0; i < 3; ++i)
    {
        vec.push_back(i);
    }

    cout << "The initial vector vec is: ( ";
    for (auto vIter = vec.begin(); vIter != vec.end(); vIter++)
    {
        cout << *vIter << " ";
    }
    cout << ")." << endl;

    // Insertions can be done with template function
    back_insert_iterator<vector<int> > backiter(vec);
    *backiter = 30;
    backiter++;
    *backiter = 40;

    // Alternatively, insertions can be done with the
    // back_insert_iterator member function
    back_inserter(vec) = 500;
    back_inserter(vec) = 600;

    cout << "After the insertions, the vector vec is: ( ";
    for (auto vIter = vec.begin(); vIter != vec.end(); vIter++)
    {
        cout << *vIter << " ";
    }
    cout << ")." << endl;
}

The initial vector vec is: ( 0 1 2 ).
After the insertions, the vector vec is: ( 0 1 2 30 40 500 600 ).

begin

Hämtar en iterator till det första elementet i en angiven container.

template <class Container>
auto begin(Container& cont)
   -> decltype(cont.begin());

template <class Container>
auto begin(const Container& cont)
   -> decltype(cont.begin());

template <class Ty, class Size>
Ty *begin(Ty (& array)[Size]);

Parameters

cont
En container.

array
En matris med objekt av typen Ty.

Returvärde

De två första mallfunktionerna returnerar cont.begin(). Den första funktionen är icke-konstant; den andra är konstant.

Den tredje mallfunktionen returnerar array.

Exempel

Vi rekommenderar att du använder den här mallfunktionen i stället för containermedlem begin() när mer allmänt beteende krävs.

// cl.exe /EHsc /nologo /W4 /MTd
#include <algorithm>
#include <functional>
#include <iostream>
#include <iterator>
#include <vector>

template <typename C> void reverse_sort(C& c)
{
    std::sort(std::begin(c), std::end(c), std::greater<>());
}

template <typename C> void print(const C& c)
{
    for (const auto& e : c)
    {
        std::cout << e << " ";
    }
    std::cout << "\n";
}

int main() 
{
    std::vector<int> v = { 11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1 };

    print(v);
    reverse_sort(v);
    print(v);

    std::cout << "--\n";

    int arr[] = { 23, 70, 35, 106, 53, 160, 80, 40, 20, 10, 5, 16, 8, 4, 2, 1 };

    print(arr);
    reverse_sort(arr);
    print(arr);
}

11 34 17 52 26 13 40 20 10 5 16 8 4 2 1
52 40 34 26 20 17 16 13 11 10 8 5 4 2 1
--
23 70 35 106 53 160 80 40 20 10 5 16 8 4 2 1
160 106 80 70 53 40 35 23 20 16 10 8 5 4 2 1

Funktionen reverse_sort stöder containrar av något slag, förutom vanliga matriser, eftersom den anropar icke-medlemsversionen av begin(). Kodning reverse_sort för att använda containermedlemmen begin():

template <typename C>
void reverse_sort(C& c) {
    using std::begin;
    using std::end;

    std::sort(c.begin(), c.end(), std::greater<>());

}

Om du sedan skickar en matris till den orsakar det här kompilatorfelet:

error C2228: left of '.begin' must have class/struct/union

cbegin

Hämtar en const-iterator (skrivskyddad) till det första elementet i en angiven container.

template <class Container>
auto cbegin(const Container& cont)
   -> decltype(cont.begin());

Parameters

cont
En container eller initializer_list.

Returvärde

En konstant cont.begin().

Remarks

Den här funktionen fungerar med alla C++ Standard Library-containrar och med initializer_list.

Du kan använda den här medlemsfunktionen i stället begin() för mallfunktionen för att garantera att returvärdet är const_iterator. Vanligtvis används den med nyckelordet auto typavdrag, som du ser i följande exempel. I exemplet bör du överväga Container att vara en ändringsbar (icke- const) container eller initializer_list av något slag som stöder begin() och cbegin().

auto i1 = Container.begin();
// i1 is Container<T>::iterator
auto i2 = Container.cbegin();

// i2 is Container<T>::const_iterator

cend

Hämtar en const-iterator (skrivskyddad) till elementet som följer det sista elementet i den angivna containern.

template <class Container>
auto cend(const Container& cont)
   -> decltype(cont.end());

Parameters

cont
En container eller initializer_list.

Returvärde

En konstant cont.end().

Remarks

Den här funktionen fungerar med alla C++ Standard Library-containrar och med initializer_list.

Du kan använda den här medlemsfunktionen i stället end() för mallfunktionen för att garantera att returvärdet är const_iterator. Vanligtvis används den med nyckelordet auto typavdrag, som du ser i följande exempel. I exemplet bör du överväga Container att vara en ändringsbar (icke- const) container eller initializer_list av något slag som stöder end() och cend().

auto i1 = Container.end();
// i1 is Container<T>::iterator
auto i2 = Container.cend();

// i2 is Container<T>::const_iterator

crbegin

Hämta en omvänd skrivskyddad iterator till elementen i containern med början i slutet av containern.

template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c));

Parameters

C
Containertypen.

c
En containerinstans.

Returvärde

Den här iteratorn returnerar elementen i containern i omvänd ordning med början i slutet av containern.

Exempel: crbegin

#include <vector>
#include <iostream>

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

30 20 10

crend

Hämta sentinel i slutet av en skrivskyddad omvänd sekvens med element.

template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c));

Parameters

C
Containertypen.

c
En containerinstans.

Returvärde

Sentinel följer det sista elementet i en omvänd vy av containern.

crend exempel

#include <vector>
#include <iostream>

int main()
{
    std::vector<int> v{10, 20, 30};
    auto vi = std::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
}

10

data

Hämta en pekare till det första elementet i containern.

1) template <class C> constexpr auto data(C& c) -> decltype(c.data());
2) template <class C> constexpr auto data(const C& c) -> decltype(c.data());
3) template <class T, size_t N> constexpr T* data(T (&array)[N]) noexcept;
4) template <class E> constexpr const E* data(initializer_list<E> il) noexcept;

Parameters

C
Containertypen.

c
En instans av en container.

E
Elementtypen för initieringslistan.

il
En initialiserarlista.

N
Antalet element i matrisen.

T
Typen av data i matrisen.

Returvärde

1, 2) En pekare, baserat på containerns typ, till det första elementet. Om containern till exempel är en heltalsvektor är typen av returvärde en int *.

3) En pekare till det första elementet som en matris.

4) En pekare till det första elementet i initialiserarlistan.

Till exempel data

#include <vector>
#include <iostream>

int main()
{
    std::vector<int> v{ 10, 20, 30 };
    std::string src{ "a string" };

    const char *charPtr = std::data(src);
    int* intPtr = std::data(v);
    std::cout << charPtr << ", " << *intPtr << '\n'; // a string, 10
}

a string, 10

distance

Avgör antalet steg mellan de positioner som hanteras av två iteratorer.

template <class InputIterator>
typename iterator_traits<InputIterator>::difference_type distance(InputIterator first, InputIterator last);

Parameters

first
Den första iteratorn vars avstånd från den andra ska fastställas.

last
Den andra iteratorn vars avstånd från den första ska fastställas.

Returvärde

Antalet gånger som first måste ökas tills det är lika med last.

Remarks

Avståndsfunktionen har konstant komplexitet när InputIterator den uppfyller kraven för en iterator med slumpmässig åtkomst. Annars har den linjär komplexitet och är därför potentiellt dyr.

Exempel

// iterator_distance.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>

int main()
{
    using namespace std;

    list<int> L;
    for (int i = -1; i < 9; ++i)
    {
        L.push_back(2 * i);
    }
    list <int>::iterator L_Iter, LPOS = L.begin();

    cout << "The list L is: ( ";
    for (L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;

    cout << "The iterator LPOS initially points to the first element: "
         << *LPOS << "." << endl;

    advance(LPOS, 7);
    cout << "LPOS is advanced 7 steps forward to point "
        << " to the eighth element: "
        << *LPOS << "." << endl;

    list<int>::difference_type Ldiff;
    Ldiff = distance(L.begin(), LPOS);
    cout << "The distance from L.begin( ) to LPOS is: "
        << Ldiff << "." << endl;
}

The list L is: ( -2 0 2 4 6 8 10 12 14 16 ).
The iterator LPOS initially points to the first element: -2.
LPOS is advanced 7 steps forward to point  to the eighth element: 12.
The distance from L.begin( ) to LPOS is: 7.

empty

template <class C> constexpr auto empty(const C& c) -> decltype(c.empty());
template <class T, size_t N> constexpr bool empty(const T (&array)[N]) noexcept;
template <class E> constexpr bool empty(initializer_list<E> il) noexcept;

Parameters

C
Containertypen.

c
En instans av en container.

E
Elementtypen för initieringslistan.

il
En initialiserarlista.

N
Antalet element i matrisen.

T
Typen av data i matrisen.

Returvärde

Returnerar true om containern inte har några element, annars false.

Exempel

#include <vector>
#include <iostream>

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

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

false, true

end

Hämtar en iterator till elementet som följer det sista elementet i den angivna containern.

template <class Container>
auto end(Container& cont)
   -> decltype(cont.end());

template <class Container>
auto end(const Container& cont)
   -> decltype(cont.end());

template <class Ty, class Size>
Ty *end(Ty (& array)[Size]);

Parameters

cont
En container.

array
En matris med objekt av typen Ty.

Returvärde

De två första mallfunktionerna returnerar cont.end() (den första är icke-konstant och den andra är konstant).

Den tredje mallfunktionen returnerar array + Size.

Remarks

Ett kodexempel finns i begin.

front_inserter

Skapar en iterator som kan infoga element framför en angiven container.

template <class Container>
front_insert_iterator<Container> front_inserter(Container& Cont);

Parameters

Cont
Containerobjektet vars front har ett element infogat.

Returvärde

En front_insert_iterator associerad med containerobjektet Cont.

Remarks

Medlemsfunktionen front_insert_iterator i klassen front_insert_iterator kan också användas.

I C++-standardbiblioteket måste argumentet referera till en av de två sekvenscontainrar som har medlemsfunktionen push_back: deque Class eller "list Class".

Exempel

// iterator_front_inserter.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>

int main()
{
    using namespace std;

    list<int> L;
    for (int i = -1; i < 9; ++i)
    {
        L.push_back(i);
    }

    cout << "The list L is:\n ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;

    // Using the template function to insert an element
    front_insert_iterator<list <int>> Iter(L);
    *Iter = 100;

    // Alternatively, you may use the front_insert member function
    front_inserter(L) = 200;

    cout << "After the front insertions, the list L is:\n ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;
}

The list L is:
( -1 0 1 2 3 4 5 6 7 8 ).
After the front insertions, the list L is:
( 200 100 -1 0 1 2 3 4 5 6 7 8 ).

inserter

En hjälpmallsfunktion som gör att du kan använda inserter(Cont, Where) i stället för insert_iterator<Container>(Cont, Where).

template <class Container>
insert_iterator<Container>
inserter(
    Container& Cont,
    typename Container::iterator Where);

Parameters

Cont
Containern som nya element ska läggas till i.

Where
En iterator som lokaliserar insättningspunkten.

Remarks

Mallfunktionen returnerar insert_iterator<Container>(Cont, Where).

Exempel

// iterator_inserter.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>

int main()
{
    using namespace std;

    list<int> L;
    for (int i = 2; i < 5; ++i)
    {
        L.push_back(10 * i);
    }

    cout << "The list L is:\n ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;

    // Using the template version to insert an element
    insert_iterator<list<int>> Iter(L, L.begin());
    *Iter = 1;

    // Alternatively, using the member function to insert an element
    inserter(L, L.end()) = 500;

    cout << "After the insertions, the list L is:\n ( ";
    for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++)
    {
        cout << *L_Iter << " ";
    }
    cout << ")." << endl;
}

The list L is:
( 20 30 40 ).
After the insertions, the list L is:
( 1 20 30 40 500 ).

make_checked_array_iterator

Skapar en checked_array_iterator som kan användas av andra algoritmer.

template <class Iter>
checked_array_iterator<Iter>
    make_checked_array_iterator(
Iter Ptr,
    size_t Size,
    size_t Index = 0);

Parameters

Ptr
En pekare till målmatrisen.

Size
Storleken på målmatrisen.

Index
Valfritt index i matrisen.

Returvärde

En instans av checked_array_iterator.

Remarks

Funktionen make_checked_array_iterator definieras i stdext namnområdet.

Den här funktionen tar en rå pekare – vilket normalt skulle orsaka oro för gränsöverskridningar – och omsluter den i en checked_array_iterator-klass som kontrollerar. Eftersom den klassen är markerad som markerad varnar inte C++-standardbiblioteket om den. Mer information och kodexempel finns i Kontrollerade iteratorer.

Exempel

I följande exempel skapas och fylls en vektor med 10 objekt. Innehållet i vektorn kopieras till en matris med hjälp av kopieringsalgoritmen och används sedan make_checked_array_iterator för att ange målet. Detta följs av en avsiktlig överträdelse av gränskontrollen så att ett felsökningsfel utlöses.

// make_checked_array_iterator.cpp
// compile with: /EHsc /W4 /MTd

#include <algorithm>
#include <iterator> // stdext::make_checked_array_iterator
#include <memory> // std::make_unique
#include <iostream>
#include <vector>
#include <string>

using namespace std;

template <typename C> void print(const string& s, const C& c)
{
    cout << s;

    for (const auto& e : c) 
    {
        cout << e << " ";
    }

    cout << endl;
}

int main()
{
    const size_t dest_size = 10;
    // Old-school but not exception safe, favor make_unique<int[]>
    // int* dest = new int[dest_size];
    unique_ptr<int[]> updest = make_unique<int[]>(dest_size);
    int* dest = updest.get(); // get a raw pointer for the demo

    vector<int> v;

    for (int i = 0; i < dest_size; ++i) 
    {
        v.push_back(i);
    }
    print("vector v: ", v);

    copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size));

    cout << "int array dest: ";
    for (int i = 0; i < dest_size; ++i)
    {
        cout << dest[i] << " ";
    }
    cout << endl;

    // Add another element to the vector to force an overrun.
    v.push_back(10);

    // ! The next line causes a debug assertion when it executes.
    copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size));
}

make_move_iterator

Skapar en move iterator som innehåller den angivna iteratorn som stored iterator.

template <class Iterator>
move_iterator<Iterator>
make_move_iterator(const Iterator& It);

Parameters

It
Iteratorn som lagras i den nya flytta iteratorn.

Remarks

Mallfunktionen returnerar move_iterator<Iterator>(_It).

make_unchecked_array_iterator

Skapar en unchecked_array_iterator som kan användas av andra algoritmer.

template <class Iter>
unchecked_array_iterator<Iter>
    make_unchecked_array_iterator(Iter Ptr);

Parameters

Ptr
En pekare till målmatrisen.

Returvärde

En instans av unchecked_array_iterator.

Remarks

Funktionen make_unchecked_array_iterator definieras i stdext namnområdet.

Den här funktionen tar en råpekare och omsluter den i en klass som inte utför någon kontroll och därför optimerar bort till ingenting, men den tystar även kompilatorvarningar som C4996. Därför är detta ett målinriktat sätt att hantera omarkerade pekarvarningar utan att globalt tysta dem eller medföra kostnaden för kontroll. Mer information och kodexempel finns i Kontrollerade iteratorer.

Exempel

I följande exempel skapas och fylls en vektor med 10 objekt. Innehållet i vektorn kopieras till en matris med hjälp av kopieringsalgoritmen och används sedan make_unchecked_array_iterator för att ange målet.

// make_unchecked_array_iterator.cpp
// compile with: /EHsc /W4 /MTd

#include <algorithm>
#include <iterator> // stdext::make_unchecked_array_iterator
#include <iostream>
#include <vector>
#include <string>

using namespace std;

template <typename C> void print(const string& s, const C& c)
{
    cout << s;

    for (const auto& e : c) 
    {
        cout << e << " ";
    }

    cout << endl;
}

int main()
{
    const size_t dest_size = 10;
    int* dest = new int[dest_size];
    vector<int> v;

    for (int i = 0; i < dest_size; ++i) 
    {
        v.push_back(i);
    }
    print("vector v: ", v);

    // COMPILER WARNING SILENCED: stdext::unchecked_array_iterator is marked as checked in debug mode
    // (it performs no checking, so an overrun will trigger undefined behavior)
    copy(v.begin(), v.end(), stdext::make_unchecked_array_iterator(dest));

    cout << "int array dest: ";
    for (int i = 0; i < dest_size; ++i)
    {
        cout << dest[i] << " ";
    }
    cout << endl;

    delete[] dest;
}

vector v: 0 1 2 3 4 5 6 7 8 9
int array dest: 0 1 2 3 4 5 6 7 8 9

next

Itererar ett angivet antal gånger och returnerar den nya iteratorpositionen.

template <class InputIterator>
InputIterator next(
    InputIterator first,
    typename iterator_traits<InputIterator>::difference_type off = 1);

Parameters

first
Den aktuella positionen.

off
Antal gånger som iterera.

Returvärde

Returnerar den nya iteratorpositionen efter itereringstiderna off .

Remarks

Mallfunktionen returnerar next inkrementerade off tider

prev

Itererar i omvänd ordning ett angivet antal gånger och returnerar den nya iteratorpositionen.

template <class BidirectionalIterator>
BidirectionalIterator prev(
    BidirectionalIterator first,
    typename iterator_traits<BidirectionalIterator>::difference_type off = 1);

Parameters

first
Den aktuella positionen.

off
Antal gånger som iterera.

Remarks

Mallfunktionen returnerar next dementa off tider.

rbegin

Hämta en iterator som returnerar elementen i containern i omvänd ordning.

template <class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
template <class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());

Parameters

C
Containertypen.

c
En containerinstans.

Returvärde

Den returnerade iteratorn visar elementen i containern i omvänd ordning, med början i slutet av det omvända intervallet.

Till exempel rbegin

#include <vector>
#include <iostream>

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

	for (auto e = std::rbegin(v); e != std::rend(v); ++e)
	{
		std::cout << *e << ' '; // outputs 30 20 10
	}
}

30 20 10

rend

Hämta sentinel i slutet av en omvänd sekvens med element.

template <class C> constexpr auto rend(C& c)-> decltype(c.rend());
template <class C> constexpr auto rend(const C& c) -> decltype(c.rend());

Parameters

C
Containertypen.

c
En containerinstans.

Returvärde

En omvänd iterator till sentinel i slutet av containern. Sentinel följer det sista elementet i den omvända vyn av containern:

rend exempel

#include <vector>
#include <iostream>

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

10

size

template <class C> constexpr auto size(const C& c)
    -> decltype(c.size());
template <class T, size_t N> constexpr size_t size(const T (&array)[N]) noexcept;

Parameters

C
Containertypen.

c
En instans av en container.

N
Antalet element i matrisen.

T
Typen av data i matrisen.

Returvärde

Antalet element i containern som ett intesignerat heltalsliknande värde.

Till exempel size

#include <vector>
#include <iostream>

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

3