コレクション (C++/CX)Collections (C++/CX)

C +/cli/CX プログラムの場合は、標準テンプレート ライブラリ (STL) コンテナー、または他のユーザー定義コレクション型を自由に使用を行うことができます。In a C++/CX program, you can make free use of Standard Template Library (STL) containers, or any other user-defined collection type. ただし、コレクションを渡す場合、双方向 Windows ランタイム アプリケーション バイナリ インターフェイス (ABI) を越えて — たとえば、XAML コントロールまたは JavaScript クライアント: Windows ランタイムのコレクション型を使用する必要があります。However, when you pass collections back and forth across the Windows Runtime application binary interface (ABI)—for example, to a XAML control or to a JavaScript client—you must use Windows Runtime collection types.

Windows ランタイムは、コレクションと関連する型、および C + 用のインターフェイスを定義します。/cli CX は collection.h ヘッダー ファイルで具象 C++ 実装を提供します。The Windows Runtime defines the interfaces for collections and related types, and C++/CX provides the concrete C++ implementations in the collection.h header file. この図は、コレクション型間のリレーションシップを示しています。This illustration shows the relationships between the collection types:

C++//CX 継承ツリーのコレクション型C++/CX inheritance tree for collection types

ベクターの使用Vector usage

クラス、シーケンス コンテナーを別の Windows ランタイム コンポーネントに渡すときに使用:foundation:: IVector<T >パラメーターまたは戻り値の型として、プラットフォーム。Collections::Vector<T >具象実装として。When your class has to pass a sequence container to another Windows Runtime component, use Windows::Foundation::Collections:: IVector<T> as the parameter or return type, and Platform::Collections::Vector<T> as the concrete implementation. パブリックの戻り値またはパラメーターで Vector 型を使用しようとすると、コンパイラ エラー C3986 が発生します。If you attempt to use a Vector type in a public return value or parameter, compiler error C3986 will be raised. このエラーは、 VectorIVectorに変更することで解決できます。You can fix the error by changing the Vector to an IVector.

重要

独自のプログラム内のシーケンスを渡している場合は、 Vectorstd::vector のどちらかを使用します。それらの方が IVectorより効率的であるためです。If you are passing a sequence within your own program, then use either Vector or std::vector because they are more efficient than IVector. ABI を介してコンテナーを渡す場合にのみ、 IVector を使用します。Use IVector only when you pass the container across the ABI.

Windows ランタイムの型システムは、ジャグ配列の概念をサポートしていませんし、そのため、IVector を渡すことはできません < platform::array<T >> を戻り値またはメソッド パラメーターとして。The Windows Runtime type system does not support the concept of jagged arrays and therefore you cannot pass an IVector<Platform::Array<T>> as a return value or method parameter. ABI を通じてジャグ配列またはシーケンスのシーケンスを渡すには、 IVector<IVector<T>^>を使用します。To pass a jagged array or a sequence of sequences across the ABI, use IVector<IVector<T>^>.

Vector<T> は、コレクションでの項目の追加、削除、およびアクセスに必要なメソッドを提供します。暗黙的に IVector<T>に変換可能です。Vector<T> provides the methods that are required for adding, removing, and accessing items in the collection, and it is implicitly convertible to IVector<T>. Vector<T>のインスタンスで STL アルゴリズム使用することもできます。You can also use STL algorithms on instances of Vector<T>. 次の例は、基本的な使用法をいくつか示しています。The following example demonstrates some basic usage. begin 関数end 関数Platform::Collections 名前空間のもので、 std 名前空間のものではありません。The begin function and end function here are from the Platform::Collections namespace, not the std namespace.

#include <collection.h>
#include <algorithm>
using namespace Platform;
using namespace Platform::Collections;
using namespace Windows::Foundation::Collections;


