Struct Vector

Source

pub struct Vector<T> {
    pub x: T,
    pub y: T,
    pub z: T,
}

Expand description

A 3D vector, containing an x, y and a z component. While many types can be used for a Vector’s components, the traits they implement determine what functions are available.

Provided that the components implement the necessary traits, Vectors can be added to or subtracted from one-another, and they can be multiplied and divided by scalar values.

There are generally two options for converting between Vector types. If the internal components’ type has an implementation of Into that targets the desired type, then [into_vec()] can be called from the source object, or [from_vec(..)] can be called and the source object can be provided.

If no Into implementation exists, then the only option is to use one of the flavours of casting with as. These are in the form as_types(), and are only implemented for specific types of components. An example usage would look like this:

use math_vector::Vector;
let f64_vector: Vector<f64> = Vector::new(10.3, 11.1, 0.0);
let i32_vector: Vector<i32> = f64_vector.as_i32s();
assert_eq!(Vector::new(10, 11, 0), i32_vector);

Implementations of as_types() are only available when an implementation of [into_vec()] is unavailable. This is to separate between the lossless casting of primitives with into() and from(..), and the lossy casting between primitives of varying detail.

Casts from signed types to unsigned types have a small additional check that ensures a lower bound of 0 on the signed value, to reduce the chances of experiencing undefined behavior. This means that a Vector<f64> with a value of (-10.3, 11.1, 0.0) would become (0, 11, 0) when cast to a Vector<u32> with [as_u32s()].

The current list of interoperable types that can be cast with the as family of functions is as follows:

i32
i64,
isize
u32
u64
usize
f32
f64

Fields§

§x: T§y: T§z: T

Implementations§

Source §

impl<T: Copy + Clone> Vector<T>

Source

pub fn new(x: T, y: T, z: T) -> Self

Create a new Vector with the provided components.

Source

pub fn set(&mut self, x: T, y: T, z: T)

Set the components of the vector to the provided values.

Source

pub fn all(value: T) -> Self

Construct a Vector with all components set to the provided value.

§Example

use math_vector::Vector;
let v = Vector::all(42.0);
assert_eq!(v, Vector::new(42.0, 42.0, 42.0));

Source

pub fn from_vec<U: Into<T> + Copy + Clone>(src: Vector) -> Vector<T>

Convert a Vector of type U to one of type T. Available only when type T has implemented From.

§Example

use math_vector::Vector;
let i32_vector: Vector<i32> = Vector::new(25, 8, 0);
let f64_vector: Vector<f64> = Vector::from_vec(i32_vector);
assert_eq!(Vector::new(25.0, 8.0, 0.0), f64_vector);

Source

pub fn into_vec<U: From<T>>(self) -> Vector

Convert a Vector, of type T to one of type U. Available only when type T has implemented Into.

§Example

use math_vector::Vector;
let i32_vector: Vector<i32> = Vector::new(25, 8, 0);
let f64_vector: Vector<f64> = i32_vector.into_vec();
assert_eq!(Vector::new(25.0, 8.0, 0.0), f64_vector);

Source §

impl<T: Default> Vector<T>

Source

pub fn default() -> Self

Default construct a Vector with all components set to 0.

§Example

use math_vector::Vector;
let v: Vector<i32> = Vector::default();
assert_eq!(Vector::new(0, 0, 0), v);

Source

pub fn abscissa(self) -> Self

Returns a vector with only the horizontal component of the current one

§Example

use math_vector::Vector;
let v = Vector::new(10, 20, 30);
assert_eq!(Vector::new(10, 0, 0), v.abscissa());

Source

pub fn ordinate(self) -> Self

Returns a vector with only the vertical component of the current one

§Example

use math_vector::Vector;
let v = Vector::new(10, 20, 30);
assert_eq!(Vector::new(0, 20, 0), v.ordinate());

Source

pub fn applicate(self) -> Self

Returns a vector with only the depth component of the current one

§Example

use math_vector::Vector;
let v = Vector::new(10, 20, 30);
assert_eq!(Vector::new(0, 0, 30), v.applicate());

Source §

impl<T> Vector<T>
where T: Mul<T, Output = T> + Copy + Clone,

Source

pub fn mul_components(self, other: Self) -> Self

