balanced_direction

Enum Balance

pub enum Balance {
    TopLeft,
    Top,
    TopRight,
    Left,
    Center,
    Right,
    BottomLeft,
    Bottom,
    BottomRight,
}

Expand description

Represents a position within a 3x3 grid, with each variant corresponding to a specific point.

The Balance enum is used to model a balanced ternary direction or position within a 2D grid. Each variant represents one of the nine possible positions in the grid, where the center (Balance::Center) is (0, 0) and the surrounding positions are offsets from this central point.

§Variants

TopLeft: The position at (-1, -1)
Top: The position at (0, -1)
TopRight: The position at (1, -1)
Left: The position at (-1, 0)
Center: The central position (0, 0)
Right: The position at (1, 0)
BottomLeft: The position at (-1, 1)
Bottom: The position at (0, 1)
BottomRight: The position at (1, 1)

§Examples

use balanced_direction::Balance;

let position = Balance::TopLeft;
assert_eq!(position.to_vector(), (-1, -1));

let center = Balance::Center;
assert_eq!(center.to_vector(), (0, 0));

Variants§

TopLeft

TopLeft: The position at (-1, -1)

Top

Top: The position at (0, -1)

TopRight

TopRight: The position at (1, -1)

Left

Left: The position at (-1, 0)

Center

Center: The central position (0, 0)

Right

Right: The position at (1, 0)

BottomLeft

BottomLeft: The position at (-1, 1)

Bottom

Bottom: The position at (0, 1)

BottomRight

BottomRight: The position at (1, 1)

Implementations§

impl Balance

pub fn x(self) -> i8

Returns the x-coordinate of the current Balance position in the 3x3 grid.

§Returns

An i8 value representing the x-coordinate of the position.

§Examples

use balanced_direction::Balance;

let position = Balance::Right;
assert_eq!(position.x(), 1);

let position = Balance::Center;
assert_eq!(position.x(), 0);

pub fn y(self) -> i8

Returns the y-coordinate of the current Balance position in the 3x3 grid.

§Returns

An i8 value representing the y-coordinate of the position.

§Examples

use balanced_direction::Balance;

let position = Balance::Bottom;
assert_eq!(position.y(), 1);

let position = Balance::Center;
assert_eq!(position.y(), 0);

pub fn has_top(self) -> bool

Checks if the current position has the Balance::Top variant or any variant that includes the top row in the 3x3 grid.

pub fn has_bottom(self) -> bool

Checks if the current position has the Balance::Bottom variant or any variant that includes the bottom row in the 3x3 grid.

pub fn has_left(self) -> bool

Checks if the current position has the Balance::Bottom variant or any variant that includes the bottom row in the 3x3 grid.

pub fn has_right(self) -> bool

Checks if the current position has the Balance::Left variant or any variant that includes the left column in the 3x3 grid.

pub fn is_orthogonal(self) -> bool

Checks if the current position includes the center or any direct neighbor (top, bottom, left, or right) in the 3x3 grid.

pub fn is_diagonal(self) -> bool

Checks if the current position includes the center or any indirect neighbor (corners) in the 3x3 grid.

pub fn is_edge(self) -> bool

Determines whether the current position is one of the edge positions (top, bottom, left, or right) in the 3x3 grid.

pub fn is_corner(self) -> bool

Checks if the current position is one of the corner positions (top-left, top-right, bottom-left, or bottom-right) in the 3x3 grid.

impl Balance

pub fn to_value(self) -> i8

Returns a unique integer value associated with each Balance variant.

This mapping assigns a unique value to each position in the 3x3 grid, which could be useful for serialization, indexing, or logical calculations that depend on the position.

§Returns

An i8 integer representing the Balance variant.

§Mapping

Balance::TopLeft => -4
Balance::Top => -3
Balance::TopRight => -2
Balance::Left => -1
Balance::Center => 0
Balance::Right => 1
Balance::BottomLeft => 2
Balance::Bottom => 3
Balance::BottomRight => 4

§Examples

use balanced_direction::Balance;

let position = Balance::Center;
assert_eq!(position.to_value(), 0);

let position = Balance::TopRight;
assert_eq!(position.to_value(), -2);

pub fn from_value(value: i8) -> Self

Constructs a Balance variant from a given i8 value.

This method maps an integer value to a specific Balance variant. Values outside the valid range will cause a panic.

§Arguments

value - An i8 integer value corresponding to a Balance variant.

§Returns

A Balance instance mapped from the provided integer.

§Panics

