You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/cppcx/array-and-writeonlyarray-c-cx.md
+83-74Lines changed: 83 additions & 74 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,79 +10,88 @@ ms.author: "mblome"
10
10
ms.workload: ["cplusplus"]
11
11
---
12
12
# Array and WriteOnlyArray (C++/CX)
13
-
You can freely use regular C-style arrays or [std::array](../standard-library/array-class-stl.md) in a C++/CX program (although [std::vector](../standard-library/vector-class.md) is often a better choice), but in any API that is published in metadata, you must convert a C-style array or vector to a [Platform::Array](../cppcx/platform-array-class.md) or [Platform::WriteOnlyArray](../cppcx/platform-writeonlyarray-class.md) type depending on how it is being used. The [Platform::Array](../cppcx/platform-array-class.md) type is neither as efficient nor as powerful as [std::vector](../standard-library/vector-class.md), so as a general guideline you should avoid its use in internal code that performs lots of operations on the array elements.
14
-
15
-
The following array types can be passed across the ABI:
16
-
17
-
1. const Platform::Array^
18
-
19
-
2. Platform::Array^*
20
-
21
-
3. Platform::WriteOnlyArray
22
-
23
-
4. return value of Platform::Array^
24
-
25
-
You use these array types to implement the three kinds of array patterns that are defined by the Windows Runtime.
26
-
27
-
PassArray
28
-
Used when the caller passes an array to a method. The C++ input parameter type is `const`[Platform::Array](../cppcx/platform-array-class.md)\<T>.
29
-
30
-
FillArray
31
-
Used when the caller passes an array for the method to fill. The C++ input parameter type is [Platform::WriteOnlyArray](../cppcx/platform-writeonlyarray-class.md)\<T>.
32
-
33
-
ReceiveArray
34
-
Used when the caller receives an array that the method allocates. In C++/CX you can return the array in the return value as an Array^ or you can return it as an out parameter as type Array^*.
35
-
36
-
## PassArray pattern
37
-
When client code passes an array to a C++ method and the method does not modify it, the method accepts the array as a const Array^. At the Windows Runtime application binary interface (ABI) level, this is known as a PassArray. The next example shows how to pass an array that's allocated in JavaScript to a C++ function that reads from it.
In the ReceiveArray pattern, client code declares an array and passes it to a method which allocates the memory for it and initializes it. The C++ input parameter type is a pointer-to-hat: `Array<T>^*`. The following example shows how to declare an array object in JavaScript, and pass it to a C++ function that allocates the memory, initializes the elements, and returns it to JavaScript. JavaScript treats the allocated array as a return value, but the C++ function treats it as an out parameter.
When you want to allocate an array in the caller, and initialize or modify it in the callee, use `WriteOnlyArray`. The next example shows how to implement a C++ function that uses `WriteOnlyArray` and call it from JavaScript.
The Windows Runtime type system does not support the concept of jagged arrays and therefore you cannot use `IVector<Platform::Array<T>>` as a return value or method parameter in a public method. To pass a jagged array or a sequence of sequences across the ABI, use `IVector<IVector<T>^>`.
74
-
75
-
## Use ArrayReference to avoid copying data
76
-
In some scenarios where data is being passed across the ABI into a [Platform::Array](../cppcx/platform-array-class.md), and you ultimately want to process that data in a C-style array for efficiency, you can use [Platform::ArrayReference](../cppcx/platform-arrayreference-class.md) to avoid the extra copy operation. When you pass a [Platform::ArrayReference](../cppcx/platform-arrayreference-class.md) as an argument to a parameter that takes a `Platform::Array`, the `ArrayReference` will store the data directly into a C-style array that you specify. Just be aware that `ArrayReference` has no lock on the source data, so if it that data is modified or deleted on another thread before the call completes, the results will be undefined.
77
-
78
-
The following code snippet shows how to copy the results of a [DataReader](https://msdn.microsoft.com/library/windows/apps/windows.storage.streams.datareader.aspx) operation into a `Platform::Array` (the usual pattern), and then how to substitute `ArrayReference` to copy the data directly into a C-style array:
In general, you should avoid exposing a `Platform::Array` type as a property in a ref class because the entire array is returned even when client code is only attempting to access a single element. When you need to expose a sequence container as a property in a public ref class, [Windows::Foundation::IVector](https://msdn.microsoft.com/library/windows/apps/br206631.aspx) is a better choice. In private or internal APIs (which are not published to metadata), consider using a standard C++ container such as [std::vector](../standard-library/vector-class.md).
84
-
85
-
## See Also
86
-
[Type System](../cppcx/type-system-c-cx.md)<br/>
13
+
14
+
You can freely use regular C-style arrays or [std::array](../standard-library/array-class-stl.md) in a C++/CX program (although [std::vector](../standard-library/vector-class.md) is often a better choice), but in any API that is published in metadata, you must convert a C-style array or vector to a [Platform::Array](../cppcx/platform-array-class.md) or [Platform::WriteOnlyArray](../cppcx/platform-writeonlyarray-class.md) type depending on how it is being used. The [Platform::Array](../cppcx/platform-array-class.md) type is neither as efficient nor as powerful as [std::vector](../standard-library/vector-class.md), so as a general guideline you should avoid its use in internal code that performs lots of operations on the array elements.
15
+
16
+
The following array types can be passed across the ABI:
17
+
18
+
1. const Platform::Array^
19
+
20
+
1. Platform::Array^*
21
+
22
+
1. Platform::WriteOnlyArray
23
+
24
+
1. return value of Platform::Array^
25
+
26
+
You use these array types to implement the three kinds of array patterns that are defined by the Windows Runtime.
27
+
28
+
PassArray
29
+
Used when the caller passes an array to a method. The C++ input parameter type is `const`[Platform::Array](../cppcx/platform-array-class.md)\<T>.
30
+
31
+
FillArray
32
+
Used when the caller passes an array for the method to fill. The C++ input parameter type is [Platform::WriteOnlyArray](../cppcx/platform-writeonlyarray-class.md)\<T>.
33
+
34
+
ReceiveArray
35
+
Used when the caller receives an array that the method allocates. In C++/CX you can return the array in the return value as an Array^ or you can return it as an out parameter as type Array^*.
36
+
37
+
## PassArray pattern
38
+
39
+
When client code passes an array to a C++ method and the method does not modify it, the method accepts the array as a const Array^. At the Windows Runtime application binary interface (ABI) level, this is known as a PassArray. The next example shows how to pass an array that's allocated in JavaScript to a C++ function that reads from it.
In the ReceiveArray pattern, client code declares an array and passes it to a method which allocates the memory for it and initializes it. The C++ input parameter type is a pointer-to-hat: `Array<T>^*`. The following example shows how to declare an array object in JavaScript, and pass it to a C++ function that allocates the memory, initializes the elements, and returns it to JavaScript. JavaScript treats the allocated array as a return value, but the C++ function treats it as an out parameter.
When you want to allocate an array in the caller, and initialize or modify it in the callee, use `WriteOnlyArray`. The next example shows how to implement a C++ function that uses `WriteOnlyArray` and call it from JavaScript.
The Windows Runtime type system does not support the concept of jagged arrays and therefore you cannot use `IVector<Platform::Array<T>>` as a return value or method parameter in a public method. To pass a jagged array or a sequence of sequences across the ABI, use `IVector<IVector<T>^>`.
80
+
81
+
## Use ArrayReference to avoid copying data
82
+
83
+
In some scenarios where data is being passed across the ABI into a [Platform::Array](../cppcx/platform-array-class.md), and you ultimately want to process that data in a C-style array for efficiency, you can use [Platform::ArrayReference](../cppcx/platform-arrayreference-class.md) to avoid the extra copy operation. When you pass a [Platform::ArrayReference](../cppcx/platform-arrayreference-class.md) as an argument to a parameter that takes a `Platform::Array`, the `ArrayReference` will store the data directly into a C-style array that you specify. Just be aware that `ArrayReference` has no lock on the source data, so if it that data is modified or deleted on another thread before the call completes, the results will be undefined.
84
+
85
+
The following code snippet shows how to copy the results of a [DataReader](https://msdn.microsoft.com/library/windows/apps/windows.storage.streams.datareader.aspx) operation into a `Platform::Array` (the usual pattern), and then how to substitute `ArrayReference` to copy the data directly into a C-style array:
In general, you should avoid exposing a `Platform::Array` type as a property in a ref class because the entire array is returned even when client code is only attempting to access a single element. When you need to expose a sequence container as a property in a public ref class, [Windows::Foundation::IVector](https://msdn.microsoft.com/library/windows/apps/br206631.aspx) is a better choice. In private or internal APIs (which are not published to metadata), consider using a standard C++ container such as [std::vector](../standard-library/vector-class.md).
92
+
93
+
## See Also
94
+
95
+
[Type System](../cppcx/type-system-c-cx.md)<br/>
87
96
[Visual C++ Language Reference](../cppcx/visual-c-language-reference-c-cx.md)<br/>
Copy file name to clipboardExpand all lines: docs/cppcx/attributes-c-cx.md
+36-33Lines changed: 36 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,38 +10,41 @@ ms.author: "mblome"
10
10
ms.workload: ["cplusplus"]
11
11
---
12
12
# Attributes (C++/CX)
13
-
An attribute is a special kind of ref class that can be prepended in square brackets to Windows Runtime types and methods to specify certain behaviors in metadata creation. Several predefined attributes—for example, [Windows::Foundation::Metadata::WebHostHidden](https://msdn.microsoft.com/library/windows/apps/windows.foundation.metadata.webhosthiddenattribute.aspx)—are commonly used in C++/CX code. This example shows how the attribute is applied to a class:
[Type System (C++/CX)](../cppcx/type-system-c-cx.md)<br/>
13
+
14
+
An attribute is a special kind of ref class that can be prepended in square brackets to Windows Runtime types and methods to specify certain behaviors in metadata creation. Several predefined attributes—for example, [Windows::Foundation::Metadata::WebHostHidden](https://msdn.microsoft.com/library/windows/apps/windows.foundation.metadata.webhosthiddenattribute.aspx)—are commonly used in C++/CX code. This example shows how the attribute is applied to a class:
0 commit comments