Returns a new vector with components equal to each of the current vector’s components multiplied by the corresponding component of the provided vector

§Example

use math_vector::Vector;
let v1 = Vector::new(11.0, -2.5, 3.0);
let v2 = Vector::new(0.5, -2.0, 1.0);
assert_eq!(Vector::new(5.5, 5.0, 3.0), v1.mul_components(v2));

Source §

impl<T> Vector<T>
where T: Div<T, Output = T> + Copy + Clone,

Source

pub fn div_components(self, other: Self) -> Self

Returns a new vector with components equal to each of the current vector’s components divided by the corresponding component of the provided vector

§Example

use math_vector::Vector;
let v1 = Vector::new(11.0, -2.5, 3.0);
let v2 = Vector::new(0.5, -2.0, 1.0);
assert_eq!(Vector::new(22.0, 1.25, 3.0), v1.div_components(v2));

Source §

impl<T> Vector<T>
where T: Neg<Output = T> + Copy + Clone,

Source

pub fn normal(self) -> Self

Returns a vector perpendicular to the current one in the 2d plane.

§Example

use math_vector::Vector;
let v = Vector::new(21.3, -98.1, 0.0);
assert_eq!(Vector::new(98.1, 21.3, 0.0), v.normal());

Source §

impl<T, U, V> Vector<T>
where T: Mul<T, Output = U> + Copy + Clone, U: Add<U, Output = V> + Copy + Clone, V: Add<U, Output = V> + Copy + Clone,

Source

pub fn dot(v1: Self, v2: Self) -> V

Get the scalar/dot product of the two Vector.

§Example

use math_vector::Vector;
let v1 = Vector::new(1.0, 2.0, 3.0);
let v2 = Vector::new(4.0, 5.0, 6.0);
assert_eq!(32.0, Vector::dot(v1, v2));

Source

pub fn length_squared(self) -> V

Get the squared length of a Vector. This is more performant than using length() – which is only available for Vector<f32> and Vector<f64> – as it does not perform any square root operation.

§Example

 use math_vector::Vector;
 let v = Vector::new(1.0, 2.0, 3.0);
 assert_eq!(14.0, Vector::length_squared(v));

Source §

impl<T, U> Vector<T>
where T: Mul<T, Output = U> + Copy + Clone, U: Sub<U, Output = T> + Copy + Clone,

Source

pub fn cross(v1: Self, v2: Self) -> Self

Get the cross product of the two Vector.

§Example

use math_vector::Vector;
let v1 = Vector::new(1.0, 2.0, 3.0);
let v2 = Vector::new(4.0, 5.0, 6.0);
assert_eq!(Vector::new(-3.0, 6.0, -3.0), Vector::cross(v1, v2));

Source §

impl<T> Vector<T>
where T: Sub<T, Output = T> + Mul<T, Output = T> + Add<T, Output = T> + Copy + Clone,

Source

pub fn lerp(start: Self, end: Self, progress: T) -> Self

Linearly interpolates between two vectors

§Example

use math_vector::Vector;
let v1 = Vector::new(1.0, 2.0, 3.0);
let v2 = Vector::new(-1.0, -4.0, -6.0);
assert_eq!(Vector::new(-0.5, -2.5, -3.75), Vector::lerp(v1, v2, 0.75));

Source §

impl Vector<f32>

Source

pub fn is_close(self, other: Self) -> bool

If two vectors are almost equal, return true.

§Example

use math_vector::Vector;
let v = Vector::<f32>::new(-1.0, 0.0, 1.0);
let u = Vector::<f32>::new(-1.000001, 0.000001, 1.000001);
let w = Vector::<f32>::new(10.0, 0.0, 1.0);
assert_eq!(v.is_close(u), true);
assert_eq!(v.is_close(w), false);

Source

pub fn from_angle(angle: f32) -> Self

Create a unit Vector in the 2d plane from a given angle in radians.

Source

pub fn reflect(self, normal: Self) -> Self

Reflects a Vector off a surface with the given normal.

Source

pub fn length(self) -> f32

Get the length of the vector. If possible, favour length_squared() over this function, as it is more performant.

Source

pub fn set_length(self, length: f32) -> Self

Return a new vector with the same direction as the original, but with a specified length. If the vector is zero, this will return a zero vector.

