[−][src]Module chickenwire::coordinate

Hexagonal coordinate systems.

Coordinate Systems

Chickenwire supports the four coorinate representations presented in The Guide: Cube, Axial, Offset, and Double. The CoordSys enum holds valueless labels for each, and each has a struct with appropriately labeled values.

Multi-Coordinates

In addition to the four coordinates' individual structs, Chickenwire defines a MultiCoord. This effectively fulfills the role of a union type, with the added benefit of tracking and maintaining its own typing.

Creating Coordinates

Axial and Offset coordinates can be instantiated normally:

use chickenwire::coordinate::axial::Axial;
use chickenwire::coordinate::offset::Offset;

let axial = Axial { q: 0, r: 1 };
let offset = Offset { col: 2, row: 3 };

Additionally, each coordinate struct has methods for instantiation from tuple or i32 values:

use chickenwire::coordinate::{Axial, Cube, Offset};

// Use _::from() for tuples
let cube_from_tup = Cube::from((1, 2, -3));
let offset_from_tup = Offset::from((-1, 0));

// Use _::from_coords() or _::force_from_coords() for i32s
let cube_from_int = Cube::force_from_coords(1, 2, -3);
let offset_from_int = Offset::from_coords(-1, 0);

// The result of the two calls is equivalent
assert_eq!(cube_from_tup, cube_from_int);
assert_eq!(offset_from_tup, offset_from_int);

Cube and Double coordinates have enforced constraints. If these constraints aren't met during instantiation, the program will panic. See the Cube and Double documentation for more information.

Modifying Coordinates

Use the set_coords method to update a Cube or Double. Otherwise, coordinate structs should be manipulated normally via their public fields.

Coordinate Conversion

The From and Into traits are implemented between Axial and Cube, and for between all coordinates and MultiCoords. For Offset and Double coordinates, conversion to a different system requires additional knowledge about the grid's state. Namely, whether the hexes have a "flat" or "sharp" orientation and if the offset patterning is "even" or "odd." Conversion methods for each circumstance are documented in the coordinate system sub-modules. See either the chickenwire::hexgrid documentation or The Guide for explantations of flat/sharp orientation and even/odd offsetting.

Arithmetic

The Add<Self>, Sub<Self>, and Mul<i32> traits are implemented for Axial, Cube, and Double. These operations treat the coordinates as vectors:

use chickenwire::coordinate::{Axial, Cube, Double};

// Vector addition
assert_eq!(
    Axial::from_coords(2, 2) + Axial::from_coords(5, -11),
    Axial::from_coords(7, -9)
);

// Vector subtraction
assert_eq!(
    Double::force_from_coords(4, -2) - Double::force_from_coords(-3, 1),
    Double::force_from_coords(7, -3)
);

// Scalar multiplication
assert_eq!(
    Axial { q: 1, r: -3 } * 2i32,
    Axial { q: 2, r: -6 }
);

On Neighbors

The exact rule for the ordering of neighbors is that the first position which remains in the same cardinal wedge always receives the zero index, and then indexing procedes clockwise for the remaining neighbors. In practice, this means that the Northeastern neighbor receives the zero index, save for the diagonal case, where the Southeastern neighbor is the recipient.

Re-exports

pub use axial::Axial;

pub use cube::Cube;

pub use double::Double;

pub use offset::Offset;

Modules

axial	Axial Coordinates
cube	Cube Coordinates
double	Double Coordinates
offset	Offset Coordinates