Struct Simd Copy item path

Reverse the order of the elements in the vector.

Rotates the vector such that the first OFFSET elements of the slice move to the end while the last self.len() - OFFSET elements move to the front. After calling rotate_elements_left, the element previously at index OFFSET will become the first element in the slice.

let a = Simd::from_array([0, 1, 2, 3]);
let x = a.rotate_elements_left::<3>();
assert_eq!(x.to_array(), [3, 0, 1, 2]);

let y = a.rotate_elements_left::<7>();
assert_eq!(y.to_array(), [3, 0, 1, 2]);

let a = Simd::from_array([0, 1, 2, 3]);
let x = a.rotate_elements_right::<3>();
assert_eq!(x.to_array(), [1, 2, 3, 0]);

let y = a.rotate_elements_right::<7>();
assert_eq!(y.to_array(), [1, 2, 3, 0]);

let a = Simd::from_array([0, 1, 2, 3]);
let x = a.shift_elements_left::<3>(255);
assert_eq!(x.to_array(), [3, 255]);

let y = a.shift_elements_left::<7>(255);
assert_eq!(y.to_array(), [255, 255]);

let a = Simd::from_array([0, 1, 2, 3]);
let x = a.shift_elements_right::<3>(255);
assert_eq!(x.to_array(), [255, 255, 0]);

let y = a.shift_elements_right::<7>(255);
assert_eq!(y.to_array(), [255, 255]);

let a = Simd::from_array([0, 1, 2, 3]);
let b = Simd::from_array([4, 5, 6, 7]);
let (x, y) = a.interleave(b);
assert_eq!(x.to_array(), [0, 4, 1, 5]);
assert_eq!(y.to_array(), [2, 6, 3, 7]);

let a = Simd::from_array([0, 4, 1, 5]);
let b = Simd::from_array([2, 6, 3, 7]);
let (x, y) = a.deinterleave(b);
assert_eq!(x.to_array(), [0, 1, 2, 3]);
assert_eq!(y.to_array(), [4, 5, 6, 7]);

Resize a vector.

If M > N, extends the length of a vector, setting the new elements to value. If M < N, truncates the vector to the first M elements.

let x = u32x4::from_array([0, 1, 2, 3]);
assert_eq!(x.resize::<8>(9).to_array(), [0, 1, 2, 3, 9]);
assert_eq!(x.resize::<2>(9).to_array(), [0, 1]);

Extract a vector from another vector.

let x = u32x4::from_array([0, 1, 2, 3]);
assert_eq!(x.extract::<1, 2>().to_array(), [1, 2]);

Swizzle a vector of bytes according to the index vector. Indices within range select the appropriate byte. Indices “out of bounds” instead select 0.

Note that the current implementation is selected during build-time of the standard library, so cargo build -Zbuild-std may be necessary to unlock better performance, especially for larger vectors. A planned compiler improvement will enable using #[target_feature] instead.

Returns the number of elements in this SIMD vector.

§Examples

let v = u32x4::splat(0);
assert_eq!(v.len(), 4);

let v = u32x4::splat(8);
assert_eq!(v.as_array(), &[8, 8]);

let v: u64x4 = Simd::from_array([0, 1, 2, 3]);
assert_eq!(v.as_array(), &[0, 1, 2, 3]);

Converts an array to a SIMD vector.

Converts a SIMD vector to an array.

Converts a slice to a SIMD vector containing slice[..N].

§Panics

Panics if the slice’s length is less than the vector’s Simd::N. Use load_or_default for an alternative that does not panic.

§Example

let source = vec![1, 2, 3, 4, 5, 6];
let v = u32x4::from_slice(&source);
assert_eq!(v.as_array(), &[1, 2, 3, 4]);

let mut dest = vec![0; 6];
let v = u32x4::from_array([1, 2, 3, 4]);
v.copy_to_slice(&mut dest);
assert_eq!(&dest, &[1, 2, 3, 4, 0]);

Reads contiguous elements from slice. Elements are read so long as they’re in-bounds for the slice. Otherwise, the default value for the element type is returned.

§Examples

let vec: Vec<i32> = vec![10, 11];

let result = Simd::<i32, 4>::load_or_default(&vec);
assert_eq!(result, Simd::from_array([10, 11, 0]));

let vec: Vec<i32> = vec![10, 11];
let or = Simd::from_array([-5, -4, -3, -2]);

let result = Simd::load_or(&vec, or);
assert_eq!(result, Simd::from_array([10, 11, -3, -2]));

Reads contiguous elements from slice. Each element is read from memory if its corresponding element in enable is true.