void Class1::Test()
{
    Vector<int>^ vec = ref new Vector<int>();
    vec->Append(1);
    vec->Append(2);
    vec->Append(3);
    vec->Append(4);
    vec->Append(5);


    auto it = 
        std::find(begin(vec), end(vec), 3);

    int j = *it; //j = 3
    int k = *(it + 1); //or it[1]

    // Find a specified value.
    unsigned int n;         
    bool found = vec->IndexOf(4, &n); //n = 3

    // Get the value at the specified index.
    n = vec->GetAt(4); // n = 3

    // Insert an item.
    // vec = 0, 1, 2, 3, 4, 5
    vec->InsertAt(0, 0);

    // Modify an item.
    // vec = 0, 1, 2, 12, 4, 5,
    vec->SetAt(3, 12);

    // Remove an item.
    //vec = 1, 2, 12, 4, 5 
    vec->RemoveAt(0);

    // vec = 1, 2, 12, 4
    vec->RemoveAtEnd();

    // Get a read-only view into the vector.
    IVectorView<int>^ view = vec->GetView();
}

使用する既存のコードがある場合std::vectorWindows ランタイム コンポーネントで再利用のいずれかを使用して、Vectorを受け取るコンス トラクター、std::vectorまたは構築する反復子のペアをVector時点を渡すことで、ABI を介してコレクションです。If you have existing code that uses std::vector and you want to reuse it in a Windows Runtime component, just use one of the Vector constructors that takes a std::vector or a pair of iterators to construct a Vector at the point where you pass the collection across the ABI. 次の例は、 Vector からの効率的な初期化のために std::vector移動コンストラクターを使用する方法を示しています。The following example shows how to use the Vector move constructor for efficient initialization from a std::vector. 移動操作の後、元の vec 変数は有効でなくなります。After the move operation, the original vec variable is no longer valid.

//#include <collection.h>
//#include <vector>
//#include <utility> //for std::move
//using namespace Platform::Collections;
//using namespace Windows::Foundation::Collections;
//using namespace std;
IVector<int>^ Class1::GetInts()
{
    vector<int> vec;
    for(int i = 0; i < 10; i++)
    {
        vec.push_back(i);
    }    
    // Implicit conversion to IVector
    return ref new Vector<int>(std::move(vec));
}

今後のいつか、ABI を介して渡す必要がある文字列ベクターがある場合、その文字列を最初に std::wstring 型として作成するのかそれとも Platform::String^ 型として作成するのかを決定する必要があります。If you have a vector of strings that you must pass across the ABI at some future point, you must decide whether to create the strings initially as std::wstring types or as Platform::String^ types. その文字列に対して多くの処理を実行する必要がある場合、 wstringを使用します。If you have to do a lot of processing on the strings, then use wstring. それ以外の場合は、文字列を Platform::String^ 型として作成して、後で変換するコストを回避してください。Otherwise, create the strings as Platform::String^ types and avoid the cost of converting them later. また、これらの文字列を std:vectorPlatform::Collections::Vector のどちらに内部的に埋め込むのかも決定する必要があります。You must also decide whether to put these strings into a std:vector or Platform::Collections::Vector internally. 一般に、 std::vector を使用し、ABI を介してコンテナーを渡す場合にのみ、そこから Platform::Vector を作成します。As a general practice, use std::vector and then create a Platform::Vector from it only when you pass the container across the ABI.

ベクターにおける値の型Value types in Vector

Platform::Collections::Vector に格納される要素は、暗黙的にまたは指定したカスタム std::equal_to 比較子を使用するかして、等値比較をサポートする必要があります。Any element to be stored in a Platform::Collections::Vector must support equality comparison, either implicitly or by using a custom std::equal_to comparator that you provide. すべての参照型とすべてのスカラー型は、暗黙的に等値比較をサポートしています。All reference types and all scalar types implicitly support equality comparisons. Windows::Foundation::DateTimeなどの非スカラー値型の場合や、カスタム比較 ( objA->UniqueID == objB->UniqueIDなど) の場合、カスタム関数オブジェクトを提供する必要があります。For non-scalar value types such as Windows::Foundation::DateTime, or for custom comparisons—for example, objA->UniqueID == objB->UniqueID—you must provide a custom function object.

