From 63eab7b00c177fb988ba8f616b85e688e371d011 Mon Sep 17 00:00:00 2001 From: Ganbarukamo41 Date: Sat, 12 Oct 2019 14:47:34 +0900 Subject: [PATCH 1/5] Update System.Numerics.Vector documents * Emphasise that this type is not appropriate for general purpose vector operations * Update ctor remarks so that only primitive numeric types are allowed * Update ctor remarks so that only the first `Vector.Count` elements are added to the vector (for Span/Array overloads) * Add information about exception that can be thrown when array.Length < Vector.Count Related: https://github.com/dotnet/corefx/issues/23448 --- xml/System.Numerics/Vector`1.xml | 61 +++++++++++++++++++++++++------- 1 file changed, 49 insertions(+), 12 deletions(-) diff --git a/xml/System.Numerics/Vector`1.xml b/xml/System.Numerics/Vector`1.xml index 24d0d56f020..40a1a338b84 100644 --- a/xml/System.Numerics/Vector`1.xml +++ b/xml/System.Numerics/Vector`1.xml @@ -49,7 +49,7 @@ is an immutable structure that represents a single vector of a specified numeric type. The count of a instance is fixed, but its upper limit is CPU-register dependent. It is intended to be used as a building block for vectorizing large algorithms. + is an immutable structure that represents a single vector of a specified numeric type. The count of a instance is fixed, but its upper limit is CPU-register dependent. It is intended to be used as a building block for vectorizing large algorithms, and therefore it is not appropriate to use this for general purpose vector operations. The structure provides support for hardware acceleration. @@ -94,7 +94,18 @@ A read-only span of bytes that contains the values to add to the vector. The span must contain at least elements. Constructs a vector from the given read-only span of bytes. - To be added. + + property returns `true`. + + Only the first elements are added to the vector. The remainders are ignored. + + ]]> + + + did not contain at least elements. @@ -119,7 +130,18 @@ The values to add to the vector, as a read-only span of objects of type T. The span must contain at least elements. Constructs a vector from the given . - To be added. + + property returns `true`. + + Only the first elements are added to the vector. The remainders are ignored. + + ]]> + + + did not contain at least elements. @@ -147,7 +169,18 @@ The values to add to the vector, as a span of objects of type T. The span must contain at least elements. Constructs a vector from the given . - To be added. + + property returns `true`. + + Only the first elements are added to the vector. The remainders are ignored. + + ]]> + + + did not contain at least elements. @@ -220,13 +253,15 @@ - A numeric array. + The values to add to the vector, as an array of objects of type T. The array must contain at least elements. Creates a vector from a specified array. elements. + The type `T` can be any primitive numeric type (that is, a numeric type whose property returns `true`. + + Only the first elements are added to the vector. The remainders are ignored. ]]> @@ -264,16 +299,18 @@ - A numeric array. + The values to add to the vector, as an array of objects of type T. The array must contain at least elements from the specified index. The starting index position from which to create the vector. Creates a vector from a specified array starting at a specified index position. - elements from the specified index. - - ]]> + The type `T` can be any primitive numeric type (that is, a numeric type whose property returns `true`. + + Only the first elements are added to the vector. The remainders are ignored. + + ]]> is . From b09173880e8ce1b26ffdf09cd994718d24cdb68f Mon Sep 17 00:00:00 2001 From: Gnbrkm41 Date: Sun, 13 Oct 2019 03:35:58 +0900 Subject: [PATCH 2/5] Apply suggestions * Pull the type constraint to the top of the ctor docs since it's shared throughout, list out the types for future-proofing * Update param descriptions for array/spans to be explicit about the remainders Part of dotnet-api-docs/#3334 Co-Authored-By: Tanner Gooding --- xml/System.Numerics/Vector`1.xml | 68 +++++++++++++++++++++++--------- 1 file changed, 49 insertions(+), 19 deletions(-) diff --git a/xml/System.Numerics/Vector`1.xml b/xml/System.Numerics/Vector`1.xml index 40a1a338b84..396970af738 100644 --- a/xml/System.Numerics/Vector`1.xml +++ b/xml/System.Numerics/Vector`1.xml @@ -49,7 +49,7 @@ is an immutable structure that represents a single vector of a specified numeric type. The count of a instance is fixed, but its upper limit is CPU-register dependent. It is intended to be used as a building block for vectorizing large algorithms, and therefore it is not appropriate to use this for general purpose vector operations. + is an immutable structure that represents a single vector of a specified numeric type. The count of a instance is fixed, but its upper limit is CPU-register dependent. It is intended to be used as a building block for vectorizing large algorithms, and therefore cannot be used directly as an arbitrary length vector or tensor. The structure provides support for hardware acceleration. @@ -72,6 +72,48 @@ + + + System.Numerics.Vectors + 2.0.5.0 + 4.0.0.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 4.1.3.0 + 4.1.4.0 + 4.1.5.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + Creates an instance of Vector<T&rt; + + | +| `byte` | | +| `short` | | +| `ushort` | | +| `int` | | +| `uint` | | +| `long` | | +| `ulong` | | +| `float` | | +| `double` | | + + ]]> + + + + @@ -92,13 +134,12 @@ - A read-only span of bytes that contains the values to add to the vector. The span must contain at least elements. + A read-only span of bytes that contains the values to add to the vector. The span must contain at least elements and only the first elements are used. Constructs a vector from the given read-only span of bytes. property returns `true`. Only the first elements are added to the vector. The remainders are ignored. @@ -128,13 +169,12 @@ - The values to add to the vector, as a read-only span of objects of type T. The span must contain at least elements. + The values to add to the vector, as a read-only span of objects of type T. The span must contain at least elements and only the first elements are used. Constructs a vector from the given . property returns `true`. Only the first elements are added to the vector. The remainders are ignored. @@ -167,13 +207,12 @@ - The values to add to the vector, as a span of objects of type T. The span must contain at least elements. + The values to add to the vector, as a span of objects of type T. The span must contain at least elements and only the first elements are used. Constructs a vector from the given . property returns `true`. Only the first elements are added to the vector. The remainders are ignored. @@ -214,14 +253,7 @@ The numeric type that defines the type of the components in the vector. Creates a vector whose components are of a specified type. - - property returns `true`. - - ]]> - + To be added. @@ -253,13 +285,12 @@ - The values to add to the vector, as an array of objects of type T. The array must contain at least elements. + The values to add to the vector, as an array of objects of type T. The array must contain at least elements and only the first elements are used. Creates a vector from a specified array. property returns `true`. Only the first elements are added to the vector. The remainders are ignored. @@ -299,14 +330,13 @@ - The values to add to the vector, as an array of objects of type T. The array must contain at least elements from the specified index. + The values to add to the vector, as an array of objects of type T. The array must contain at least elements from the specified index and only the first elements are used. The starting index position from which to create the vector. Creates a vector from a specified array starting at a specified index position. property returns `true`. Only the first elements are added to the vector. The remainders are ignored. From d3fc6b2458e3cf3e53813067bd7d8c1918939e97 Mon Sep 17 00:00:00 2001 From: Ganbarukamo41 Date: Sun, 13 Oct 2019 03:58:22 +0900 Subject: [PATCH 3/5] Use see tag * Reference the type instead of just writing it out --- xml/System.Numerics/Vector`1.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Numerics/Vector`1.xml b/xml/System.Numerics/Vector`1.xml index 396970af738..9db4733f1c6 100644 --- a/xml/System.Numerics/Vector`1.xml +++ b/xml/System.Numerics/Vector`1.xml @@ -90,7 +90,7 @@ 2.1.0.0 - Creates an instance of Vector<T&rt; + Creates an instance of . Date: Sat, 14 Dec 2019 16:48:37 +0900 Subject: [PATCH 4/5] Define the meaning of primitive numeric data type --- xml/System.Numerics/Vector`1.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Numerics/Vector`1.xml b/xml/System.Numerics/Vector`1.xml index 9db4733f1c6..6f6a663e93f 100644 --- a/xml/System.Numerics/Vector`1.xml +++ b/xml/System.Numerics/Vector`1.xml @@ -51,9 +51,9 @@ ## Remarks is an immutable structure that represents a single vector of a specified numeric type. The count of a instance is fixed, but its upper limit is CPU-register dependent. It is intended to be used as a building block for vectorizing large algorithms, and therefore cannot be used directly as an arbitrary length vector or tensor. - The structure provides support for hardware acceleration. + The structure provides support for hardware acceleration. - The following table shows which primitive numeric data type and operation combination uses intrinsic instructions for faster executions: + The term 'primitive numeric data type' in this document refers to numeric data types that are directly supported by the CPU and have instructions that can manipulate those data types. The following table shows which primitive numeric data type and operation combination uses intrinsic instructions for faster executions: | Primitive type | `+` | `-` | `*` | `/` | | --- | :---: | :---: | :---: | :---: | From 1898c62a7aa1556a7bd0bd18260608f913656c44 Mon Sep 17 00:00:00 2001 From: Ganbarukamo41 Date: Tue, 17 Dec 2019 18:47:35 +0900 Subject: [PATCH 5/5] Pluralise "instance" --- xml/System.Numerics/Vector`1.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Numerics/Vector`1.xml b/xml/System.Numerics/Vector`1.xml index 6f6a663e93f..eab1a218494 100644 --- a/xml/System.Numerics/Vector`1.xml +++ b/xml/System.Numerics/Vector`1.xml @@ -49,7 +49,7 @@ is an immutable structure that represents a single vector of a specified numeric type. The count of a instance is fixed, but its upper limit is CPU-register dependent. It is intended to be used as a building block for vectorizing large algorithms, and therefore cannot be used directly as an arbitrary length vector or tensor. + is an immutable structure that represents a single vector of a specified numeric type. The count of instances is fixed, but its upper limit is CPU-register dependent. It is intended to be used as a building block for vectorizing large algorithms, and therefore cannot be used directly as an arbitrary length vector or tensor. The structure provides support for hardware acceleration.