winrt::com_array struct template (C++/WinRT)
Represents a C-style conformant array of data where the underlying buffer is allocated and freed via the COM task allocator, hence the name. It's typically used to represent a C-style conformant array that's allocated by one component, and freed by another.
winrt::com_array is used for passing parameters to and from Windows Runtime APIs. If you're authoring APIs then you'll probably need to construct a winrt::com_array to return a projected array to the caller; either as the return value, or through an output parameter.
winrt::com_array derives from winrt::array_view. See the winrt::array_view struct template topic, which documents members and free operators that are also available to winrt::com_array. However, be aware of the difference in semantics between the base type winrt::array_view (which is a non-owning view, or span, of a contiguous series of values), and winrt::com_array (which allocates and frees its own elements).
Syntax
template <typename T>
struct com_array : winrt::array_view<T>
Template parameters
typename T
The type of the values (elements) that the com_array contains.
Requirements
Minimum supported SDK: Windows SDK version 10.0.17134.0 (Windows 10, version 1803)
Namespace: winrt
Header: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (included by default)
Constructors
| Constructor | Description |
|---|---|
| com_array::com_array constructor | Initializes a new instance of the com_array struct with a copy of the input data, or with default values of T if no data is provided. |
Member functions
| Function | Description |
|---|---|
| com_array::clear function | Makes the com_array object empty. |
Member operators
| Operator | Description |
|---|---|
| com_array::operator= (assignment operator) | Assigns a value to the com_array object. |
Free functions
| Function | Description |
|---|---|
| detach_abi function | Detaches the com_array object from its raw values, perhaps to return them to a caller. The com_array is cleared. Also see winrt::detach_abi function. |
| put_abi function | Retrieves the address of the com_array so that it can be set to another value. Also see winrt::put_abi function. |
| swap function | Swaps the contents of the two com_array parameters. |
com_array::com_array constructor
Initializes a new instance of the com_array struct with a copy of the input data, or with default values of T if no data is provided.
Syntax
The constructors are numbered, and described further in Remarks below.
1. com_array() noexcept;
2. com_array(uint32_t const count);
3. com_array(uint32_t const count, T const& value);
4. template <typename InIt> com_array(InIt first, InIt last);
5. com_array(std::vector<T> const& vectorValue);
6. template <size_t N> com_array(std::array<T, N> const& arrayValue);
7. template <uint32_t N> com_array(T const(&rawArrayValue)[N])
8. com_array(std::initializer_list<T> initializerListValue);
9. com_array(void* ptr, uint32_t const count, winrt::take_ownership_from_abi_t) noexcept;
10. com_array(com_array&& comArrayValue) noexcept;
Template parameters
typename InIt
An input iterator, which provides the input data.
size_t N uint32_t N
The number of values (elements) in the input data.
Parameters
arrayValue
A std::array value that initializes the com_array object.
comArrayValue
Another com_array that initializes the com_array object. After the constructor returns, comArrayValue will be empty.
count
The element count of the com_array object.
first last
A pair of input iterators. The values in the range [first, last) are used to initialize the com_array object.
initializerListValue
An initializer list value that initializes the com_array object.
ptr
A pointer to a block of N values, which you've allocated by using CoTaskMemAlloc. The com_array object takes ownership of this memory.
rawArrayValue
A C-style array that initializes the com_array object.
value
The value to give to each element of the com_array object.
vectorValue
A std::vector value that initializes the com_array object.
Remarks
The constructors are numbered in Syntax above.
1. Default constructor
Constructs an empty buffer.
2. Capacity constructor; default value
Creates a buffer of count elements, all of which are copies of a default-constructed T.
This is similar to (but not the same as) creating a buffer of count elements, each of which is a default-constructed T.
auto players{ winrt::com_array<MediaPlayer>(50) };
The MediaPlayer object's default constructor creates a reference to a new media player object, and its copy constructor copies the reference. Therefore, the above line of code creates an array of 50 references to the same media player object. It doesn't create an array of 50 different media player objects.
3. Capacity constructor; explicit value
Creates a buffer of count elements, each of which is a copy of the provided value.
winrt::com_array(2, 42) is interpreted as an attempt to use the range constructor (4). But it fails because 2 and 42 aren't iterators. To get this to be interpreted as a capacity constructor with an explicit int32_t value, use an explicitly unsigned integer as the first parameter: com_array(2u, 42).
4. Range constructor
Creates a buffer that is a copy of the range [first, last).
State the underlying type T explicitly, like this.
auto a{ winrt::com_array<T>(source.begin(), source.end()) };
To move the range, rather than copying it, use the std::move_iterator iterator adaptor.
auto a{ winrt::com_array<T>(std::move_iterator(source.begin()),
std::move_iterator(source.end())) };
5. Vector constructor
Creates a buffer that is a copy of the contents of vectorValue.
6. Array constructor
Creates a buffer that is a copy of the contents of arrayValue.
7. C-style array constructor
Creates a buffer that is a copy of the contents of the C-style array rawArrayValue.
8. Initializer-list constructor
Creates a buffer that is a copy of the contents of the initializer list initializerListValue.
9. ABI constructor
Takes ownership of a buffer of specified length.
This lowest-level of the constructors. Use it when you have a block of memory already allocated via CoTaskMemAlloc, and you want the com_array to assume responsibility for it. To emphasize the special requirements for this constructor, the final argument must be winrt::take_ownership_from_abi.
10. Move constructor
Moves the resources from another com_array of the same type, leaving the original empty.
Constructors 5, 6, and 7
Copies are taken of the contents of the provided container. You can use the range constructor (4) with the std::move_iterator iterator adaptor to move the contents into the com_array instead of copying them.
com_array::clear function
Makes the com_array object empty.
Syntax
void clear() noexcept;
detach_abi function
Detaches the com_array object from its raw values, perhaps to return them to a caller. The com_array is cleared. Also see winrt::detach_abi function.
Syntax
auto detach_abi(winrt::com_array<T>& object) noexcept;
auto detach_abi(winrt::com_array<T>&& object) noexcept;
Parameters
object
A com_array object to operate on.
Return value
A two-element tuple containing an element count, and the contiguous series of values that the com_array spanned.
com_array::operator= (assignment operator)
Assigns a value to the com_array object.
Syntax
com_array& operator=(winrt::com_array&& comArrayValue) noexcept;
Parameters
comArrayValue
A com_array value to assign to the com_array object.
Return value
A reference to the com_array object.
put_abi function
Retrieves the address of the com_array so that it can be set to another value. Also see winrt::put_abi function.
Syntax
template<typename T> auto put_abi(winrt::com_array<T>& object) noexcept;
Parameters
object
A com_array object to operate on.
Return value
The address of the com_array, ready to be set to another value.
swap function
Swaps the contents of the two com_array parameters.
Syntax
friend void swap(winrt::com_array& left, winrt::com_array& right) noexcept;
Parameters
left right
A com_array value whose contents to mutually swap with those of the other parameter.
Example
using namespace winrt;
...
com_array<byte> left{ 1,2,3 };
com_array<byte> right{ 4,5,6 };
swap(left, right);