VectorProxy 要素VectorProxy elements

Platform::Collections::VectorIteratorPlatform::Collections::VectorViewIteratorの使用を有効にするrange forループとなどのアルゴリズムstd::sortIVector<T >コンテナー。Platform::Collections::VectorIterator and Platform::Collections::VectorViewIterator enable the use of range for loops and algorithms like std::sort with an IVector<T> container. ただし、C++ ポインターの逆参照を使って IVector 要素にアクセスすることはできません。これらの要素には、 GetAt メソッドと SetAt メソッドを使ってアクセスすることしかできません。But IVector elements cannot be accessed through C++ pointer dereference; they can be accessed only through GetAt and SetAt methods. そのため、これらの反復子を使用して、プロキシ クラスPlatform::Details::VectorProxy<T>Platform::Details::ArrowProxy<T>を介して個々 の要素へのアクセスを提供する__*->、および[]__ 演算子は、標準ライブラリで必要とします。Therefore, these iterators use the proxy classes Platform::Details::VectorProxy<T> and Platform::Details::ArrowProxy<T> to provide access to the individual elements through *, ->, and [] operators, as required by the Standard Library. 厳密には、 IVector<Person^> vecが指定されている場合、 *begin(vec) の型は VectorProxy<Person^>になります。Strictly speaking, given an IVector<Person^> vec, the type of *begin(vec) is VectorProxy<Person^>. ただし、プロキシ オブジェクトは、ほとんどの場合、コードに対して透過的です。However, the proxy object is almost always transparent to your code. これらのプロキシ オブジェクトは反復子によって内部でのみ使用されるため文書化されませんが、その機構の動作がわかっていると便利です。These proxy objects are not documented because they are only for internal use by the iterators, but it is useful to know how the mechanism works.

range for コンテナーに対して IVector ループを使用する場合は、 auto&& を使用して反復子変数が VectorProxy 要素に正しくバインドされるようにします。When you use a range for loop over IVector containers, use auto&& to enable the iterator variable to bind correctly to the VectorProxy elements. auto または auto&を使用すると、コンパイラ警告 C4239 が発生し、警告テキストに VectoryProxy が示されます。If you use auto or auto&, compiler warning C4239 is raised and VectoryProxy is mentioned in the warning text.

range for に対する IVector<Person^>ループ処理の例を次に示します。The following illustration shows a range for loop over an IVector<Person^>. 実行が 64 行のブレークポイントで停止していることに注意してください。Notice that execution is stopped on the breakpoint on line 64. [クイック ウォッチ] ウィンドウには、反復子変数 p が実際には VectorProxy<Person^> メンバー変数と m_v メンバー変数を持つ m_i であることが示されています。The QuickWatch window shows that the iterator variable p is in fact a VectorProxy<Person^> that has m_v and m_i member variables. ただし、この変数で GetType を呼び出すと、 Person インスタンス p2と同一の型が返されます。However, when you call GetType on this variable, it returns the identical type to the Person instance p2. VectorProxyArrowProxy[クイック ウォッチ]、デバッガーの一部のコンパイラ エラー、またはその他の場所に表示される場合でも、通常はそれらについて明示的にコーディングする必要はありません。The takeaway is that although VectorProxy and ArrowProxy might appear in QuickWatch, the debugger certain compiler errors, or other places, you typically don't have to explicitly code for them.

範囲内にある VectorProxy-基づく for ループVectorProxy in range-based for loop

プロキシ オブジェクトに関してコーディングする必要があるのは、 dynamic_cast 要素コレクションで特定の型の XAML オブジェクトを探している場合など、要素で UIElement を実行する必要がある場合です。One scenario in which you have to code around the proxy object is when you have to perform a dynamic_cast on the elements—for example, when you are looking for XAML objects of a particular type in a UIElement element collection. この場合は、最初に Platform::Object^ に要素をキャストし、その後に動的キャストを実行する必要があります。In this case, you must first cast the element to Platform::Object^ and then perform the dynamic cast:

void FindButton(UIElementCollection^ col)
{
    // Use auto&& to avoid warning C4239
    for (auto&& elem : col)
    {
        Button^ temp = dynamic_cast<Button^>(static_cast<Object^>(elem));
        if (nullptr != temp)
        {
            // Use temp...
        }
    }
}

マップの使用Map usage

この例は、項目の挿入し、で確認する方法を示します、 :map、戻って、Map読み取り専用 [Windows::Foundation::Collections::IMapView] として/uwp api/Windows.Foundation.Collections.IMapView_K_V_) の型。This example shows how to insert items and look them up in a Platform::Collections::Map, and then return the Map as a read-only [Windows::Foundation::Collections::IMapView]/uwp/api/Windows.Foundation.Collections.IMapView_K_V_) type.

//#include <collection.h>
//using namespace Platform::Collections;
//using namespace Windows::Foundation::Collections;
IMapView<String^, int>^ Class1::MapTest()
{
    Map<String^, int>^ m = ref new Map<String^, int >();
    m->Insert("Mike", 0);
    m->Insert("Dave", 1);
    m->Insert("Doug", 2);
    m->Insert("Nikki", 3);
    m->Insert("Kayley", 4);
    m->Insert("Alex", 5);
    m->Insert("Spencer", 6);

   // PC::Map does not support [] operator
   int i = m->Lookup("Doug");
   
   return m->GetView();
   
}

一般に、内部マップ機能については、パフォーマンス上の理由で std::map 型を優先します。In general, for internal map functionality, prefer the std::map type for performance reasons. ABI を介してコンテナーを渡す必要がある場合は、 std::map から Platform::Collections::Map を構築し、 MapWindows::Foundation::Collections::IMapとして返します。If you have to pass the container across the ABI, construct a Platform::Collections::Map from the std::map and return the Map as an Windows::Foundation::Collections::IMap. パブリックの戻り値またはパラメーターで Map 型を使用しようとすると、コンパイラ エラー C3986 が発生します。If you attempt to use a Map type in a public return value or parameter, compiler error C3986 will be raised. このエラーは、 MapIMapに変更することで解決できます。You can fix the error by changing the Map to an IMap. たとえば、実行するルックアップや挿入の数が多くなく、ABI を介して頻繁にコレクションを渡すなどの場合、最初から Platform::Collections::Map を使用し std::mapを変換するコストを回避した方がコストを抑えられることがあります。In some cases—for example, if you are not making a large number of lookups or insertions, and you are passing the collection across the ABI frequently—it might be less expensive to use Platform::Collections::Map from the beginning and avoid the cost of converting the std::map. どちらの場合も、 IMap のルックアップ操作と挿入操作は、3 つの種類で最もパフォーマンスが低いので避けます。In any case, avoid lookup and insert operations on an IMap because these are the least performant of the three types. ABI を介してコンテナーを渡すポイントでのみ、 IMap に変換します。Convert to IMap only at the point that you pass the container across the ABI.

マップにおける値の型Value types in Map

Platform::Collections::Map 内の要素は、順序付きです。Elements in a Platform::Collections::Map are ordered. Map に格納しようとする要素は、厳密な弱い順序付けに基づき、"より小さい" 比較をサポートする必要があります。このために、暗黙的な比較、または開発者が指定したカスタム比較子 stl::less が使用されます。Any element to be stored in a Map must support less-than comparison with strict weak ordering, either implicitly or by using a custom stl::less comparator that you provide. スカラー型では、この比較を暗黙的にサポートしています。Scalar types support the comparison implicitly. Windows::Foundation::DateTimeなどの非スカラー値型、またはカスタム比較 ( objA->UniqueID < objB->UniqueIDなど) の場合、カスタム比較子を提供する必要があります。For non-scalar value types such as Windows::Foundation::DateTime, or for custom comparisons—for example, objA->UniqueID < objB->UniqueID—you must provide a custom comparator.

コレクション型Collection types

