Crate vector2d

vector2d

A simple and convenient 2D vector library without excessive use of external dependencies. If other vector crates are swiss-army knives, vector2d is a spoon; safe, intuitive, and convenient. As an added bonus, you won't run into any excursions with the law using this library thanks to the awfully permissive Unlicense.

The only type in this crate is Vector2D, which is highly generic; shifting functionality depending upon the traits implemented by its internal components' types.

Example

use vector2d::Vector2D;

fn main() {
    // Vectors have fields X and Y, these can be of any type
    let v1: Vector2D<i32> = Vector2D { x: 10, y: 5 };

    // Alternatively you can use new(..) to condense instantiation
    let v2: Vector2D<f64> = Vector2D::new(13.0, 11.5);

    // There are two ways to cast between Vector2Ds, depending on the source
    // and target types.
    //
    // If the target type has a implementation of From<SourceType>, then you
    // can either use source.into_vec2d() or Vector2D::from_vec2d(source).
    assert_eq!(Vector2D::new(10.0, 5.0), v1.into_vec2d());
    assert_eq!(Vector2D::new(10.0, 5.0), Vector2D::from_vec2d(v1));

    // If there is no From or Into implementation, then you're out of luck
    // unless you are using specific primitives, such as i32 and f64. In
    // this case you can use specialised functions, as shown below:
    assert_eq!(Vector2D::new(13, 11), v2.as_i32s());

    // The full list of interoperable primitives is as follows:
    //   - i32, i64, isize
    //   - u32, u64, usize
    //   - f32, f64

    // As primitives generally implement From/Into for lossless casts,
    // an as_Ts() function is not available for those types, and
    // from(..)/into() should be favoured.
    //
    // Casts between signed and unsigned primitives will perform bounds
    // checking, so casting the vector (-10.0, 2.0) to a Vector2D<u32> will
    // result in the vector (0, 2).

    // For types with an Add and Mul implementation, the functions dot() and
    // length_squared() are available. For access to length(), normalise(),
    // or angle() however, you must be using either Vector2D<f32> or
    // Vector2D<f64>.
    let _v1_len_sq = v1.length_squared();
    let v2_len = v2.length();
    let v2_dir = v2.normalise();

    // Assuming the operator traits are implemented for the types involved,
    // you can add and subtract Vector2Ds from one-another, as well as
    // multiply and divide them with scalar values.
    assert_eq!(v2, v2_dir * v2_len);
    assert_eq!(Vector2D::new(23.0, 16.5),  v2 + v1.into_vec2d()) ;

    // If you feel the need to multiply or divide individual components of
    // vectors with the same type, you can use mul_components(...) or
    // div_components(...) provided that their types can be multiplied or
    // divided.

    // For any Vector2D<T>, there is an implementation of
    // From<(T, T)> and From<[T; 2]>
    let v4: Vector2D<f64> = Vector2D::new(1.5, 2.3);
    assert_eq!(v4, (1.5, 2.3).into());
    assert_eq!(v4, [1.5, 2.3].into());

    // Additionally, there is an Into<(T, T)> implementation for any types
    // that the vector components have their own Into implementations for
    assert_eq!((1.5, 2.3), v4.into());

    // If you want the normal of a vector you can just call normal()
    let v5 = Vector2D::new(-10.0, -2.3);
    assert_eq!(Vector2D::new(2.3, -10.0), v5.normal());

    // You can get a vector consisting of only the horizontal or vertical
    // component of a vector by calling horizontal() or vertical()
    // respectively
    let v6 = Vector2D::new(12.3, 83.2);
    assert_eq!(Vector2D::new(12.3, 0.0), v6.horizontal());
    assert_eq!(Vector2D::new(0.0, 83.2), v6.vertical());
}

Structs

Vector2D

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