This function will panic if the input value is not in the range -4..=4.

§Examples

use balanced_direction::Balance;

let position = Balance::from_value(-4);
assert_eq!(position, Balance::TopLeft);

let position = Balance::from_value(0);
assert_eq!(position, Balance::Center);

// This will panic:
// let invalid = Balance::from_value(5);

pub fn to_scalar(self) -> i8

Calculates the scalar magnitude squared for the vector representation of the current Balance position within the grid.

The scalar magnitude squared is defined as x^2 + y^2, where (x, y) are the coordinates of the position.

§Returns

An i8 value representing the scalar magnitude squared of the position.

§Examples

use balanced_direction::Balance;

let position = Balance::TopLeft;
assert_eq!(position.to_scalar(), 2);

let center = Balance::Center;
assert_eq!(center.to_scalar(), 0);

pub fn to_magnitude(self) -> f64

Calculates the Euclidean (or absolute) magnitude of the vector representation of the current Balance position.

The magnitude is defined as the square root of the scalar magnitude squared (√(x² + y²)), where (x, y) are the coordinates of the position.

§Returns

A f64 value representing the Euclidean magnitude of the position with low precision (but fast) calculus.

§Examples

use balanced_direction::Balance;

let position = Balance::TopLeft;
assert_eq!(position.to_magnitude(), 2.0f64.sqrt());

let center = Balance::Center;
assert_eq!(center.to_magnitude(), 0.0);

pub fn to_angle(self) -> f32

Converts the current Balance position into its corresponding angle in degrees in a Cartesian coordinate system.

The angle is calculated in a counter-clockwise direction starting from the positive x-axis, with (-y, x) treated as the vector direction. The angle is returned in the range [-180.0, 180.0] degrees.

§Returns

A f32 value representing the angle in degrees.

§Examples

use balanced_direction::Balance;

let position = Balance::Top;
assert_eq!(position.to_angle(), 90.0);

pub fn from_angle(angle: f32) -> Self

Constructs a Balance enum variant based on the given angle in degrees.

The angle is treated in the Cartesian coordinate system, where:

0 degrees corresponds to Balance::Right (positive x-axis),
Positive angles proceed counterclockwise, and negative angles proceed clockwise,
The angle is normalized into the range [-180.0, 180.0] and converted into the nearest discrete position (x, y) on the 3x3 grid.

§Parameters

angle: A f32 value representing the angle in degrees.

§Returns

A Balance enum variant corresponding to the direction indicated by the angle.

§Examples

use balanced_direction::Balance;

let balance = Balance::from_angle(45.0);
assert_eq!(balance, Balance::TopRight);

let balance = Balance::from_angle(-135.0);
assert_eq!(balance, Balance::BottomLeft);

pub fn to_vector(self) -> (i8, i8)

Converts the current Balance variant into a 2D vector (i8, i8) representing its coordinates.

§Returns

A tuple (i8, i8) representing the position in the 3x3 grid.

§Examples

use balanced_direction::Balance;

let position = Balance::TopLeft;
assert_eq!(position.to_vector(), (-1, -1));

let center = Balance::Center;
assert_eq!(center.to_vector(), (0, 0));

pub fn from_vector(a: i8, b: i8) -> Self

Converts a pair of integers (a, b) into the corresponding Balance variant.

§Parameters

a: The x-coordinate in the 2D grid, expected to be in the range -1..=1.
b: The y-coordinate in the 2D grid, expected to be in the range -1..=1.

§Returns

The Balance variant that corresponds to the provided (a, b) coordinates.

§Panics

Panics if the provided (a, b) pair does not correspond to a valid Balance variant.

§Examples

use balanced_direction::Balance;

let balance = Balance::from_vector(-1, -1);
assert_eq!(balance, Balance::TopLeft);

let balance = Balance::from_vector(0, 1);
assert_eq!(balance, Balance::Bottom);

impl Balance

pub fn up(self) -> Self

Moves the current position upwards in the 3x3 grid while staying within bounds.

§Returns

The Balance variant representing the position directly above the current one. If the current position is at the top edge, the result will stay at the edge.

§Examples

use balanced_direction::Balance;

let balance = Balance::Center;
assert_eq!(balance.up(), Balance::Top);

let balance = Balance::Top;
assert_eq!(balance.up(), Balance::Top);

pub fn down(self) -> Self

Moves the current position downwards in the 3x3 grid while staying within bounds.

§Returns

The Balance variant representing the position directly below the current one. If the current position is at the bottom edge, the result will stay at the edge.