コレクションは、シーケンス コレクションと関連コレクションそれぞれの変更可能バージョンと読み取り専用バージョンという 4 つのカテゴリに分類されます。Collections fall into four categories: modifiable versions and read-only versions of sequence collections and associative collections. さらに、C +/cli CX はコレクションのアクセスを簡略化する 3 つの反復子クラスを提供することでコレクションを拡張します。In addition, C++/CX enhances collections by providing three iterator classes that simplify the accessing of collections.

変更可能なコレクションの要素は変更できますが、 ビューと呼ばれる読み取り専用コレクションの要素は読み取りしか実行できません。Elements of a modifiable collection can be changed, but elements of a read-only collection, which is known as a view, can only be read. 要素をplatform::collections:またはPlatform::Collections::VectorView 、反復子またはコレクションを使用してコレクションにアクセスできるvector::getatとインデックス。Elements of a Platform::Collections::Vector orPlatform::Collections::VectorView collection can be accessed by using an iterator or the collection's Vector::GetAt and an index. 関連コレクションの要素のコレクションを使用してアクセスできるmap::lookupとキー。Elements of an associative collection can be accessed by using the collection's Map::Lookup and a key.

Platform::Collections::Map クラスPlatform::Collections::Map Class
変更可能な関連コレクション。A modifiable, associative collection. マップ要素は、キーと値のペアです。Map elements are key-value pairs. キーを検索してその関連付けられた値を取得することと、キーと値のペアをすべて繰り返すことの両方がサポートされています。Looking up a key to retrieve its associated value, and iterating through all key-value pairs, are both supported.

MapMapView は、 <K, V, C = std::less<K>>で template 宣言されるので、比較子をカスタマイズできます。Map and MapView are templated on <K, V, C = std::less<K>>; therefore, you can customize the comparator. さらに、 VectorVectorView<T, E = std::equal_to<T>> で template 宣言されるので、 IndexOf()の動作をカスタマイズできます。Additionally, Vector and VectorView are templated on <T, E = std::equal_to<T>> so that you can customize the behavior of IndexOf(). これは、値の構造体の VectorVectorView について特に重要です。This is important mostly for Vector and VectorView of value structs. たとえば、ベクターを作成する<::datetime > を DateTime オーバー ロードしていないため、カスタム比較子を提供する必要があります、演算子 = =。For example, to create a Vector<Windows::Foundation::DateTime>, you must provide a custom comparator because DateTime does not overload the == operator.

Platform::Collections::MapView クラスPlatform::Collections::MapView Class
Mapの読み取り専用バージョン。A read-only version of a Map.

Platform::Collections::Vector ClassPlatform::Collections::Vector Class
変更可能なシーケンス コレクション。A modifiable sequence collection. Vector<T> は、定数時間ランダム アクセス操作と償却定数時間の 追加 操作をサポートしています。Vector<T> supports constant-time random access and amortized-constant-time Append operations..

Platform::Collections::VectorView クラスPlatform::Collections::VectorView Class
Vectorの読み取り専用バージョン。A read-only version of a Vector.

Platform::Collections::InputIterator クラスPlatform::Collections::InputIterator Class
STL 入力反復子の要件を満たす STL の反復子。An STL iterator that satisfies the requirements of an STL input iterator.

Platform::Collections::VectorIterator クラスPlatform::Collections::VectorIterator Class
変更可能な STL ランダム アクセス反復子の要件を満たす STL 反復子。An STL iterator that satisfies the requirements of an STL mutable random-access iterator.

Platform::Collections::VectorViewIterator クラスPlatform::Collections::VectorViewIterator Class
STL の const ランダム アクセス反復子の要件を満たす STL 反復子。An STL iterator that satisfies the requirements of an STL const random-access iterator.

begin() および end() 関数begin() and end() functions

処理する STL の使用を簡略化VectorVectorViewMapMapView、および任意Windows::Foundation::Collectionsオブジェクト、C +/cli CX のオーバー ロードをサポートしている、 begin 関数終了関数非メンバー関数。To simplify the use of the STL to process Vector, VectorView, Map, MapView, and arbitrary Windows::Foundation::Collections objects, C++/CX supports overloads of the begin Function and end Function non-member functions.

