29 Numerics library [numerics]

29.10 Data-parallel types [simd]

29.10.6 Class template basic_simd [simd.class]

29.10.6.1 Class template basic_simd overview [simd.overview]

namespace std::datapar { template<class T, class Abi> class basic_simd { public: using value_type = T; using mask_type = basic_simd_mask<sizeof(T), Abi>; using abi_type = Abi; static constexpr integral_constant<simd-size-type, simd-size-v<T, Abi>> size {}; constexpr basic_simd() noexcept = default; // [simd.ctor], basic_simd constructors template<class U> constexpr explicit(see below) basic_simd(U&& value) noexcept; template<class U, class UAbi> constexpr explicit(see below) basic_simd(const basic_simd<U, UAbi>&) noexcept; template<class G> constexpr explicit basic_simd(G&& gen) noexcept; template<class R, class... Flags> constexpr basic_simd(R&& range, flags<Flags...> = {}); template<class R, class... Flags> constexpr basic_simd(R&& range, const mask_type& mask, flags<Flags...> = {}); template<simd-floating-point V> constexpr explicit(see below) basic_simd(const V& reals, const V& imags = {}) noexcept; // [simd.subscr], basic_simd subscript operators constexpr value_type operator[](simd-size-type) const; // [simd.unary], basic_simd unary operators constexpr basic_simd& operator++() noexcept; constexpr basic_simd operator++(int) noexcept; constexpr basic_simd& operator--() noexcept; constexpr basic_simd operator--(int) noexcept; constexpr mask_type operator!() const noexcept; constexpr basic_simd operator~() const noexcept; constexpr basic_simd operator+() const noexcept; constexpr basic_simd operator-() const noexcept; // [simd.binary], basic_simd binary operators friend constexpr basic_simd operator+(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator-(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator*(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator/(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator%(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator&(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator|(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator^(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator<<(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator>>(const basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd operator<<(const basic_simd&, simd-size-type) noexcept; friend constexpr basic_simd operator>>(const basic_simd&, simd-size-type) noexcept; // [simd.cassign], basic_simd compound assignment friend constexpr basic_simd& operator+=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator-=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator*=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator/=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator%=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator&=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator|=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator^=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator<<=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator>>=(basic_simd&, const basic_simd&) noexcept; friend constexpr basic_simd& operator<<=(basic_simd&, simd-size-type) noexcept; friend constexpr basic_simd& operator>>=(basic_simd&, simd-size-type) noexcept; // [simd.comparison], basic_simd compare operators friend constexpr mask_type operator==(const basic_simd&, const basic_simd&) noexcept; friend constexpr mask_type operator!=(const basic_simd&, const basic_simd&) noexcept; friend constexpr mask_type operator>=(const basic_simd&, const basic_simd&) noexcept; friend constexpr mask_type operator<=(const basic_simd&, const basic_simd&) noexcept; friend constexpr mask_type operator>(const basic_simd&, const basic_simd&) noexcept; friend constexpr mask_type operator<(const basic_simd&, const basic_simd&) noexcept; // [simd.complex.access], basic_simd complex-value accessors constexpr auto real() const noexcept; constexpr auto imag() const noexcept; template<simd-floating-point V> constexpr void real(const V& v) noexcept; template<simd-floating-point V> constexpr void imag(const V& v) noexcept; // [simd.cond], basic_simd exposition only conditional operators friend constexpr basic_simd simd-select-impl( // exposition only const mask_type&, const basic_simd&, const basic_simd&) noexcept; }; template<class R, class... Ts> basic_simd(R&& r, Ts...) -> see below; }

Every specialization of basic_simd is a complete type.

The specialization of basic_simd<T, Abi> is

(1.1)
enabled, if T is a vectorizable type, and there exists value N in the range [1, 64], such that Abi is deduce-abi-t<T, N>,
(1.2)
otherwise, disabled, if T is not a vectorizable type,
(1.3)
otherwise, it is implementation-defined if such a specialization is enabled.

If basic_simd<T, Abi> is disabled, then the specialization has a deleted default constructor, deleted destructor, deleted copy constructor, and deleted copy assignment.

In addition only the value_type, abi_type, and mask_type members are present.

If basic_simd<T, Abi> is enabled, then basic_simd<T, Abi> is trivially copyable, default-initialization of an object of such a type default-initializes all elements, and value-initialization value-initializes all elements ([dcl.init.general]).

Recommended practice: Implementations should support implicit conversions between specializations of basic_simd and appropriate implementation-defined types.

[Note 1:

Appropriate types are non-standard vector types which are available in the implementation.

— end note]

29.10.6.2 basic_simd constructors [simd.ctor]

🔗

template<class U> constexpr explicit(see below) basic_simd(U&& value) noexcept;

Let From denote the type remove_cvref_t<U>.

Constraints: value_type satisfies constructible_from<U>.

Effects: Initializes each element to the value of the argument after conversion to value_type.

Remarks: The expression inside explicit evaluates to false if and only if U satisfies convertible_to<value_type>, and either

(4.1)
From is not an arithmetic type and does not satisfy constexpr-wrapper-like,
(4.2)
From is an arithmetic type and the conversion from From to value_type is value-preserving ([simd.general]), or
(4.3)
From satisfies constexpr-wrapper-like, remove_const_t<decltype(From::value)> is an arithmetic type, and From::value is representable by value_type.

🔗

template<class U, class UAbi>
  constexpr explicit(see below) basic_simd(const basic_simd<U, UAbi>& x) noexcept;

Constraints: simd-size-v<U, UAbi> == size() is true.

Effects: Initializes the

i^{th}

element with static_cast<T>(x[i]) for all i in the range of [0, size()).

Remarks: The expression inside explicit evaluates to true if either

(7.1)
the conversion from U to value_type is not value-preserving, or
(7.2)
both U and value_type are integral types and the integer conversion rank ([conv.rank]) of U is greater than the integer conversion rank of value_type, or
(7.3)
both U and value_type are floating-point types and the floating-point conversion rank ([conv.rank]) of U is greater than the floating-point conversion rank of value_type.

🔗

template<class G> constexpr explicit basic_simd(G&& gen);

Let From

_{i}

denote the type decltype(gen(integral_constant<simd-size-type, i>())).

Constraints: From

_{i}

satisfies convertible_to<value_type> for all i in the range of [0, size()).

In addition, for all i in the range of [0, size()), if From

_{i}

is an arithmetic type, conversion from From

_{i}

to value_type is value-preserving.

Effects: Initializes the

i^{th}

element with static_cast<value_type>(gen(integral_constant<simd-size-type, i>())) for all i in the range of [0, size()).

Remarks: gen is invoked exactly once for each i, in increasing order of i.

🔗

template<class R, class... Flags>
  constexpr basic_simd(R&& r, flags<Flags...> = {});
template<class R, class... Flags>
  constexpr basic_simd(R&& r, const mask_type& mask, flags<Flags...> = {});

Let mask be mask_type(true) for the overload with no mask parameter.

Constraints:

(13.1)
R models ranges::contiguous_range and ranges::sized_range,
(13.2)
ranges::size(r) is a constant expression, and
(13.3)
ranges::size(r) is equal to size().

Mandates:

(14.1)
ranges::range_value_t<R> is a vectorizable type, and
(14.2)
if the template parameter pack Flags does not contain convert-flag, then the conversion from ranges::range_value_t<R> to value_type is value-preserving.

Preconditions:

(15.1)
If the template parameter pack Flags contains aligned-flag, ranges::data(range) points to storage aligned by alignment_v<basic_simd, ranges::range_value_t<R>>.
(15.2)
If the template parameter pack Flags contains overaligned-flag<N>, ranges::data(range) points to storage aligned by N.

Effects: Initializes the

i^{th}

element with mask[i] ? static_cast<T>(ranges::data(range)[i]) : T() for all i in the range of [0, size()).

🔗

template<class R, class... Ts>
  basic_simd(R&& r, Ts...) -> see below;

Constraints:

(17.1)
R models ranges::contiguous_range and ranges::sized_range, and
(17.2)
ranges::size(r) is a constant expression.

Remarks: The deduced type is equivalent to simd<ranges::range_value_t<R>, ranges::size(r)>.

🔗

template<simd-floating-point V>
  constexpr explicit(see below)
    basic_simd(const V& reals, const V& imags = {}) noexcept;

Constraints:

(19.1)
simd-complex<basic_simd> is modeled, and
(19.2)
V::size() == size() is true.

Effects: Initializes the

i^{th}

element with value_type(reals[i], imags[i]) for all i in the range [0, size()).

Remarks: The expression inside explicit evaluates to false if and only if the floating-point conversion rank of T::value_type is greater than or equal to the floating-point conversion rank of V::value_type.

29.10.6.3 basic_simd subscript operator [simd.subscr]

🔗

constexpr value_type operator[](simd-size-type i) const;

Preconditions: i >= 0 && i < size() is true.

Returns: The value of the

i^{th}

element.

Throws: Nothing.

29.10.6.4 basic_simd unary operators [simd.unary]

Effects in [simd.unary] are applied as unary element-wise operations.

🔗

constexpr basic_simd& operator++() noexcept;

Constraints: requires (value_type a) { ++a; } is true.

Effects: Increments every element by one.

Returns: *this.

🔗

constexpr basic_simd operator++(int) noexcept;

Constraints: requires (value_type a) { a++; } is true.

Effects: Increments every element by one.

Returns: A copy of *this before incrementing.

🔗

constexpr basic_simd& operator--() noexcept;

Constraints: requires (value_type a) { --a; } is true.

Effects: Decrements every element by one.

Returns: *this.

🔗

constexpr basic_simd operator--(int) noexcept;

Constraints: requires (value_type a) { a--; } is true.

Effects: Decrements every element by one.

Returns: A copy of *this before decrementing.

🔗

constexpr mask_type operator!() const noexcept;

Constraints: requires (const value_type a) { !a; } is true.

Returns: A basic_simd_mask object with the

i^{th}

element set to !operator[](i) for all i in the range of [0, size()).

🔗

constexpr basic_simd operator~() const noexcept;

Constraints: requires (const value_type a) { ~a; } is true.

Returns: A basic_simd object with the

i^{th}

element set to ~operator[](i) for all i in the range of [0, size()).

🔗

constexpr basic_simd operator+() const noexcept;

Constraints: requires (const value_type a) { +a; } is true.

Returns: *this.

🔗

constexpr basic_simd operator-() const noexcept;

Constraints: requires (const value_type a) { -a; } is true.

Returns: A basic_simd object where the

i^{th}

element is initialized to -operator[](i) for all i in the range of [0, size()).