checked_array_iterator Class
The checked_array_iterator class allows you to transform an array or pointer into a checked iterator. Use this class as a wrapper (using the make_checked_array_iterator function) for raw pointers or arrays as a targeted way to provide checking and to manage unchecked pointer warnings instead of globally silencing these warnings. If necessary, you can use the unchecked version of this class, unchecked_array_iterator.
Note
This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension. For an example demonstrating how to write code that does not require the use of this class, see the second example below.
Syntax
template <class _Iterator>
class checked_array_iterator;
Remarks
This class is defined in the stdext namespace.
For more information and example code on the checked iterator feature, see Checked Iterators.
Examples
The following sample shows how to define and use a checked array iterator.
If the destination is not large enough to hold all the elements being copied, such as would be the case if you changed the line:
copy(a, a + 5, checked_array_iterator<int*>(b, 5));
to
copy(a, a + 5, checked_array_iterator<int*>(b, 4));
A runtime error will occur.
// compile with: /EHsc /W4 /MTd
#include <algorithm>
#include <iostream>
using namespace std;
using namespace stdext;
int main() {
int a[]={0, 1, 2, 3, 4};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b, 5));
cout << "(";
for (int i = 0 ; i < 5 ; i++)
cout << " " << b[i];
cout << " )" << endl;
// constructor example
checked_array_iterator<int*> checked_out_iter(b, 5);
copy(a, a + 5, checked_out_iter);
cout << "(";
for (int i = 0 ; i < 5 ; i++)
cout << " " << b[i];
cout << " )" << endl;
}
/* Output:
( 0 1 2 3 4 )
( 0 1 2 3 4 )
*/
To avoid the need for the checked_array_iterator class when using C++ Standard Library algorithms, consider using a vector instead of a dynamically allocated array. The following example demonstrates how to do this.
// compile with: /EHsc /W4 /MTd
#include <algorithm>
#include <iostream>
#include <vector>
using namespace std;
int main()
{
std::vector<int> v(10);
int *arr = new int[10];
for (int i = 0; i < 10; ++i)
{
v[i] = i;
arr[i] = i;
}
// std::copy(v.begin(), v.end(), arr); will result in
// warning C4996. To avoid this warning while using int *,
// use the Microsoft extension checked_array_iterator.
std::copy(v.begin(), v.end(),
stdext::checked_array_iterator<int *>(arr, 10));
// Instead of using stdext::checked_array_iterator and int *,
// consider using std::vector to encapsulate the array. This will
// result in no warnings, and the code will be portable.
std::vector<int> arr2(10); // Similar to int *arr = new int[10];
std::copy(v.begin(), v.end(), arr2.begin());
for (int j = 0; j < arr2.size(); ++j)
{
cout << " " << arr2[j];
}
cout << endl;
return 0;
}
/* Output:
0 1 2 3 4 5 6 7 8 9
*/
Constructors
| Constructor | Description |
|---|---|
| checked_array_iterator | Constructs a default checked_array_iterator or a checked_array_iterator from an underlying iterator. |
Typedefs
| Type name | Description |
|---|---|
| difference_type | A type that provides the difference between two checked_array_iterators referring to elements within the same container. |
| pointer | A type that provides a pointer to an element addressed by a checked_array_iterator. |
| reference | A type that provides a reference to an element addressed by a checked_array_iterator. |
Member functions
| Member function | Description |
|---|---|
| base | Recovers the underlying iterator from its checked_array_iterator. |
Operators
| Operator | Description |
|---|---|
| operator== | Tests two checked_array_iterators for equality. |
| operator!= | Tests two checked_array_iterators for inequality. |
| operator< | Tests if the checked_array_iterator on the left side of the operator is less than the checked_array_iterator on the right side. |
| operator> | Tests if the checked_array_iterator on the left side of the operator is greater than the checked_array_iterator on the right side. |
| operator<= | Tests if the checked_array_iterator on the left side of the operator is less than or equal to the checked_array_iterator on the right side. |
| operator>= | Tests if the checked_array_iterator on the left side of the operator is greater than or equal to the checked_array_iterator on the right side. |
| operator* | Returns the element that a checked_array_iterator addresses. |
| operator-> | Returns a pointer to the element addressed by the checked_array_iterator. |
| operator++ | Increments the checked_array_iterator to the next element. |
| operator-- | Decrements the checked_array_iterator to the previous element. |
| operator+= | Adds a specified offset to a checked_array_iterator. |
| operator+ | Adds an offset to an iterator and returns the new checked_array_iterator addressing the inserted element at the new offset position. |
| operator-= | Decrements a specified offset from a checked_array_iterator. |
| operator- | Decrements an offset from an iterator and returns the new checked_array_iterator addressing the inserted element at the new offset position. |
operator[] |
Returns a reference to an element offset from the element addressed by a checked_array_iterator by a specified number of positions. |
Requirements
Header: <iterator>
Namespace: stdext
checked_array_iterator::base
Recovers the underlying iterator from its checked_array_iterator.
_Iterator base() const;
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_base.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main() {
using namespace std;
int V1[10];
for (int i = 0; i < 10 ; i++)
V1[i] = i;
int* bpos;
stdext::checked_array_iterator<int*> rpos(V1, 10);
rpos++;
bpos = rpos.base ( );
cout << "The iterator underlying rpos is bpos & it points to: "
<< *bpos << "." << endl;
}
/* Output:
The iterator underlying rpos is bpos & it points to: 1.
*/
checked_array_iterator::checked_array_iterator
Constructs a default checked_array_iterator or a checked_array _iterator from an underlying iterator.
checked_array_iterator();
checked_array_iterator(
ITerator ptr,
size_t size,
size_t index = 0);
Parameters
ptr
A pointer to the array.
size
The size of the array.
index
(Optional) An element in the array, to initialize the iterator. By default, the iterator is initialized to the first element in the array.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_ctor.cpp
// compile with: /EHsc
#include <iterator>
#include <iostream>
using namespace std;
using namespace stdext;
int main() {
int a[] = {0, 1, 2, 3, 4};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
for (int i = 0 ; i < 5 ; i++)
cout << b[i] << " ";
cout << endl;
checked_array_iterator<int*> checked_output_iterator(b,5);
copy (a, a + 5, checked_output_iterator);
for (int i = 0 ; i < 5 ; i++)
cout << b[i] << " ";
cout << endl;
checked_array_iterator<int*> checked_output_iterator2(b,5,3);
cout << *checked_output_iterator2 << endl;
}
/* Output:
0 1 2 3 4
0 1 2 3 4
3
*/
checked_array_iterator::difference_type
A type that provides the difference between two checked_array_iterators referring to elements within the same container.
typedef typename iterator_traits<_Iterator>::difference_type difference_type;
Remarks
The checked_array_iterator difference type is the same as the iterator difference type.
See checked_array_iterator::operator[] for a code sample.
For more information, see Checked Iterators.
checked_array_iterator::operator==
Tests two checked_array_iterators for equality.
bool operator==(const checked_array_iterator<_Iterator>& right) const;
Parameters
right
The checked_array_iterator against which to check for equality.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_opeq.cpp
// compile with: /EHsc
#include <iterator>
#include <iostream>
using namespace std;
using namespace stdext;
int main() {
int a[] = {0, 1, 2, 3, 4};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
copy(a, a + 5, checked_array_iterator<int*>(b,5));
checked_array_iterator<int*> checked_output_iterator(b,5);
checked_array_iterator<int*> checked_output_iterator2(b,5);
if (checked_output_iterator2 == checked_output_iterator)
cout << "checked_array_iterators are equal" << endl;
else
cout << "checked_array_iterators are not equal" << endl;
copy (a, a + 5, checked_output_iterator);
checked_output_iterator++;
if (checked_output_iterator2 == checked_output_iterator)
cout << "checked_array_iterators are equal" << endl;
else
cout << "checked_array_iterators are not equal" << endl;
}
/* Output:
checked_array_iterators are equal
checked_array_iterators are not equal
*/
checked_array_iterator::operator!=
Tests two checked_array_iterators for inequality.
bool operator!=(const checked_array_iterator<_Iterator>& right) const;
Parameters
right
The checked_array_iterator against which to check for inequality.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_opneq.cpp
// compile with: /EHsc
#include <iterator>
#include <iostream>
using namespace std;
using namespace stdext;
int main() {
int a[] = {0, 1, 2, 3, 4};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
copy(a, a + 5, checked_array_iterator<int*>(b,5));
checked_array_iterator<int*> checked_output_iterator(b,5);
checked_array_iterator<int*> checked_output_iterator2(b,5);
if (checked_output_iterator2 != checked_output_iterator)
cout << "checked_array_iterators are not equal" << endl;
else
cout << "checked_array_iterators are equal" << endl;
copy (a, a + 5, checked_output_iterator);
checked_output_iterator++;
if (checked_output_iterator2 != checked_output_iterator)
cout << "checked_array_iterators are not equal" << endl;
else
cout << "checked_array_iterators are equal" << endl;
}
/* Output:
checked_array_iterators are equal
checked_array_iterators are not equal
*/
checked_array_iterator::operator<
Tests if the checked_array_iterator on the left side of the operator is less than the checked_array_iterator on the right side.
bool operator<(const checked_array_iterator<_Iterator>& right) const;
Parameters
right
The checked_array_iterator against which to check for inequality.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_oplt.cpp
// compile with: /EHsc
#include <iterator>
#include <iostream>
using namespace std;
using namespace stdext;
int main() {
int a[] = {0, 1, 2, 3, 4};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
copy(a, a + 5, checked_array_iterator<int*>(b,5));
checked_array_iterator<int*> checked_output_iterator(b,5);
checked_array_iterator<int*> checked_output_iterator2(b,5);
if (checked_output_iterator2 < checked_output_iterator)
cout << "checked_output_iterator2 is less than checked_output_iterator" << endl;
else
cout << "checked_output_iterator2 is not less than checked_output_iterator" << endl;
copy (a, a + 5, checked_output_iterator);
checked_output_iterator++;
if (checked_output_iterator2 < checked_output_iterator)
cout << "checked_output_iterator2 is less than checked_output_iterator" << endl;
else
cout << "checked_output_iterator2 is not less than checked_output_iterator" << endl;
}
/* Output:
checked_output_iterator2 is not less than checked_output_iterator
checked_output_iterator2 is less than checked_output_iterator
*/
checked_array_iterator::operator>
Tests if the checked_array_iterator on the left side of the operator is greater than the checked_array_iterator on the right side.
bool operator>(const checked_array_iterator<_Iterator>& right) const;
Parameters
right
The checked_array_iterator to compare against.
Remarks
See checked_array_iterator::operator< for a code sample.
For more information, see Checked Iterators.
checked_array_iterator::operator<=
Tests if the checked_array_iterator on the left side of the operator is less than or equal to the checked_array_iterator on the right side.
bool operator<=(const checked_array_iterator<_Iterator>& right) const;
Parameters
right
The checked_array_iterator to compare against.
Remarks
See checked_array_iterator::operator>= for a code sample.
For more information, see Checked Iterators.
checked_array_iterator::operator>=
Tests if the checked_array_iterator on the left side of the operator is greater than or equal to the checked_array_iterator on the right side.
bool operator>=(const checked_array_iterator<_Iterator>& right) const;
Parameters
right
The checked_array_iterator to compare against.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_opgteq.cpp
// compile with: /EHsc
#include <iterator>
#include <iostream>
using namespace std;
using namespace stdext;
int main() {
int a[] = {0, 1, 2, 3, 4};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
copy(a, a + 5, checked_array_iterator<int*>(b,5));
checked_array_iterator<int*> checked_output_iterator(b,5);
checked_array_iterator<int*> checked_output_iterator2(b,5);
if (checked_output_iterator2 >= checked_output_iterator)
cout << "checked_output_iterator2 is greater than or equal to checked_output_iterator" << endl;
else
cout << "checked_output_iterator2 is less than checked_output_iterator" << endl;
copy (a, a + 5, checked_output_iterator);
checked_output_iterator++;
if (checked_output_iterator2 >= checked_output_iterator)
cout << "checked_output_iterator2 is greater than or equal to checked_output_iterator" << endl;
else
cout << "checked_output_iterator2 is less than checked_output_iterator" << endl;
}
/* Output:
checked_output_iterator2 is greater than or equal to checked_output_iterator
checked_output_iterator2 is less than checked_output_iterator
*/
checked_array_iterator::operator*
Returns the element that a checked_array_iterator addresses.
reference operator*() const;
Return Value
The value of the element addressed by the checked_array_iterator.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterator_pointer.cpp
// compile with: /EHsc
#include <iterator>
#include <algorithm>
#include <vector>
#include <utility>
#include <iostream>
using namespace std;
using namespace stdext;
int main() {
int a[] = {0, 1, 2, 3, 4};
int b[5];
pair<int, int> c[1];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
for (int i = 0 ; i < 5 ; i++)
cout << b[i] << endl;
c[0].first = 10;
c[0].second = 20;
checked_array_iterator<int*> checked_output_iterator(b,5);
checked_array_iterator<int*>::pointer p = &(*checked_output_iterator);
checked_array_iterator<pair<int, int>*> chk_c(c, 1);
checked_array_iterator<pair<int, int>*>::pointer p_c = &(*chk_c);
cout << "b[0] = " << *p << endl;
cout << "c[0].first = " << p_c->first << endl;
}
/* Output:
0
1
2
3
4
b[0] = 0
c[0].first = 10
*/
checked_array_iterator::operator->
Returns a pointer to the element addressed by the checked_array_iterator.
pointer operator->() const;
Return Value
A pointer to the element addressed by the checked_array_iterator.
Remarks
See checked_array_iterator::pointer for a code sample.
For more information, see Checked Iterators.
checked_array_iterator::operator++
Increments the checked_array_iterator to the next element.
checked_array_iterator& operator++();
checked_array_iterator<_Iterator> operator++(int);
Return Value
The first operator returns the preincremented checked_array_iterator and the second, the postincrement operator, returns a copy of the incremented checked_array_iterator.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_op_plus_plus.cpp
// compile with: /EHsc
#include <vector>
#include <iostream>
int main() {
using namespace stdext;
using namespace std;
int a[] = {6, 3, 77, 199, 222};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
checked_array_iterator<int*> checked_output_iterator(b,5);
cout << *checked_output_iterator << endl;
++checked_output_iterator;
cout << *checked_output_iterator << endl;
checked_output_iterator++;
cout << *checked_output_iterator << endl;
}
/* Output:
6
3
77
*/
checked_array_iterator::operator--
Decrements the checked_array_iterator to the previous element.
checked_array_iterator<_Iterator>& operator--();
checked_array_iterator<_Iterator> operator--(int);
Return Value
The first operator returns the predecremented checked_array_iterator and the second, the postdecrement operator, returns a copy of the decremented checked_array_iterator.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_op_minus_minus.cpp
// compile with: /EHsc
#include <vector>
#include <iostream>
int main() {
using namespace stdext;
using namespace std;
int a[] = {6, 3, 77, 199, 222};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
checked_array_iterator<int*> checked_output_iterator(b,5);
cout << *checked_output_iterator << endl;
checked_output_iterator++;
cout << *checked_output_iterator << endl;
checked_output_iterator--;
cout << *checked_output_iterator << endl;
}
/* Output:
6
3
6
*/
checked_array_iterator::operator+=
Adds a specified offset to a checked_array_iterator.
checked_array_iterator<_Iterator>& operator+=(difference_type _Off);
Parameters
_Off
The offset by which to increment the iterator.
Return Value
A reference to the element addressed by the checked_array_iterator.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_op_plus_eq.cpp
// compile with: /EHsc
#include <vector>
#include <iostream>
int main() {
using namespace stdext;
using namespace std;
int a[] = {6, 3, 77, 199, 222};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
checked_array_iterator<int*> checked_output_iterator(b,5);
cout << *checked_output_iterator << endl;
checked_output_iterator += 3;
cout << *checked_output_iterator << endl;
}
/* Output:
6
199
*/
checked_array_iterator::operator+
Adds an offset to an iterator and returns the new checked_array_iterator addressing the inserted element at the new offset position.
checked_array_iterator<_Iterator> operator+(difference_type _Off) const;
Parameters
_Off
The offset to be added to the checked_array_iterator.
Return Value
A checked_array_iterator addressing the offset element.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_op_plus.cpp
// compile with: /EHsc
#include <vector>
#include <iostream>
int main() {
using namespace stdext;
using namespace std;
int a[] = {6, 3, 77, 199, 222};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
checked_array_iterator<int*> checked_output_iterator(b,5);
cout << *checked_output_iterator << endl;
checked_output_iterator = checked_output_iterator + 3;
cout << *checked_output_iterator << endl;
}
/* Output:
6
199
*/
checked_array_iterator::operator-=
Decrements a specified offset from a checked_array_iterator.
checked_array_iterator<_Iterator>& operator-=(difference_type _Off);
Parameters
_Off
The offset by which to increment the iterator.
Return Value
A reference to the element addressed by the checked_array_iterator.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_op_minus_eq.cpp
// compile with: /EHsc
#include <vector>
#include <iostream>
int main() {
using namespace stdext;
using namespace std;
int a[] = {6, 3, 77, 199, 222};
int b[5];
copy(a, a + 5, checked_array_iterator<int*>(b,5));
checked_array_iterator<int*> checked_output_iterator(b,5);
checked_output_iterator += 3;
cout << *checked_output_iterator << endl;
checked_output_iterator -= 2;
cout << *checked_output_iterator << endl;
}
/* Output:
199
3
*/
checked_array_iterator::operator-
Decrements an offset from an iterator and returns the new checked_array_iterator addressing the inserted element at the new offset position.
checked_array_iterator<_Iterator> operator-(difference_type _Off) const;
difference_type operator-(const checked_array_iterator& right) const;
Parameters
_Off
The offset to be decremented from the checked_array_iterator.
Return Value
A checked_array_iterator addressing the offset element.
Remarks
For more information, see Checked Iterators.
checked_array_iterator::operator[]
Returns a reference to an element offset from the element addressed by a checked_array_iterator by a specified number of positions.
reference operator[](difference_type _Off) const;
Parameters
_Off
The offset from the checked_array_iterator address.
Return Value
The reference to the element offset.
Remarks
For more information, see Checked Iterators.
Example
// checked_array_iterators_op_diff.cpp
// compile with: /EHsc
#include <vector>
#include <iostream>
int main() {
using namespace std;
int V1[10];
for (int i = 0; i < 10 ; i++)
V1[i] = i;
// Declare a difference type for a parameter
stdext::checked_array_iterator<int*>::difference_type diff = 2;
stdext::checked_array_iterator<int*> VChkIter(V1, 10);
stdext::checked_array_iterator<int*>::reference refrpos = VChkIter [diff];
cout << refrpos + 1 << endl;
}
/* Output:
3
*/
checked_array_iterator::pointer
A type that provides a pointer to an element addressed by a checked_array_iterator.
typedef typename iterator_traits<_Iterator>::pointer pointer;
Remarks
See checked_array_iterator::operator* for a code sample.
For more information, see Checked Iterators.
checked_array_iterator::reference
A type that provides a reference to an element addressed by a checked_array_iterator.
typedef typename iterator_traits<_Iterator>::reference reference;
Remarks
See checked_array_iterator::operator[] for a code sample.
For more information, see Checked Iterators.