[API Proposal]: Vector.Create

[EgorBo]

Background and motivation

Currently, when we need to create a vector from a scalar or array, we do:

_ = Vector64.Create(42);
_ = Vector128.Create(42);
_ = Vector256.Create(42);
_ = Vector512.Create(42);
_ = new Vector2(42);
_ = new Vector3(42);
_ = new Vector4(42);
_ = new Vector<int>(42);

I propose we add Create methods to Vector2/3/4 and Vector<> too for slightly better consistency.

API Proposal

namespace System.Numerics
{
    public static class Vector
    {
        public static Vector<T> Create<T>(T value);
        public static Vector<T> Create<T>(ReadOnlySpan<T> values);

        public static Quaternion AsQuaternion(this Vector4 value);
        public static Plane AsPlane(this Vector4 value);

        public static Vector2 AsVector2(this Vector4 value);
        public static Vector3 AsVector3(this Vector4 value);

        public static Vector4 AsVector4(this Quaternion value);
        public static Vector4 AsVector4(this Plane value);
        public static Vector4 AsVector4(this Vector2 value);
        public static Vector4 AsVector4(this Vector3 value);
        public static Vector4 AsVector4Unsafe(this Vector2 value);
        public static Vector4 AsVector4Unsafe(this Vector3 value);
    }

    public struct Vector2
    {
        public static Vector2 Create(float value);
        public static Vector2 Create(float x, float y);
        public static Vector2 Create(ReadOnlySpan<float> values);
    }

    public struct Vector3
    {
        public static Vector3 Create(float value);
        public static Vector3 Create(float x, float y, float z);
        public static Vector3 Create(Vector2 vector, float z);
        public static Vector3 Create(ReadOnlySpan<float> values);
    }

    public struct Vector4
    {
        public static Vector4 Create(float value);
        public static Vector4 Create(float x, float y, float z, float w);
        public static Vector4 Create(Vector2 vector, float z, float w);
        public static Vector4 Create(Vector3 vector, float w);
        public static Vector4 Create(ReadOnlySpan<float> values);
    }
}

namespace System.Runtime.Intrinsics
{
    public static class Vector128
    {
        public static Vector128<float> AsVector128Unsafe(this Vector2 value);
        public static Vector128<float> AsVector128Unsafe(this Vector3 value);
        public static Vector128<float> AsVector128Unsafe(this Vector4 value);
    }
}

We might also add T[] values, int offset and Span<T> overloads.

API Usage

Vector<int> v = Vector.Create(42);

Alternative Designs

No response

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-numerics
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Currently, when we need to create a vector from a scalar or array, we do:

_ = Vector64.Create(42);
_ = Vector128.Create(42);
_ = Vector256.Create(42);
_ = Vector512.Create(42);
_ = new Vector2(42);
_ = new Vector3(42);
_ = new Vector4(42);
_ = new Vector<int>(42);

I propose we add Create methods to Vector2/3/4 and Vector<> too for slightly better consistency.

API Proposal

namespace System.Numerics
{
    public struct Vector
    {
        public static Vector<T> Create(T value);
        public static Vector<T> Create(ReadOnlySpan<T> values);
    }

    public struct Vector2
    {
        public static Vector2 Create(float value);
        public static Vector2 Create(float x, float y);
        public static Vector2 Create(ReadOnlySpan<float> values);
    }

    public struct Vector3
    {
        public static Vector3 Create(float value);
        public static Vector3 Create(float x, float y, float z);
        public static Vector3 Create(ReadOnlySpan<float> values);
    }

    public struct Vector4
    {
        public static Vector4 Create(float value);
        public static Vector4 Create(float x, float y, float z, float w);
        public static Vector4 Create(ReadOnlySpan<float> values);
    }
}

Not might also add T[] values, int offset and Span<T> overloads.

API Usage

Vector<int> v = Vector.Create(42);

Alternative Designs

No response

Risks

No response

Author:	EgorBo
Assignees:	-
Labels:	api-suggestion, area-System.Numerics
Milestone:	-

[EgorBo]

cc @tannergooding

[MichalPetryka]

This'd probably be required for making them implement ISimdVector anyway?

[EgorBo]

This'd probably be required for making them implement ISimdVector anyway?

Probably? if we plan to implement ISimdVector in VectorT

[tannergooding]

That's part of the long term plan, yes. However, I don't think ISimdVector can be made public without a language feature or two as we won't be able to correctly version it or expose some core APIs otherwise.

[bartonjs]

Video

Looks good as proposed

namespace System.Numerics
{
    public static partial class Vector
    {
        public static Vector<T> Create<T>(T value);
        public static Vector<T> Create<T>(ReadOnlySpan<T> values);

        public static Quaternion AsQuaternion(this Vector4 value);
        public static Plane AsPlane(this Vector4 value);

        public static Vector2 AsVector2(this Vector4 value);
        public static Vector3 AsVector3(this Vector4 value);

        public static Vector4 AsVector4(this Quaternion value);
        public static Vector4 AsVector4(this Plane value);
        public static Vector4 AsVector4(this Vector2 value);
        public static Vector4 AsVector4(this Vector3 value);
        public static Vector4 AsVector4Unsafe(this Vector2 value);
        public static Vector4 AsVector4Unsafe(this Vector3 value);
    }

    public partial struct Vector2
    {
        public static Vector2 Create(float value);
        public static Vector2 Create(float x, float y);
        public static Vector2 Create(ReadOnlySpan<float> values);
    }

    public partial struct Vector3
    {
        public static Vector3 Create(float value);
        public static Vector3 Create(float x, float y, float z);
        public static Vector3 Create(Vector2 vector, float z);
        public static Vector3 Create(ReadOnlySpan<float> values);
    }

    public partial struct Vector4
    {
        public static Vector4 Create(float value);
        public static Vector4 Create(float x, float y, float z, float w);
        public static Vector4 Create(Vector2 vector, float z, float w);
        public static Vector4 Create(Vector3 vector, float w);
        public static Vector4 Create(ReadOnlySpan<float> values);
    }
}

namespace System.Runtime.Intrinsics
{
    public static partial class Vector128
    {
        public static Vector128<float> AsVector128Unsafe(this Vector2 value);
        public static Vector128<float> AsVector128Unsafe(this Vector3 value);
        public static Vector128<float> AsVector128Unsafe(this Vector4 value);
    }
}

[julealgon]

Do these Create methods only exist to workaround the lack of generic type inference on constructors? Or is there more to it?

[tannergooding]

They exist for parity with Vector64/128/256/512<T>, so that they can be used with the eventual exposure of a new ISimdVector<TSelf, T> (we have this internally already), and because they can provide a slight perf advantage and overall better IR/codegen due to operating byvalue instead of taking this via an implicit byref (which requires a block copy and the JIT to elide it).

[tannergooding]

This was resolved in #103462