次の表は、使用できる反復子と関数の一覧を示しています。The following table lists the available iterators and functions.

IteratorsIterators 関数Functions
Platform::Collections::VectorIterator<T >Platform::Collections::VectorIterator<T>

(内部に格納:foundation:: IVector<T >と int です)。(Internally stores Windows::Foundation::Collections:: IVector<T> and int.)
begin/ end(Windows::Foundation::Collections:: IVector<T>)begin/ end(Windows::Foundation::Collections:: IVector<T>)
Platform::Collections::VectorViewIterator<T >Platform::Collections::VectorViewIterator<T>

(内部に格納IVectorView<T >^ と int です)。(Internally stores IVectorView<T>^ and int.)
開始/ エンド(IVectorView<T >^)begin/ end (IVectorView<T>^)
Platform::Collections::InputIterator<T >Platform::Collections::InputIterator<T>

(内部に格納IIterator<T >^ および T)(Internally stores IIterator<T>^ and T.)
開始/ エンド(IIterable<T >)begin/ end (IIterable<T>)
Platform::Collections::InputIterator < IKeyValuePair<K, V > ^ >Platform::Collections::InputIterator<IKeyValuePair<K, V>^>

(内部に格納IIterator<T >^ および T)(Internally stores IIterator<T>^ and T.)
開始/ エンド(IMap<K, V >します。begin/ end (IMap<K,V>.
Platform::Collections::InputIterator < IKeyValuePair<K, V > ^ >Platform::Collections::InputIterator<IKeyValuePair<K, V>^>

(内部に格納IIterator<T >^ および T)(Internally stores IIterator<T>^ and T.)
開始/ エンド([Windows:: Foundation::Collections::IMapView]/uwp/api/Windows.Foundation.Collections.IMapView_K_V_))begin/ end ([Windows::Foundation::Collections::IMapView]/uwp/api/Windows.Foundation.Collections.IMapView_K_V_))

コレクション変更イベントCollection change events

VectorMap は、XAML コレクションでのデータ バインドをサポートしていますが、これは、コレクション オブジェクトが変更またはリセットされたとき、またはコレクションのいずれかの要素が挿入、削除、または変更されたときに発生するイベントを実装することで実現されています。Vector and Map support databinding in XAML collections by implementing events that occur when a collection object is changed or reset, or when any element of a collection is inserted, removed, or changed. データ バインドをサポートする独自の型を作成できます。ただし、 MapVector から継承することはできません。これらの型はシールされているためです。You can write your own types that support databinding, although you cannot inherit from Map or Vector because those types are sealed.

Windows::Foundation::Collections::VectorChangedEventHandler デリゲートと Windows::Foundation::Collections::MapChangedEventHandler デリゲートは、コレクション変更イベントのイベント ハンドラーのシグネチャを指定します。The Windows::Foundation::Collections::VectorChangedEventHandler and Windows::Foundation::Collections::MapChangedEventHandler delegates specify the signatures for event handlers for collection change events. Windows::Foundation::Collections::CollectionChange パブリック列挙型クラス、 Platform::Collection::Details::MapChangedEventArgsPlatform::Collections::Details::VectorChangedEventArgs ref クラスは、イベントの原因を特定するためにイベント引数を格納します。The Windows::Foundation::Collections::CollectionChange public enum class, and Platform::Collection::Details::MapChangedEventArgs and Platform::Collections::Details::VectorChangedEventArgs ref classes, store the event arguments to determine what caused the event. *EventArgsで型が定義されている、Details名前空間を作成または使用するときに明示的に使用する必要がないためMapまたはVectorします。The *EventArgs types are defined in the Details namespace because you don't have to construct or consume them explicitly when you use Map or Vector.

関連項目See Also

型システムType System
Visual C 言語リファレンスVisual C++ Language Reference
名前空間参照Namespaces Reference