Struct chickenwire::coordinate::cube::Cube

pub struct Cube { /* fields omitted */ }

Cube coordinates operate on three planes, treating hexes as cross-sections of a cube sliced along the diagonal.

Cube coordinates possess the constraint that, for cube coorinate (x, y, z), x + y + z == 0. This is automatically enforced in methods for Cube and associated functions. As part of this enforcement, Cube is opaque, requiring method or function calls for instantiation and modification.

Methods

impl Cube

pub const ORIGIN: Cube

Cube coordinate origin of (0, 0, 0).

pub fn from_coords(x: i32, y: i32, z: i32) -> CoordResult<Cube>

Attempts to create a Cube from three i32 values. If these values obey the Cube constraint, x + y + z == 0, then returns that Cube in an Ok. Otherwise, returns an Err.

Examples

use chickenwire::coordinate::cube::Cube;

let cube_1 = Cube::from_coords(1, 3, -4);
let cube_2 = Cube::from_coords(0, 0, 1);

assert!(cube_1.is_ok());

assert_eq!(cube_1.unwrap().x(), 1);
assert_eq!(cube_1.unwrap().y(), 3);
assert_eq!(cube_1.unwrap().z(), -4);

assert!(cube_2.is_err());

pub fn force_from_coords(x: i32, y: i32, z: i32) -> Self

Creates a Cube from three i32 values.

Panics

Panics if the given i32 values fail to obey the constraint x + y + z == 0.

Examples

use chickenwire::coordinate::Cube;

let cube_1 = Cube::force_from_coords(1, 3, -4);

assert_eq!(cube_1.x(), 1);
assert_eq!(cube_1.y(), 3);
assert_eq!(cube_1.z(), -4);

pub fn from_tuple((x, y, z): (i32, i32, i32)) -> CoordResult<Cube>

Attempts to create a Cube from a tuple of three i32 values. If these values obey the Cube constraint, x + y + z == 0, then returns that Cube in an Ok. Otherwise, returns an Err.

Examples

use chickenwire::coordinate::Cube;

let cube_1 = Cube::from_tuple((1, 3, -4));
let cube_2 = Cube::from_tuple((0, 0, 1));

assert!(cube_1.is_ok());

assert_eq!(cube_1.unwrap().x(), 1);
assert_eq!(cube_1.unwrap().y(), 3);
assert_eq!(cube_1.unwrap().z(), -4);

assert!(cube_2.is_err());

pub fn to_tuple(self) -> (i32, i32, i32)

pub fn x(self) -> i32

pub fn y(self) -> i32

pub fn z(self) -> i32

pub fn neighbor(self, index: usize) -> Self

Calculates the requested neighbor. An index of 0 returns the Northeastern neighbor, and increases clockwise. Indices wrap around.

Examples

use chickenwire::coordinate::cube::Cube;

assert_eq!(
    Cube::force_from_coords(1, 0, -1),
    Cube::ORIGIN.neighbor(0)
);
assert_eq!(
    Cube::force_from_coords(1, -1, 0),
    Cube::ORIGIN.neighbor(1)
);
assert_eq!(
    Cube::force_from_coords(0, 1, -1),
    Cube::ORIGIN.neighbor(5)
);

assert_eq!(Cube::ORIGIN.neighbor(0), Cube::ORIGIN.neighbor(6));
assert_eq!(Cube::ORIGIN.neighbor(1), Cube::ORIGIN.neighbor(7));

pub fn neighbors(self) -> Vec<Self>

Produces a Vec<Cube> ordered beginning with the Northeastern neighbor of the calling instance and proceeding clockwise.

The Northeastern coordinate was chosen as the anchor because it is the first diagonal (when proceeding clockwise) which visually remains in the same compass direction from the calling instance. This logic is consistent throughout the module.

Examples

use chickenwire::coordinate::cube::Cube;

let origin_neighbors = vec![
    Cube::force_from_coords(1, 0, -1),
    Cube::force_from_coords(1, -1, 0),
    Cube::force_from_coords(0, -1, 1),
    Cube::force_from_coords(-1, 0, 1),
    Cube::force_from_coords(-1, 1, 0),
    Cube::force_from_coords(0, 1, -1),
];

