Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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.

System_CAPS_ICON_note.jpg Note

This class is a Microsoft extension of the Standard C++ 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.

template <class _Iterator>  
class checked_array_iterator;

This class is defined in the stdext namespace.

For more information and example code on the checked iterator feature, see Checked Iterators.

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 Standard C++ 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

checked_array_iteratorConstructs a default checked_array_iterator or a checked_array_iterator from an underlying iterator.

Typedefs

difference_typeA type that provides the difference between two checked_array_iterators referring to elements within the same container.
pointerA type that provides a pointer to an element addressed by a checked_array_iterator.
referenceA type that provides a reference to an element addressed by a checked_array_iterator.

Member Functions

baseRecovers the underlying iterator from its checked_array_iterator.

Operators

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.

Header: <iterator>

Namespace: stdext

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.  
*\  

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  
*\  

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.

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  
*\  

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  
*\  

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  
*\  

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.

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.

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  
*\  

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  
*\  

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.

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  
*\  

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  
*\  

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  
*\  

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  
*\  

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  
*\  

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

See checked_array_iterator::operator- for a code sample.

For more information, see Checked Iterators.

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  
*\  

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.

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.

<iterator>
Standard Template Library

Show:
© 2016 Microsoft