Source

pub fn set_length_squared(self, length: f32) -> Self

Return a new vector with the same direction as the original, but with a specified squared length. If the vector is zero, this will return a zero vector.

Source

pub fn clamp_length(self, min: Option<f32>, max: Option<f32>) -> Self

Keep the vector’s length within the given bounds. If the vector is zero, this will return a zero vector.

Source

pub fn clamp_length_squared(self, min: Option<f32>, max: Option<f32>) -> Self

Keeps the vector’s squared length within the given bounds. If the vector is zero, this will return a zero vector.

Source

pub fn limit_length(self, max: f32) -> Self

Keeps the vector’s length below the given bound. If the vector is zero, this will return a zero vector. Same as clamp_length(None, Some(max))

Source

pub fn limit_length_squared(self, max: f32) -> Self

Keeps the vector’s squared length below the given bound. If the vector is zero, this will return a zero vector. Same as clamp_length_squared(None, Some(max))

Source

pub fn normalize(self) -> Self

Get a new vector with the same direction as this vector, but with a length of 1.0. If the the length of the vector is 0, then the original vector is returned.

Source

pub fn distance(self, other: Vector<f32>) -> f32

Get the distance between two vectors.

Source

pub fn distance_squared(self, other: Vector<f32>) -> f32

Get the squared distance between two vectors.

Source

pub fn angle(self) -> f32

Get the vector’s direction in radians in the 2d plane.

Source

pub fn angle_between(self, other: Vector<f32>) -> f32

Get the angle between two vectors in radians.

Source

pub fn rotate(self, angle: f32, axis: Vector<f32>) -> Self

Performs rotation of the vector by the given angle in radians

§Parameters

angle - The angle to rotate by in radians
axis - The axis to rotate around (note it should be a unit vector)

Source

pub fn rotate_z(self, angle: f32) -> Self

Performs rotation of the vector by the given angle in radians around the z axis

Source

pub fn rotate_y(self, angle: f32) -> Self

Performs rotation of the vector by the given angle in radians around the y axis

Source

pub fn rotate_x(self, angle: f32) -> Self

Performs rotation of the vector by the given angle in radians around the x axis

Source

pub fn is_close(self, other: Self) -> bool

If two vectors are almost equal, return true.

§Example

use math_vector::Vector;
let v = Vector::<f64>::new(-1.0, 0.0, 1.0);
let u = Vector::<f64>::new(-1.000001, 0.000001, 1.000001);
let w = Vector::<f64>::new(10.0, 0.0, 1.0);
assert_eq!(v.is_close(u), true);
assert_eq!(v.is_close(w), false);

Source

pub fn from_angle(angle: f64) -> Self

Create a unit Vector in the 2d plane from a given angle in radians.

Source

pub fn reflect(self, normal: Self) -> Self

Reflects a Vector off a surface with the given normal.

Source

pub fn length(self) -> f64

Get the length of the vector. If possible, favour length_squared() over this function, as it is more performant.

Source

pub fn set_length(self, length: f64) -> Self

Return a new vector with the same direction as the original, but with a specified length. If the vector is zero, this will return a zero vector.

Source

pub fn set_length_squared(self, length: f64) -> Self

Return a new vector with the same direction as the original, but with a specified squared length. If the vector is zero, this will return a zero vector.

Source

pub fn clamp_length(self, min: Option<f64>, max: Option<f64>) -> Self

Keep the vector’s length within the given bounds. If the vector is zero, this will return a zero vector.

Source

pub fn clamp_length_squared(self, min: Option<f64>, max: Option<f64>) -> Self

Keeps the vector’s squared length within the given bounds. If the vector is zero, this will return a zero vector.

Source

pub fn limit_length(self, max: f64) -> Self

Keeps the vector’s length below the given bound. If the vector is zero, this will return a zero vector. Same as clamp_length(None, Some(max))

Source

pub fn limit_length_squared(self, max: f64) -> Self

Keeps the vector’s squared length below the given bound. If the vector is zero, this will return a zero vector. Same as clamp_length_squared(None, Some(max))

Source

pub fn normalize(self) -> Self

Get a new vector with the same direction as this vector, but with a length of 1.0. If the the length of the vector is 0, then the original vector is returned.

Source