assert_eq!(origin_neighbors, Cube::ORIGIN.neighbors());

let offset_neighbors = vec![
    Cube::force_from_coords(2, 2, -4),
    Cube::force_from_coords(2, 1, -3),
    Cube::force_from_coords(1, 1, -2),
    Cube::force_from_coords(0, 2, -2),
    Cube::force_from_coords(0, 3, -3),
    Cube::force_from_coords(1, 3, -4),
];

assert_eq!(
    offset_neighbors,
    Cube::force_from_coords(1, 2, -3).neighbors()
);

pub fn diagonal(self, index: usize) -> Self

Calculates the requested diagonal. An index of 0 returns the Southeastern diagonal, and increases clockwise. Indices wrap around.

Examples

use chickenwire::coordinate::cube::Cube;

assert_eq!(
    Cube::force_from_coords(1, -2, 1),
    Cube::ORIGIN.diagonal(0)
);
assert_eq!(
    Cube::force_from_coords(-1, -1, 2),
    Cube::ORIGIN.diagonal(1)
);
assert_eq!(
    Cube::force_from_coords(2, -1, -1),
    Cube::ORIGIN.diagonal(5)
);

assert_eq!(Cube::ORIGIN.diagonal(0), Cube::ORIGIN.diagonal(6));
assert_eq!(Cube::ORIGIN.diagonal(1), Cube::ORIGIN.diagonal(7));

pub fn diagonals(self) -> Vec<Self>

Produces a Vec<Cube> ordered beginning with the Southeastern diagonal of the calling instance and proceeding clockwise.

The Southeastern coordinate was chosen as the anchor because it is the first diagonal (when proceeding clockwise) which visually remains in the same compass direction from the calling instance. This logic is consistent throughout the module.

Examples

use chickenwire::coordinate::cube::Cube;

let origin_diagonals = vec![
    Cube::force_from_coords(1, -2, 1),
    Cube::force_from_coords(-1, -1, 2),
    Cube::force_from_coords(-2, 1, 1),
    Cube::force_from_coords(-1, 2, -1),
    Cube::force_from_coords(1, 1, -2),
    Cube::force_from_coords(2, -1, -1),
];

assert_eq!(origin_diagonals, Cube::ORIGIN.diagonals());

let offset_diagonals = vec![
    Cube::force_from_coords(2, 0, -2),
    Cube::force_from_coords(0, 1, -1),
    Cube::force_from_coords(-1, 3, -2),
    Cube::force_from_coords(0, 4, -4),
    Cube::force_from_coords(2, 3, -5),
    Cube::force_from_coords(3, 1, -4),
];

assert_eq!(
    offset_diagonals,
    Cube::force_from_coords(1, 2, -3).diagonals()
);

pub fn dist(self, other: Self) -> i32

Determines the distance between two cube coordinates.

Examples

use chickenwire::coordinate::cube::Cube;

let origin = Cube::ORIGIN;
let coord_1 = Cube::force_from_coords(1, 2, -3);
let coord_2 = Cube::force_from_coords(-8, 6, 2);

assert_eq!(origin.dist(coord_1), 3);
assert_eq!(coord_1.dist(origin), 3);
assert_eq!(coord_1.dist(coord_1), 0);
assert_eq!(coord_2.dist(coord_1), 9);

pub fn rotate_cw(self, point: Self, num_turns: u32) -> Self

Rotate a point n times clockwise about the calling instance.

pub fn rotate_cc(self, point: Self, num_turns: u32) -> Self

Rotate a point n times counter-clockwise about the calling instance.

pub fn ring(self, radius: u32) -> Vec<Self>

Return the coordinates comprising a ring with a given radisu about the calling instance.

pub fn spiral(self, radius: u32) -> Vec<Self>

Return all coordinates up to and within a ring with the given radius about the calling instance. Spirals outwards, so the first element of the returned vector is the calling instance.

Trait Implementations

impl From<Cube> for Axial

Creates an Axial from a Cube.

Examples

use chickenwire::coordinate::axial::Axial;
use chickenwire::coordinate::cube::Cube;

let cube = Cube::force_from_coords(1, 2, -3);