When the element is disabled or out of bounds for the slice, that memory location is not accessed and the corresponding value from or is passed through.

§Examples

let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
let enable = Mask::from_array([true, true, false, true]);
let or = Simd::from_array([-5, -4, -3, -2]);

let result = Simd::load_select(&vec, enable, or);
assert_eq!(result, Simd::from_array([10, 11, -3, 13]));

Reads contiguous elements from slice. Each element is read from memory if its corresponding element in enable is true.

When the element is disabled or out of bounds for the slice, that memory location is not accessed and the corresponding value from or is passed through.

§Examples

let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
let enable = Mask::from_array([true, true, false, true]);
let or = Simd::from_array([-5, -4, -3, -2]);

let result = Simd::load_select(&vec, enable, or);
assert_eq!(result, Simd::from_array([10, 11, -3, 13]));

Reads contiguous elements from slice. Each element is read from memory if its corresponding element in enable is true.

When the element is disabled, that memory location is not accessed and the corresponding value from or is passed through.

§Safety

Enabled loads must not exceed the length of slice.

Reads contiguous elements starting at ptr. Each element is read from memory if its corresponding element in enable is true.

When the element is disabled, that memory location is not accessed and the corresponding value from or is passed through.

§Safety

Enabled ptr elements must be safe to read as if by std::ptr::read.

Reads from potentially discontiguous indices in slice to construct a SIMD vector. If an index is out-of-bounds, the element is instead selected from the or vector.

§Examples

let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
let idxs = Simd::from_array([9, 3, 0, 5]);  / Note the index that is out-of-bounds
let alt = Simd::from_array([-5, -4, -3, -2]);

let result = Simd::gather_or(&vec, idxs, alt);
assert_eq!(result, Simd::from_array([-5, 13, 10, 15]));

Reads from indices in slice to construct a SIMD vector. If an index is out-of-bounds, the element is set to the default given by T: Default.

§Examples

let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
let idxs = Simd::from_array([9, 3, 0, 5]);  / Note the index that is out-of-bounds

let result = Simd::gather_or_default(&vec, idxs);
assert_eq!(result, Simd::from_array([0, 13, 10, 15]));

Reads from indices in slice to construct a SIMD vector. The mask enables all true indices and disables all false indices. If an index is disabled or is out-of-bounds, the element is selected from the or vector.

§Examples

let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
let idxs = Simd::from_array([9, 3, 0, 5]); / Includes an out-of-bounds index
let alt = Simd::from_array([-5, -4, -3, -2]);
let enable = Mask::from_array([true, true, false]); / Includes a masked element

let result = Simd::gather_select(&vec, enable, idxs, alt);
assert_eq!(result, Simd::from_array([-5, 13, 10, -2]));

Reads from indices in slice to construct a SIMD vector. The mask enables all true indices and disables all false indices. If an index is disabled, the element is selected from the or vector.

§Safety

Calling this function with an enabled out-of-bounds index is undefined behavior even if the resulting value is not used.

§Examples

let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
let idxs = Simd::from_array([9, 3, 0, 5]); / Includes an out-of-bounds index
let alt = Simd::from_array([-5, -4, -3, -2]);
let enable = Mask::from_array([true, true, false]); / Includes a masked element
/ If this mask was used to gather, it would be unsound. Let's fix that.
let enable = enable & idxs.simd_lt(Simd::splat(vec.len()));

/ The out-of-bounds index has been masked, so it's safe to gather now.
let result = unsafe { Simd::gather_select_unchecked(&vec, enable, idxs, alt) };
assert_eq!(result, Simd::from_array([-5, 13, 10, -2]));

Reads elementwise from pointers into a SIMD vector.

§Safety

Each read must satisfy the same conditions as core::ptr::read.

§Example

let values = [6, 2, 4, 9];
let offsets = Simd::from_array([1, 0, 3]);
let source = Simd::splat(values.as_ptr()).wrapping_add(offsets);
let gathered = unsafe { Simd::gather_ptr(source) };
assert_eq!(gathered, Simd::from_array([2, 6, 9]));

Conditionally read elementwise from pointers into a SIMD vector. The mask enables all true pointers and disables all false pointers. If a pointer is disabled, the element is selected from the or vector, and no read is performed.

§Safety

Enabled elements must satisfy the same conditions as core::ptr::read.

§Example

let values = [6, 2, 4, 9];
let enable = Mask::from_array([true, true, false, true]);
let offsets = Simd::from_array([1, 0, 3]);
let source = Simd::splat(values.as_ptr()).wrapping_add(offsets);
let gathered = unsafe { Simd::gather_select_ptr(source, enable, Simd::splat(0)) };
assert_eq!(gathered, Simd::from_array([2, 6, 0, 9]));