§Examples

use balanced_direction::Balance;

let balance = Balance::Center;
assert_eq!(balance.down(), Balance::Bottom);

let balance = Balance::Bottom;
assert_eq!(balance.down(), Balance::Bottom);

pub fn left(self) -> Self

Moves the current position to the left in the 3x3 grid while staying within bounds.

§Returns

The Balance variant representing the position directly to the left of the current one. If the current position is at the left edge, the result will stay at the edge.

§Examples

use balanced_direction::Balance;

let balance = Balance::Center;
assert_eq!(balance.left(), Balance::Left);

let balance = Balance::Left;
assert_eq!(balance.left(), Balance::Left);

pub fn right(self) -> Self

Moves the current position to the right in the 3x3 grid while staying within bounds.

§Returns

The Balance variant representing the position directly to the right of the current one. If the current position is at the right edge, the result will stay at the edge.

§Examples

use balanced_direction::Balance;

let balance = Balance::Center;
assert_eq!(balance.right(), Balance::Right);

let balance = Balance::Right;
assert_eq!(balance.right(), Balance::Right);

pub fn up_wrap(self) -> Self

Moves the position upwards in the 3x3 grid with wrapping behavior.

pub fn down_wrap(self) -> Self

Moves the position downwards in the 3x3 grid with wrapping behavior.

pub fn left_wrap(self) -> Self

Moves the position leftwards in the 3x3 grid with wrapping behavior.

pub fn right_wrap(self) -> Self

Moves the position rightwards in the 3x3 grid with wrapping behavior.

pub fn flip_h(self) -> Self

Flips the current position horizontally in the 3x3 grid.

§Returns

The Balance variant that is mirrored horizontally across the vertical axis. For example, flipping Balance::Left results in Balance::Right, and vice-versa. Positions on the vertical axis (like Balance::Center or Balance::Top) remain unchanged.

§Examples

use balanced_direction::Balance;

let balance = Balance::Left;
assert_eq!(balance.flip_h(), Balance::Right);

let balance = Balance::Center;
assert_eq!(balance.flip_h(), Balance::Center);

pub fn flip_v(self) -> Self

Flips the current position vertically in the 3x3 grid.

§Returns

The Balance variant that is mirrored vertically across the horizontal axis. For example, flipping Balance::Top results in Balance::Bottom, and vice-versa. Positions on the horizontal axis (like Balance::Center or Balance::Left) remain unchanged.

§Examples

use balanced_direction::Balance;

let balance = Balance::Top;
assert_eq!(balance.flip_v(), Balance::Bottom);

let balance = Balance::Center;
assert_eq!(balance.flip_v(), Balance::Center);

pub fn rotate_left(self) -> Self

Rotates the current position 90 degrees counterclockwise in the 3x3 grid.

§Returns

The Balance variant representing the position after a 90-degree counterclockwise rotation around the center. For example, rotating Balance::Right counterclockwise will result in Balance::Top, and Balance::Top will result in Balance::Left. The center position (Balance::Center) remains unchanged.

§Examples

use balanced_direction::Balance;

let balance = Balance::Right;
assert_eq!(balance.rotate_left(), Balance::Top);

let balance = Balance::Center;
assert_eq!(balance.rotate_left(), Balance::Center);

let balance = Balance::Top;
assert_eq!(balance.rotate_left(), Balance::Left);

pub fn rotate_right(self) -> Self

Rotates the current position 90 degrees clockwise in the 3x3 grid.

§Returns

The Balance variant representing the position after a 90-degree clockwise rotation around the center. For example, rotating Balance::Top clockwise results in Balance::Right, and Balance::Right will result in Balance::Bottom. The center position (Balance::Center) remains unchanged.

§Examples

use balanced_direction::Balance;

let balance = Balance::Top;
assert_eq!(balance.rotate_right(), Balance::Right);

let balance = Balance::Center;
assert_eq!(balance.rotate_right(), Balance::Center);

let balance = Balance::Right;
assert_eq!(balance.rotate_right(), Balance::Bottom);

pub fn center_h(self) -> Self

Centers the current position horizontally in the 3x3 grid by setting the x-coordinate to 0.

§Returns

A Balance variant where the x-coordinate is always 0, keeping the same y-coordinate. This effectively moves the current position to the vertical axis of the grid.

§Examples

use balanced_direction::Balance;

let balance = Balance::Left;
assert_eq!(balance.center_h(), Balance::Center);