assert_eq!(
    Axial::from(cube),
    Axial { q: 1, r: -3 }
);
assert_eq!(
    Axial::from(Cube::ORIGIN),
    Axial::ORIGIN
);

fn from(coord: Cube) -> Self

Performs the conversion.

impl From<(i32, i32, i32)> for Cube

Creates a Cube from an (i32, i32, i32).

The produced Cube, (x, y, z), must be constrained such that x + y + z == 0.

Panics

Panics upon receiving i32 values which violate the constraint x + y + z == 0 for Cube (x, y, z).

fn from((x, y, z): (i32, i32, i32)) -> Self

Performs the conversion.

impl From<Axial> for Cube

For axial coordinate (q, r), cube coordinate (x, y, z) is calculated by solving for y based upon the constraint x + y + z == 0, where x == q and z == r.

Examples

use chickenwire::coordinate::axial::Axial;
use chickenwire::coordinate::cube::Cube;

let axial = Axial::from_coords(1, 2);

assert_eq!(Cube::from(Axial::ORIGIN), Cube::ORIGIN);
assert_eq!(Cube::from(axial), Cube::force_from_coords(1, -3, 2));

fn from(coord: Axial) -> Self

Performs the conversion.

impl From<MultiCoord> for Cube

fn from(coord: MultiCoord) -> Self

Performs the conversion.

impl From<Cube> for CoordSys

Creates a CoordSys::Cube from a Cube.

fn from(_: Cube) -> Self

Performs the conversion.

impl From<Cube> for MultiCoord

Creates a MultiCoord from a Cube.

fn from(coord: Cube) -> Self

Performs the conversion.

impl Ord for Cube

fn cmp(&self, other: &Cube) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl PartialOrd<Cube> for Cube

fn partial_cmp(&self, other: &Cube) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Cube) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Cube) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Cube) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Cube) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialEq<Cube> for Cube

fn eq(&self, other: &Cube) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Cube) -> bool

This method tests for !=.

impl Default for Cube

fn default() -> Cube

Returns the "default value" for a type.

impl Clone for Cube

fn clone(&self) -> Cube

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Eq for Cube

impl Copy for Cube

impl Debug for Cube

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Add<Cube> for Cube

Cube coordinates are added together like vectors.

Examples

use chickenwire::coordinate::Cube;

let coord_1 = Cube::force_from_coords(1, 2, -3);
let coord_2 = Cube::force_from_coords(-5, -7, 12);

assert_eq!(coord_1 + coord_2, Cube::force_from_coords(-4, -5, 9));
assert_eq!(coord_2 + coord_1, Cube::force_from_coords(-4, -5, 9));

type Output = Self

The resulting type after applying the + operator.

fn add(self, other: Self) -> Self

Performs the + operation.

impl Sub<Cube> for Cube

Cube coordinates are subtracted from each other like vectors.

Examples

use chickenwire::coordinate::cube::Cube;

let coord_1 = Cube::force_from_coords(1, 2, -3);
let coord_2 = Cube::force_from_coords(5, 7, -12);

assert_eq!(coord_1 - coord_2, Cube::force_from_coords(-4, -5, 9));
assert_eq!(coord_2 - coord_1, Cube::force_from_coords(4, 5, -9));

type Output = Self

The resulting type after applying the - operator.

fn sub(self, other: Self) -> Self

Performs the - operation.

impl Mul<i32> for Cube

Cube coordinates can be multiplied by i32 scalars, like vectors.

Examples

use chickenwire::coordinate::cube::Cube;

let coord = Cube::force_from_coords(1, 2, -3);

assert_eq!(-1 * coord, Cube::force_from_coords(-1, -2, 3));
assert_eq!(0 * coord, Cube::ORIGIN);
assert_eq!(coord * 2, Cube::force_from_coords(2, 4, -6));

type Output = Self

The resulting type after applying the * operator.

fn mul(self, n: i32) -> Self

Performs the * operation.

impl Mul<Cube> for i32

type Output = Cube

The resulting type after applying the * operator.

fn mul(self, coord: Cube) -> Cube

Performs the * operation.

impl Hash for Cube

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].