Struct pix_engine::vector::Vector
source · pub struct Vector<T = f64, const N: usize = 2>(/* private fields */);
Expand description
A Euclidean Vector
in N-dimensional space.
Also known as a geometric vector. A Vector
has both a magnitude and a direction. The Vector
struct, however, contains N values for each dimensional coordinate.
The magnitude and direction are retrieved with the mag and heading methods.
Some example uses of a Vector include modeling a position, velocity, or acceleration of an object or particle.
Vectors can be combined using vector math, so for example two Vectors can be added together
to form a new Vector using let v3 = v1 + v2
or you can add one Vector to another by calling
v1 += v2
.
Please see the module-level documentation for examples.
Implementations§
source§impl<T, const N: usize> Vector<T, N>
impl<T, const N: usize> Vector<T, N>
sourcepub fn as_<U>(&self) -> Vector<U, N>where
U: 'static + Copy,
T: AsPrimitive<U>,
pub fn as_<U>(&self) -> Vector<U, N>where
U: 'static + Copy,
T: AsPrimitive<U>,
Converts Vector < T, N > to Vector < U, N >.
source§impl<T: Float, const N: usize> Vector<T, N>
impl<T: Float, const N: usize> Vector<T, N>
source§impl<T, const N: usize> Vector<T, N>
impl<T, const N: usize> Vector<T, N>
sourcepub const fn new(coords: [T; N]) -> Self
pub const fn new(coords: [T; N]) -> Self
Constructs a Vector
from [T; N]
coordinates.
Examples
let v = Vector::new([2.1]);
assert_eq!(v.coords(), [2.1]);
let v = Vector::new([2.1, 3.5]);
assert_eq!(v.coords(), [2.1, 3.5]);
let v = Vector::new([2.1, 3.5, 1.0]);
assert_eq!(v.coords(), [2.1, 3.5, 1.0]);
source§impl<T: Num + Float> Vector<T>
impl<T: Num + Float> Vector<T>
sourcepub fn rotated<V>(v: V, angle: T) -> Self
pub fn rotated<V>(v: V, angle: T) -> Self
Constructs a Vector
from another Vector
, rotated by an angle
.
Example
use pix_engine::math::FRAC_PI_2;
let v1 = Vector::new([10.0, 20.0]);
let v2 = Vector::rotated(v1, FRAC_PI_2);
assert!(v2.approx_eq(vector![-20.0, 10.0], 1e-4));
sourcepub fn from_angle(angle: T, length: T) -> Self
pub fn from_angle(angle: T, length: T) -> Self
source§impl<T: Num + Float> Vector<T, 3>
impl<T: Num + Float> Vector<T, 3>
sourcepub fn cross<V>(&self, v: V) -> Self
pub fn cross<V>(&self, v: V) -> Self
Returns the cross product between two
Vector
s. Only defined for 3D Vector
s.
Example
let v1 = vector!(1.0, 2.0, 3.0);
let v2 = vector!(1.0, 2.0, 3.0);
let cross = v1.cross(v2);
assert_eq!(cross.coords(), [0.0, 0.0, 0.0]);
sourcepub fn angle_between<V>(&self, v: V) -> T
pub fn angle_between<V>(&self, v: V) -> T
Returns the angle between two 3D Vector
s in radians.
Example
let v1 = vector!(1.0, 0.0, 0.0);
let v2 = vector!(0.0, 1.0, 0.0);
let angle = v1.angle_between(v2);
assert_eq!(angle, std::f64::consts::FRAC_PI_2);
source§impl<T: Copy, const N: usize> Vector<T, N>
impl<T: Copy, const N: usize> Vector<T, N>
sourcepub fn from_point(p: Point<T, N>) -> Self
pub fn from_point(p: Point<T, N>) -> Self
sourcepub fn coords(&self) -> [T; N]
pub fn coords(&self) -> [T; N]
Get Vector
coordinates as [T; N]
.
Example
let v = vector!(2.0, 1.0, 3.0);
assert_eq!(v.coords(), [2.0, 1.0, 3.0]);
sourcepub fn coords_mut(&mut self) -> &mut [T; N]
pub fn coords_mut(&mut self) -> &mut [T; N]
Get Vector
coordinates as a mutable slice &[T; N]
.
Example
let mut vector = vector!(2.0, 1.0, 3.0);
for v in vector.coords_mut() {
*v *= 2.0;
}
assert_eq!(vector.coords(), [4.0, 2.0, 6.0]);
source§impl<T: Num, const N: usize> Vector<T, N>
impl<T: Num, const N: usize> Vector<T, N>
sourcepub fn offset<V, const M: usize>(&mut self, offsets: V)
pub fn offset<V, const M: usize>(&mut self, offsets: V)
Constructs a Vector
by shifting coordinates by given amount.
Examples
let mut v = vector!(2.0, 3.0, 1.5);
v.offset([2.0, -4.0]);
assert_eq!(v.coords(), [4.0, -1.0, 1.5]);
sourcepub fn offset_y(&mut self, offset: T)
pub fn offset_y(&mut self, offset: T)
Offsets the y-coordinate
of the point by a given amount.
Panics
If Vector
has less than 2 dimensions.
sourcepub fn offset_z(&mut self, offset: T)
pub fn offset_z(&mut self, offset: T)
Offsets the z-coordinate
of the point by a given amount.
Panics
If Vector
has less than 3 dimensions.
sourcepub fn scale<U>(&mut self, s: U)
pub fn scale<U>(&mut self, s: U)
Constructs a Vector
by multiplying it by the given scale factor.
Examples
let mut v = vector!(2.0, 3.0, 1.5);
v.scale(2.0);
assert_eq!(v.coords(), [4.0, 6.0, 3.0]);
sourcepub fn wrap(&mut self, wrap: [T; N], size: T)where
T: Signed,
pub fn wrap(&mut self, wrap: [T; N], size: T)where
T: Signed,
Wraps Vector
around the given [T; N]
, and size (radius).
Examples
let mut v = vector!(200.0, 300.0);
v.wrap([150.0, 400.0], 10.0);
assert_eq!(v.coords(), [-10.0, 300.0]);
let mut v = vector!(-100.0, 300.0);
v.wrap([150.0, 400.0], 10.0);
assert_eq!(v.coords(), [160.0, 300.0]);
sourcepub fn random() -> Selfwhere
T: SampleUniform,
pub fn random() -> Selfwhere
T: SampleUniform,
Constructs a random unit Vector
in 1D space.
Example
let v: Vector<f64, 3> = Vector::random();
assert!(v.x() > -1.0 && v.x() < 1.0);
assert!(v.y() > -1.0 && v.y() < 1.0);
assert!(v.z() > -1.0 && v.z() < 1.0);
// May make v's (x, y, z) values something like:
// (0.61554617, 0.0, 0.0) or
// (-0.4695841, 0.0, 0.0) or
// (0.6091097, 0.0, 0.0)
source§impl<T: Num + Float, const N: usize> Vector<T, N>
impl<T: Num + Float, const N: usize> Vector<T, N>
sourcepub fn reflection<V>(v: V, normal: V) -> Self
pub fn reflection<V>(v: V, normal: V) -> Self
Constructs a Vector
from a reflection about a normal to a line in 2D space or a plane in 3D
space.
Example
let v1 = Vector::new([1.0, 1.0, 0.0]);
let normal = Vector::new([0.0, 1.0, 0.0]);
let v2 = Vector::reflection(v1, normal);
assert_eq!(v2.coords(), [-1.0, 1.0, 0.0]);
sourcepub fn normalized<V>(v: V) -> Self
pub fn normalized<V>(v: V) -> Self
Constructs a unit Vector
of length 1
from another Vector
.
Example
let v1 = Vector::new([0.0, 5.0, 0.0]);
let v2 = Vector::normalized(v1);
assert_eq!(v2.coords(), [0.0, 1.0, 0.0]);
sourcepub fn mag(&self) -> T
pub fn mag(&self) -> T
Returns the magnitude (length) of the Vector
.
The formula used for 2D is sqrt(x*x + y*y)
.
The formula used for 3D is sqrt(x*x + y*y + z*z)
.
Example
let v = vector!(1.0, 2.0, 3.0);
let abs_difference = (v.mag() as f64 - 3.7416).abs();
assert!(abs_difference <= 1e-4);
sourcepub fn mag_sq(&self) -> T
pub fn mag_sq(&self) -> T
Returns the squared magnitude (length) of the Vector
. This is faster if the real length
is not required in the case of comparing vectors.
The formula used for 2D is x*x + y*y
.
The formula used for 3D is x*x + y*y + z*z
.
Example
let v = vector!(1.0, 2.0, 3.0);
assert_eq!(v.mag_sq(), 14.0);
sourcepub fn dot<V>(&self, o: V) -> T
pub fn dot<V>(&self, o: V) -> T
Returns the dot product betwen two Vector
s.
Example
let v1 = vector!(1.0, 2.0, 3.0);
let v2 = vector!(2.0, 3.0, 4.0);
let dot_product = v1.dot(v2);
assert_eq!(dot_product, 20.0);
sourcepub fn reflect<V>(&mut self, normal: V)
pub fn reflect<V>(&mut self, normal: V)
Reflect Vector
about a normal to a line in 2D space or a plane in 3D space.
Example
let mut v = vector!(4.0, 6.0); // Vector heading right and down
let n = vector!(0.0, 1.0); // Surface normal facing up
v.reflect(n); // Reflect about the surface normal (e.g. the x-axis)
assert_eq!(v.x(), -4.0);
assert_eq!(v.y(), 6.0);
sourcepub fn set_mag(&mut self, mag: T)
pub fn set_mag(&mut self, mag: T)
Set the magnitude (length) of the Vector
.
Examples
let mut v = vector!(10.0, 20.0, 2.0);
v.set_mag(10.0);
assert!(v.approx_eq(vector![4.4543, 8.9087, 0.8908], 1e-4));
sourcepub fn dist<V>(&self, v: V) -> T
pub fn dist<V>(&self, v: V) -> T
Returns the Euclidean distance between two Vector
s.
Example
let v1 = vector!(1.0, 0.0, 0.0);
let v2 = vector!(0.0, 1.0, 0.0);
let dist = v1.dist(v2);
let abs_difference: f64 = (dist - std::f64::consts::SQRT_2).abs();
assert!(abs_difference <= 1e-4);
sourcepub fn normalize(&mut self)
pub fn normalize(&mut self)
Normalize the Vector
to length 1
making it a unit vector.
Example
let mut v = vector!(10.0, 20.0, 2.0);
v.normalize();
assert!(v.approx_eq(vector!(0.4454, 0.8908, 0.0890), 1e-4));
sourcepub fn limit(&mut self, max: T)
pub fn limit(&mut self, max: T)
Clamp the magnitude (length) of Vector
to the value given by max
.
Example
let mut v = vector!(10.0, 20.0, 2.0);
v.limit(5.0);
assert!(v.approx_eq(vector!(2.2271, 4.4543, 0.4454), 1e-4));
Methods from Deref<Target = [T; N]>§
1.57.0 · sourcepub fn as_slice(&self) -> &[T]
pub fn as_slice(&self) -> &[T]
Returns a slice containing the entire array. Equivalent to &s[..]
.
1.57.0 · sourcepub fn as_mut_slice(&mut self) -> &mut [T]
pub fn as_mut_slice(&mut self) -> &mut [T]
Returns a mutable slice containing the entire array. Equivalent to
&mut s[..]
.
sourcepub fn each_ref(&self) -> [&T; N]
🔬This is a nightly-only experimental API. (array_methods
)
pub fn each_ref(&self) -> [&T; N]
array_methods
)Borrows each element and returns an array of references with the same
size as self
.
Example
#![feature(array_methods)]
let floats = [3.1, 2.7, -1.0];
let float_refs: [&f64; 3] = floats.each_ref();
assert_eq!(float_refs, [&3.1, &2.7, &-1.0]);
This method is particularly useful if combined with other methods, like
map
. This way, you can avoid moving the original
array if its elements are not Copy
.
#![feature(array_methods)]
let strings = ["Ferris".to_string(), "♥".to_string(), "Rust".to_string()];
let is_ascii = strings.each_ref().map(|s| s.is_ascii());
assert_eq!(is_ascii, [true, false, true]);
// We can still access the original array: it has not been moved.
assert_eq!(strings.len(), 3);
sourcepub fn each_mut(&mut self) -> [&mut T; N]
🔬This is a nightly-only experimental API. (array_methods
)
pub fn each_mut(&mut self) -> [&mut T; N]
array_methods
)Borrows each element mutably and returns an array of mutable references
with the same size as self
.
Example
#![feature(array_methods)]
let mut floats = [3.1, 2.7, -1.0];
let float_refs: [&mut f64; 3] = floats.each_mut();
*float_refs[0] = 0.0;
assert_eq!(float_refs, [&mut 0.0, &mut 2.7, &mut -1.0]);
assert_eq!(floats, [0.0, 2.7, -1.0]);
sourcepub fn split_array_ref<const M: usize>(&self) -> (&[T; M], &[T])
🔬This is a nightly-only experimental API. (split_array
)
pub fn split_array_ref<const M: usize>(&self) -> (&[T; M], &[T])
split_array
)Divides one array reference into two at an index.
The first will contain all indices from [0, M)
(excluding
the index M
itself) and the second will contain all
indices from [M, N)
(excluding the index N
itself).
Panics
Panics if M > N
.
Examples
#![feature(split_array)]
let v = [1, 2, 3, 4, 5, 6];
{
let (left, right) = v.split_array_ref::<0>();
assert_eq!(left, &[]);
assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
}
{
let (left, right) = v.split_array_ref::<2>();
assert_eq!(left, &[1, 2]);
assert_eq!(right, &[3, 4, 5, 6]);
}
{
let (left, right) = v.split_array_ref::<6>();
assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
assert_eq!(right, &[]);
}
sourcepub fn split_array_mut<const M: usize>(&mut self) -> (&mut [T; M], &mut [T])
🔬This is a nightly-only experimental API. (split_array
)
pub fn split_array_mut<const M: usize>(&mut self) -> (&mut [T; M], &mut [T])
split_array
)Divides one mutable array reference into two at an index.
The first will contain all indices from [0, M)
(excluding
the index M
itself) and the second will contain all
indices from [M, N)
(excluding the index N
itself).
Panics
Panics if M > N
.
Examples
#![feature(split_array)]
let mut v = [1, 0, 3, 0, 5, 6];
let (left, right) = v.split_array_mut::<2>();
assert_eq!(left, &mut [1, 0][..]);
assert_eq!(right, &mut [3, 0, 5, 6]);
left[1] = 2;
right[1] = 4;
assert_eq!(v, [1, 2, 3, 4, 5, 6]);
sourcepub fn rsplit_array_ref<const M: usize>(&self) -> (&[T], &[T; M])
🔬This is a nightly-only experimental API. (split_array
)
pub fn rsplit_array_ref<const M: usize>(&self) -> (&[T], &[T; M])
split_array
)Divides one array reference into two at an index from the end.
The first will contain all indices from [0, N - M)
(excluding
the index N - M
itself) and the second will contain all
indices from [N - M, N)
(excluding the index N
itself).
Panics
Panics if M > N
.
Examples
#![feature(split_array)]
let v = [1, 2, 3, 4, 5, 6];
{
let (left, right) = v.rsplit_array_ref::<0>();
assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
assert_eq!(right, &[]);
}
{
let (left, right) = v.rsplit_array_ref::<2>();
assert_eq!(left, &[1, 2, 3, 4]);
assert_eq!(right, &[5, 6]);
}
{
let (left, right) = v.rsplit_array_ref::<6>();
assert_eq!(left, &[]);
assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
}
sourcepub fn rsplit_array_mut<const M: usize>(&mut self) -> (&mut [T], &mut [T; M])
🔬This is a nightly-only experimental API. (split_array
)
pub fn rsplit_array_mut<const M: usize>(&mut self) -> (&mut [T], &mut [T; M])
split_array
)Divides one mutable array reference into two at an index from the end.
The first will contain all indices from [0, N - M)
(excluding
the index N - M
itself) and the second will contain all
indices from [N - M, N)
(excluding the index N
itself).
Panics
Panics if M > N
.
Examples
#![feature(split_array)]
let mut v = [1, 0, 3, 0, 5, 6];
let (left, right) = v.rsplit_array_mut::<4>();
assert_eq!(left, &mut [1, 0]);
assert_eq!(right, &mut [3, 0, 5, 6][..]);
left[1] = 2;
right[1] = 4;
assert_eq!(v, [1, 2, 3, 4, 5, 6]);
sourcepub fn as_ascii(&self) -> Option<&[AsciiChar; N]>
🔬This is a nightly-only experimental API. (ascii_char
)
pub fn as_ascii(&self) -> Option<&[AsciiChar; N]>
ascii_char
)Converts this array of bytes into a array of ASCII characters,
or returns None
if any of the characters is non-ASCII.
Examples
#![feature(ascii_char)]
#![feature(const_option)]
const HEX_DIGITS: [std::ascii::Char; 16] =
*b"0123456789abcdef".as_ascii().unwrap();
assert_eq!(HEX_DIGITS[1].as_str(), "1");
assert_eq!(HEX_DIGITS[10].as_str(), "a");
sourcepub unsafe fn as_ascii_unchecked(&self) -> &[AsciiChar; N]
🔬This is a nightly-only experimental API. (ascii_char
)
pub unsafe fn as_ascii_unchecked(&self) -> &[AsciiChar; N]
ascii_char
)Converts this array of bytes into a array of ASCII characters, without checking whether they’re valid.
Safety
Every byte in the array must be in 0..=127
, or else this is UB.
Trait Implementations§
source§impl<T, U, const N: usize> AddAssign<U> for Vector<T, N>
impl<T, U, const N: usize> AddAssign<U> for Vector<T, N>
source§fn add_assign(&mut self, val: U)
fn add_assign(&mut self, val: U)
+=
operation. Read moresource§impl<T: Num, const N: usize> AddAssign<Vector<T, N>> for Point<T, N>
impl<T: Num, const N: usize> AddAssign<Vector<T, N>> for Point<T, N>
source§fn add_assign(&mut self, other: Vector<T, N>)
fn add_assign(&mut self, other: Vector<T, N>)
+=
operation. Read moresource§impl<T: Num, const N: usize> AddAssign for Vector<T, N>
impl<T: Num, const N: usize> AddAssign for Vector<T, N>
source§fn add_assign(&mut self, other: Vector<T, N>)
fn add_assign(&mut self, other: Vector<T, N>)
+=
operation. Read moresource§impl<'de, T, const N: usize> Deserialize<'de> for Vector<T, N>where
T: Serialize + DeserializeOwned,
impl<'de, T, const N: usize> Deserialize<'de> for Vector<T, N>where
T: Serialize + DeserializeOwned,
source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
source§impl<T, U, const N: usize> DivAssign<U> for Vector<T, N>
impl<T, U, const N: usize> DivAssign<U> for Vector<T, N>
source§fn div_assign(&mut self, val: U)
fn div_assign(&mut self, val: U)
/=
operation. Read moresource§impl<T: Default, const N: usize> FromIterator<T> for Vector<T, N>
impl<T: Default, const N: usize> FromIterator<T> for Vector<T, N>
source§fn from_iter<I>(iter: I) -> Selfwhere
I: IntoIterator<Item = T>,
fn from_iter<I>(iter: I) -> Selfwhere
I: IntoIterator<Item = T>,
source§impl<'a, T, const N: usize> IntoIterator for &'a Vector<T, N>
impl<'a, T, const N: usize> IntoIterator for &'a Vector<T, N>
source§impl<'a, T, const N: usize> IntoIterator for &'a mut Vector<T, N>
impl<'a, T, const N: usize> IntoIterator for &'a mut Vector<T, N>
source§impl<T, const N: usize> IntoIterator for Vector<T, N>
impl<T, const N: usize> IntoIterator for Vector<T, N>
source§impl<T, U, const N: usize> MulAssign<U> for Vector<T, N>
impl<T, U, const N: usize> MulAssign<U> for Vector<T, N>
source§fn mul_assign(&mut self, val: U)
fn mul_assign(&mut self, val: U)
*=
operation. Read moresource§impl<T: Ord, const N: usize> Ord for Vector<T, N>
impl<T: Ord, const N: usize> Ord for Vector<T, N>
1.21.0 · source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
source§impl<T: PartialEq, const N: usize> PartialEq for Vector<T, N>
impl<T: PartialEq, const N: usize> PartialEq for Vector<T, N>
source§impl<T: PartialOrd, const N: usize> PartialOrd for Vector<T, N>
impl<T: PartialOrd, const N: usize> PartialOrd for Vector<T, N>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T, U, const N: usize> SubAssign<U> for Vector<T, N>
impl<T, U, const N: usize> SubAssign<U> for Vector<T, N>
source§fn sub_assign(&mut self, val: U)
fn sub_assign(&mut self, val: U)
-=
operation. Read moresource§impl<T: Num, const N: usize> SubAssign<Vector<T, N>> for Point<T, N>
impl<T: Num, const N: usize> SubAssign<Vector<T, N>> for Point<T, N>
source§fn sub_assign(&mut self, other: Vector<T, N>)
fn sub_assign(&mut self, other: Vector<T, N>)
-=
operation. Read moresource§impl<T: Num, const N: usize> SubAssign for Vector<T, N>
impl<T: Num, const N: usize> SubAssign for Vector<T, N>
source§fn sub_assign(&mut self, other: Vector<T, N>)
fn sub_assign(&mut self, other: Vector<T, N>)
-=
operation. Read more