let balance = Balance::BottomLeft;
assert_eq!(balance.center_h(), Balance::Bottom);

pub fn center_v(self) -> Self

Centers the current position vertically in the 3x3 grid by setting the y-coordinate to 0.

§Returns

A Balance variant where the y-coordinate is always 0, keeping the same x-coordinate. This effectively moves the current position to the horizontal axis of the grid.

§Examples

use balanced_direction::Balance;

let balance = Balance::Top;
assert_eq!(balance.center_v(), Balance::Center);

let balance = Balance::TopRight;
assert_eq!(balance.center_v(), Balance::Right);

impl Balance

pub fn to_ternary_pair(self) -> (Digit, Digit)

Converts the Balance position into a pair of ternary digits.

§Returns

A tuple containing two Digit values. The first element represents the x-coordinate and the second represents the y-coordinate of the Balance position in the ternary numeral system.

The Digit values can range from Neg (-1), Zero (0), to Pos (1), matching the 3x3 balanced grid’s coordinate representation.

§Examples

use balanced_direction::Balance;
use balanced_ternary::Digit;

let balance = Balance::Top;
assert_eq!(balance.to_ternary_pair(), (Digit::Zero, Digit::Neg));

let balance = Balance::Right;
assert_eq!(balance.to_ternary_pair(), (Digit::Pos, Digit::Zero));

pub fn from_ternary_pair(a: Digit, b: Digit) -> Self

Creates a Balance instance from a pair of ternary digits.

§Arguments

a - A Digit representing the x-coordinate in the ternary numeral system.
b - A Digit representing the y-coordinate in the ternary numeral system.

§Returns

A new Balance instance corresponding to the provided ternary coordinates.

The values of a and b should be valid ternary digits within the range of:

Neg (-1), Zero (0), and Pos (1).

This allows for mapping coordinates within the 3x3 grid system used by the Balance enum, ensuring that any valid pair of ternary digits maps directly to a specific Balance position.

§Examples

use balanced_direction::Balance;
use balanced_ternary::Digit;

let balance = Balance::from_ternary_pair(Digit::Zero, Digit::Neg);
assert_eq!(balance, Balance::Top);

let balance = Balance::from_ternary_pair(Digit::Pos, Digit::Zero);
assert_eq!(balance, Balance::Right);

Trait Implementations§

impl Add for Balance

type Output = Balance

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation. Read more

impl BitAnd for Balance

type Output = Balance

The resulting type after applying the & operator.

fn bitand(self, rhs: Self) -> Self::Output

Performs the & operation. Read more

impl BitOr for Balance

type Output = Balance

The resulting type after applying the | operator.

fn bitor(self, rhs: Self) -> Self::Output

Performs the | operation. Read more

impl BitXor for Balance

type Output = Balance

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: Self) -> Self::Output

Performs the ^ operation. Read more

impl Clone for Balance

fn clone(&self) -> Balance

Returns a copy of the value. Read more

1.0.0 · Source§

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

Performs copy-assignment from source. Read more

impl Debug for Balance

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

Formats the value using the given formatter. Read more

impl Hash for Balance

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

Feeds this value into the given Hasher. Read more

1.3.0 · Source§

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

Feeds a slice of this type into the given Hasher. Read more

impl Mul for Balance

type Output = Balance

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation. Read more

impl Neg for Balance

type Output = Balance

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation. Read more

impl Not for Balance

type Output = Balance

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation. Read more

impl PartialEq for Balance

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

Tests for self and other values to be equal, and is used by ==.

1.0.0 · Source§

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Sub for Balance

type Output = Balance

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation. Read more

impl Copy for Balance

impl Eq for Balance

impl StructuralPartialEq for Balance

Auto Trait Implementations§

impl Freeze for Balance

impl RefUnwindSafe for Balance

impl Send for Balance

impl Sync for Balance

impl Unpin for Balance

impl UnwindSafe for Balance

Blanket Implementations§

impl<T> Any for T
where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T
where T: ?Sized,

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T
where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

impl<T> CloneToUninit for T
where T: Clone,

unsafe fn clone_to_uninit(&self, dst: *mut u8)

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

Performs copy-assignment from self to dst. Read more

impl<T> From<T> for T

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into<U> for T
where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

impl<T> ToOwned for T
where T: Clone,

type Owned = T

The resulting type after obtaining ownership.

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more

impl<T, U> TryFrom<U> for T
where U: Into<T>,

type Error = Infallible

The type returned in the event of a conversion error.

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.