Conditionally write contiguous elements to slice. The enable mask controls which elements are written, as long as they’re in-bounds of the slice. If the element is disabled or out of bounds, no memory access to that location is made.

§Examples

let mut arr = [0i32; 4];
let write = Simd::from_array([-5, -4, -3, -2]);
let enable = Mask::from_array([false, true]);

write.store_select(&mut arr[..3], enable);
assert_eq!(arr, [0, -4, -3, 0]);

Conditionally write contiguous elements to slice. The enable mask controls which elements are written.

§Safety

Every enabled element must be in bounds for the slice.

§Examples

let mut arr = [0i32; 4];
let write = Simd::from_array([-5, -4, -3, -2]);
let enable = Mask::from_array([false, true]);

unsafe { write.store_select_unchecked(&mut arr, enable) };
assert_eq!(arr, [0, -4, -3, -2]);

Conditionally write contiguous elements starting from ptr. The enable mask controls which elements are written. When disabled, the memory location corresponding to that element is not accessed.

§Safety

Memory addresses for element are calculated pointer::wrapping_offset and each enabled element must satisfy the same conditions as core::ptr::write.

Writes the values in a SIMD vector to potentially discontiguous indices in slice. If an index is out-of-bounds, the write is suppressed without panicking. If two elements in the scattered vector would write to the same index only the last element is guaranteed to actually be written.

§Examples

let mut vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
let idxs = Simd::from_array([9, 3, 0]); / Note the duplicate index.
let vals = Simd::from_array([-27, 82, -41, 124]);

vals.scatter(&mut vec, idxs); / two logical writes means the last wins.
assert_eq!(vec, vec![124, 11, 12, 82, 14, 15, 16, 17, 18]);

Writes values from a SIMD vector to multiple potentially discontiguous indices in slice. The mask enables all true indices and disables all false indices. If an enabled index is out-of-bounds, the write is suppressed without panicking. If two enabled elements in the scattered vector would write to the same index, only the last element is guaranteed to actually be written.

§Examples

let mut vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
let idxs = Simd::from_array([9, 3, 0]); / Includes an out-of-bounds index
let vals = Simd::from_array([-27, 82, -41, 124]);
let enable = Mask::from_array([true, true, false]); / Includes a masked element

vals.scatter_select(&mut vec, enable, idxs); / The last write is masked, thus omitted.
assert_eq!(vec, vec![-41, 11, 12, 82, 14, 15, 16, 17, 18]);

Writes values from a SIMD vector to multiple potentially discontiguous indices in slice. The mask enables all true indices and disables all false indices. If two enabled elements in the scattered vector would write to the same index, only the last element is guaranteed to actually be written.

§Safety

Calling this function with an enabled out-of-bounds index is undefined behavior, and may lead to memory corruption.

§Examples

let mut vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
let idxs = Simd::from_array([9, 3, 0]);
let vals = Simd::from_array([-27, 82, -41, 124]);
let enable = Mask::from_array([true, true, false]); / Masks the final index
/ If this mask was used to scatter, it would be unsound. Let's fix that.
let enable = enable & idxs.simd_lt(Simd::splat(vec.len()));

/ We have masked the OOB index, so it's safe to scatter now.
unsafe { vals.scatter_select_unchecked(&mut vec, enable, idxs); }
/ The second write to index 0 was masked, thus omitted.
assert_eq!(vec, vec![-41, 11, 12, 82, 14, 15, 16, 17, 18]);

let mut values = [0; 4];
let offset = Simd::from_array([3, 2, 1, 0]);
let ptrs = Simd::splat(values.as_mut_ptr()).wrapping_add(offset);
unsafe { Simd::from_array([6, 3, 5, 7]).scatter_ptr(ptrs); }
assert_eq!(values, [7, 5, 3, 6]);

Conditionally write pointers elementwise into a SIMD vector. The mask enables all true pointers and disables all false pointers. If a pointer is disabled, the write to its pointee is skipped.

§Safety

Enabled pointers must satisfy the same conditions as core::ptr::write.

§Example

let mut values = [0; 4];
let offset = Simd::from_array([3, 2, 1, 0]);
let ptrs = Simd::splat(values.as_mut_ptr()).wrapping_add(offset);
let enable = Mask::from_array([true, true, false]);
unsafe { Simd::from_array([6, 3, 5, 7]).scatter_select_ptr(ptrs, enable); }
assert_eq!(values, [0, 0, 3, 6]);