<iterator> operators
The latest version of this topic can be found at <iterator> operators.
| operator!= | operator> | operator>= |
| operator< | operator<= | operator+ |
| operator- | operator== |
operator!=
Tests if the iterator object on the left side of the operator is not equal to the iterator object on the right side.
template <class RandomIterator>
bool operator!=(const reverse_iterator<RandomIterator>& left, const reverse_iterator<RandomIterator>& right);
template <class Type, class CharType, class Traits, class Distance>
bool operator!=(const istream_iterator<Type, CharType, Traits, Distance>& left, const istream_iterator<Type, CharType, Traits, Distance>& right);
template <class CharType, class Tr>
bool operator!=(const istreambuf_iterator<CharType, Traits>& left, const istreambuf_iterator<CharType, Traits>& right);
Parameters
left
An object of type iterator.
right
An object of type iterator.
Return Value
true if the iterator objects are not equal; false if the iterator objects are equal.
Remarks
One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they are not equal.
Example
// iterator_op_ne.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
int i;
vector<int> vec;
for ( i = 1 ; i < 9 ; ++i )
{
vec.push_back ( i );
}
vector <int>::iterator vIter;
cout << "The vector vec is: ( ";
for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++ )
cout << *vIter << " ";
cout << ")." << endl;
// Initializing reverse_iterators to the last element
vector <int>::reverse_iterator rVPOS1 = vec.rbegin ( ),
rVPOS2 = vec.rbegin ( );
cout << "The iterator rVPOS1 initially points to the first "
<< "element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
if ( rVPOS1 != rVPOS2 )
cout << "The iterators are not equal." << endl;
else
cout << "The iterators are equal." << endl;
rVPOS1++;
cout << "The iterator rVPOS1 now points to the second "
<< "element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
if ( rVPOS1 != rVPOS2 )
cout << "The iterators are not equal." << endl;
else
cout << "The iterators are equal." << endl;
}
The vector vec is: ( 1 2 3 4 5 6 7 8 ).
The iterator rVPOS1 initially points to the first element
in the reversed sequence: 8.
The iterators are equal.
The iterator rVPOS1 now points to the second element
in the reversed sequence: 7.
The iterators are not equal.
operator==
Tests if the iterator object on the left side of the operator is equal to the iterator object on the right side.
template <class RandomIterator1, class RandomIterator2>
bool operator==(
const move_iterator<RandomIterator1>& left,
const move_iterator<RandomIterator2>& right);
template <class RandomIterator1, class RandomIterator2>
bool operator==(
const reverse_iterator<RandomIterator1>& left,
const reverse_iterator<RandomIterator2>& right);
template <class Type, class CharType, class Traits, class Distance>
bool operator==(
const istream_iterator<Type, CharType, Traits, Distance>& left,
const istream_iterator<Type, CharType, Traits, Distance>& right);
template <class CharType, class Tr>
bool operator==(
const istreambuf_iterator<CharType, Traits>& left,
const istreambuf_iterator<CharType, Traits>& right);
Parameters
left
An object of type iterator.
right
An object of type iterator.
Return Value
true if the iterator objects are equal; false if the iterator objects are not equal.
Remarks
One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they are not equal.
The first two template operators return true only if both left and right store the same iterator. The third template operator returns true only if both left and right store the same stream pointer. The fourth template operator returns left.equal ( right).
Example
// iterator_op_eq.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
int i;
vector<int> vec;
for ( i = 1 ; i < 6 ; ++i )
{
vec.push_back ( 2 * i );
}
vector <int>::iterator vIter;
cout << "The vector vec is: ( ";
for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++)
cout << *vIter << " ";
cout << ")." << endl;
// Initializing reverse_iterators to the last element
vector <int>::reverse_iterator rVPOS1 = vec.rbegin ( ),
rVPOS2 = vec.rbegin ( );
cout << "The iterator rVPOS1 initially points to the first "
<< "element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
if ( rVPOS1 == rVPOS2 )
cout << "The iterators are equal." << endl;
else
cout << "The iterators are not equal." << endl;
rVPOS1++;
cout << "The iterator rVPOS1 now points to the second "
<< "element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
if ( rVPOS1 == rVPOS2 )
cout << "The iterators are equal." << endl;
else
cout << "The iterators are not equal." << endl;
}
The vector vec is: ( 2 4 6 8 10 ).
The iterator rVPOS1 initially points to the first element
in the reversed sequence: 10.
The iterators are equal.
The iterator rVPOS1 now points to the second element
in the reversed sequence: 8.
The iterators are not equal.
operator<
Tests if the iterator object on the left side of the operator is less than the iterator object on the right side.
template <class RandomIterator>
bool operator<(const reverse_iterator<RandomIterator>& left, const reverse_iterator<RandomIterator>& right);
Parameters
left
An object of type iterator.
right
An object of type iterator.
Return Value
true if the iterator on the left side of the expression is less than the iterator on the right side of the expression; false if it is greater than or equal to the iterator on the right.
Remarks
One iterator object is less than another if it addresses an element that occurs earlier in the container than the element addressed by the other iterator object. One iterator object is not less than another if it addresses either the same element as the other iterator object or an element that occurs later in the container than the element addressed by the other iterator object.
Example
// iterator_op_lt.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
int i;
vector<int> vec;
for ( i = 0 ; i < 6 ; ++i )
{
vec.push_back ( 2 * i );
}
vector <int>::iterator vIter;
cout << "The initial vector vec is: ( ";
for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++)
cout << *vIter << " ";
cout << ")." << endl;
// Initializing reverse_iterators to the last element
vector <int>::reverse_iterator rVPOS1 = vec.rbegin ( ),
rVPOS2 = vec.rbegin ( );
cout << "The iterators rVPOS1& rVPOS2 initially point to the "
<< "first element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
if ( rVPOS1 < rVPOS2 )
cout << "The iterator rVPOS1 is less than"
<< " the iterator rVPOS2." << endl;
else
cout << "The iterator rVPOS1 is not less than"
<< " the iterator rVPOS2." << endl;
rVPOS2++;
cout << "The iterator rVPOS2 now points to the second "
<< "element\n in the reversed sequence: "
<< *rVPOS2 << "." << endl;
if ( rVPOS1 < rVPOS2 )
cout << "The iterator rVPOS1 is less than"
<< " the iterator rVPOS2." << endl;
else
cout << "The iterator rVPOS1 is not less than"
<< " the iterator rVPOS2." << endl;
}
The initial vector vec is: ( 0 2 4 6 8 10 ).
The iterators rVPOS1& rVPOS2 initially point to the first element
in the reversed sequence: 10.
The iterator rVPOS1 is not less than the iterator rVPOS2.
The iterator rVPOS2 now points to the second element
in the reversed sequence: 8.
The iterator rVPOS1 is less than the iterator rVPOS2.
operator<=
Tests if the iterator object on the left side of the operator is less than or equal to the iterator object on the right side.
template <class RandomIterator>
bool operator<=(const reverse_iterator<RandomIterator>& left, const reverse_iterator<RandomIterator>& right);
Parameters
left
An object of type iterator.
right
An object of type iterator.
Return Value
true if the iterator on the left side of the expression is less than or equal to the iterator on the right side of the expression; false if it is greater than the iterator on the right.
Remarks
One iterator object is less than or equal to another if it addresses the same element or an element that occurs earlier in the container than the element addressed by the other iterator object. One iterator object is greater than another if it addresses an element that occurs later in the container than the element addressed by the other iterator object.
Example
// iterator_op_le.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
int i;
vector<int> vec;
for (i = 0 ; i < 6 ; ++i ) {
vec.push_back ( 2 * i );
}
vector <int>::iterator vIter;
cout << "The initial vector vec is: ( ";
for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++)
cout << *vIter << " ";
cout << ")." << endl;
vector <int>::reverse_iterator rVPOS1 = vec.rbegin ( ) + 1,
rVPOS2 = vec.rbegin ( );
cout << "The iterator rVPOS1 initially points to the "
<< "second element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
cout << "The iterator rVPOS2 initially points to the "
<< "first element\n in the reversed sequence: "
<< *rVPOS2 << "." << endl;
if ( rVPOS1 <= rVPOS2 )
cout << "The iterator rVPOS1 is less than or "
<< "equal to the iterator rVPOS2." << endl;
else
cout << "The iterator rVPOS1 is greater than "
<< "the iterator rVPOS2." << endl;
rVPOS2++;
cout << "The iterator rVPOS2 now points to the second "
<< "element\n in the reversed sequence: "
<< *rVPOS2 << "." << endl;
if ( rVPOS1 <= rVPOS2 )
cout << "The iterator rVPOS1 is less than or "
<< "equal to the iterator rVPOS2." << endl;
else
cout << "The iterator rVPOS1 is greater than "
<< "the iterator rVPOS2." << endl;
}
The initial vector vec is: ( 0 2 4 6 8 10 ).
The iterator rVPOS1 initially points to the second element
in the reversed sequence: 8.
The iterator rVPOS2 initially points to the first element
in the reversed sequence: 10.
The iterator rVPOS1 is greater than the iterator rVPOS2.
The iterator rVPOS2 now points to the second element
in the reversed sequence: 8.
The iterator rVPOS1 is less than or equal to the iterator rVPOS2.
operator>
Tests if the iterator object on the left side of the operator is greater than the iterator object on the right side.
template <class RandomIterator>
bool operator>(const reverse_iterator<RandomIterator>& left, const reverse_iterator<RandomIterator>& right);
Parameters
left
An object of type iterator.
right
An object of type iterator.
Return Value
true if the iterator on the left side of the expression is greater than the iterator on the right side of the expression; false if it is less than or equal to the iterator on the right.
Remarks
One iterator object is greater than another if it addresses an element that occurs later in the container than the element addressed by the other iterator object. One iterator object is not greater than another if it addresses either the same element as the other iterator object or an element that occurs earlier in the container than the element addressed by the other iterator object.
Example
// iterator_op_gt.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
int i;
vector<int> vec;
for (i = 0 ; i < 6 ; ++i ) {
vec.push_back ( 2 * i );
}
vector <int>::iterator vIter;
cout << "The initial vector vec is: ( ";
for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++)
cout << *vIter << " ";
cout << ")." << endl;
vector <int>::reverse_iterator rVPOS1 = vec.rbegin ( ),
rVPOS2 = vec.rbegin ( );
cout << "The iterators rVPOS1 & rVPOS2 initially point to "
<< "the first element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
if ( rVPOS1 > rVPOS2 )
cout << "The iterator rVPOS1 is greater than "
<< "the iterator rVPOS2." << endl;
else
cout << "The iterator rVPOS1 is less than or "
<< "equal to the iterator rVPOS2." << endl;
rVPOS1++;
cout << "The iterator rVPOS1 now points to the second "
<< "element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
if ( rVPOS1 > rVPOS2 )
cout << "The iterator rVPOS1 is greater than "
<< "the iterator rVPOS2." << endl;
else
cout << "The iterator rVPOS1 is less than or "
<< "equal to the iterator rVPOS2." << endl;
}
The initial vector vec is: ( 0 2 4 6 8 10 ).
The iterators rVPOS1 & rVPOS2 initially point to the first element
in the reversed sequence: 10.
The iterator rVPOS1 is less than or equal to the iterator rVPOS2.
The iterator rVPOS1 now points to the second element
in the reversed sequence: 8.
The iterator rVPOS1 is greater than the iterator rVPOS2.
operator>=
Tests if the iterator object on the left side of the operator is greater than or equal to the iterator object on the right side.
template <class RandomIterator>
bool operator>=(const reverse_iterator<RandomIterator>& left, const reverse_iterator<RandomIterator>& right);
Parameters
left
An object of type iterator.
right
An object of type iterator.
Return Value
true if the iterator on the left side of the expression is greater than or equal to the iterator on the right side of the expression; false if it is less than the iterator on the right.
Remarks
One iterator object is greater than or equal to another if it addresses the same element or an element that occurs later in the container than the element addressed by the other iterator object. One iterator object is less than another if it addresses an element that occurs earlier in the container than the element addressed by the other iterator object.
Example
// iterator_op_ge.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
int i;
vector<int> vec;
for (i = 0 ; i < 6 ; ++i ) {
vec.push_back ( 2 * i );
}
vector <int>::iterator vIter;
cout << "The initial vector vec is: ( ";
for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++)
cout << *vIter << " ";
cout << ")." << endl;
vector <int>::reverse_iterator rVPOS1 = vec.rbegin ( ),
rVPOS2 = vec.rbegin ( ) + 1;
cout << "The iterator rVPOS1 initially points to the "
<< "first element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
cout << "The iterator rVPOS2 initially points to the "
<< "second element\n in the reversed sequence: "
<< *rVPOS2 << "." << endl;
if ( rVPOS1 >= rVPOS2 )
cout << "The iterator rVPOS1 is greater than or "
<< "equal to the iterator rVPOS2." << endl;
else
cout << "The iterator rVPOS1 is less than "
<< "the iterator rVPOS2." << endl;
rVPOS1++;
cout << "The iterator rVPOS1 now points to the second "
<< "element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
if ( rVPOS1 >= rVPOS2 )
cout << "The iterator rVPOS1 is greater than or "
<< "equal to the iterator rVPOS2." << endl;
else
cout << "The iterator rVPOS1 is less than "
<< "the iterator rVPOS2." << endl;
}
The initial vector vec is: ( 0 2 4 6 8 10 ).
The iterator rVPOS1 initially points to the first element
in the reversed sequence: 10.
The iterator rVPOS2 initially points to the second element
in the reversed sequence: 8.
The iterator rVPOS1 is less than the iterator rVPOS2.
The iterator rVPOS1 now points to the second element
in the reversed sequence: 8.
The iterator rVPOS1 is greater than or equal to the iterator rVPOS2.
operator+
Adds an offset to an iterator and returns a move_iterator or a reverse_iterator addressing the inserted element at the new offset position.
template <class RandomIterator, class Diff>
move_iterator<RandomIterator>
operator+(
Diff _Off,
const move_iterator<RandomIterator>& right);
template <class RandomIterator>
reverse_iterator<RandomIterator>
operator+(
Diff _Off,
const reverse_iterator<RandomIterator>& right);
Parameters
_Off
The number of positions the const move_iterator or const reverse_iterator is to be offset.
right
The iterator to be offset.
Return Value
Returns the sum right + _Off.
Example
// iterator_op_insert.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
int i;
vector<int> vec;
for (i = 0 ; i < 6 ; ++i ) {
vec.push_back ( 2 * i );
}
vector <int>::iterator vIter;
cout << "The initial vector vec is: ( ";
for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++)
cout << *vIter << " ";
cout << ")." << endl;
vector <int>::reverse_iterator rVPOS1 = vec.rbegin ( );
cout << "The iterator rVPOS1 initially points to "
<< "the first element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
vector<int>::difference_type diff = 4;
rVPOS1 = diff +rVPOS1;
cout << "The iterator rVPOS1 now points to the fifth "
<< "element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
}
The initial vector vec is: ( 0 2 4 6 8 10 ).
The iterator rVPOS1 initially points to the first element
in the reversed sequence: 10.
The iterator rVPOS1 now points to the fifth element
in the reversed sequence: 2.
operator-
Subtracts one iterator from another and returns the difference.
template <class RandomIterator1, class RandomIterator2>
Tdiff operator-(
const move_iterator<RandomIterator1>& left,
const move_iterator<RandomIterator2>& right);
template <class RandomIterator1, class RandomIterator2>
Tdiff operator-(
const reverse_iterator<RandomIterator1>& left,
const reverse_iterator<RandomIterator2>& right);
Parameters
left
An iterator.
right
An iterator.
Return Value
The difference between two iterators .
Remarks
The first template operator returns left.base() - right.base().
The second template operator returns right.current - left.current.
Tdiff is determined by the type of the returned expression. Otherwise, it is RandomIterator1::difference_type.
Example
// iterator_op_sub.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
int i;
vector<int> vec;
for (i = 0 ; i < 6 ; ++i )
{
vec.push_back ( 2 * i );
}
vector <int>::iterator vIter;
cout << "The initial vector vec is: ( ";
for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++)
cout << *vIter << " ";
cout << ")." << endl;
vector <int>::reverse_iterator rVPOS1 = vec.rbegin ( ),
rVPOS2 = vec.rbegin ( );
cout << "The iterators rVPOS1 & rVPOS2 initially point to "
<< "the first element\n in the reversed sequence: "
<< *rVPOS1 << "." << endl;
for (i = 1; i < 5; ++i)
{
rVPOS2++;
}
cout << "The iterator rVPOS2 now points to the fifth "
<< "element\n in the reversed sequence: "
<< *rVPOS2 << "." << endl;
vector<int>::difference_type diff = rVPOS2 - rVPOS1;
cout << "The difference: rVPOS2 - rVPOS1= "
<< diff << "." << endl;
}
The initial vector vec is: ( 0 2 4 6 8 10 ).
The iterators rVPOS1 & rVPOS2 initially point to the first element
in the reversed sequence: 10.
The iterator rVPOS2 now points to the fifth element
in the reversed sequence: 2.
The difference: rVPOS2 - rVPOS1= 4.