Enum Balance

Source

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§

Source §

impl Balance

Source

pub const 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);

Source

pub const 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);

Source

pub const fn has_top(self) -> bool

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

Source

pub const fn has_bottom(self) -> bool

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

Source

pub const fn has_left(self) -> bool

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

Source

pub const fn has_right(self) -> bool

(spatial) Checks if the current position has the Balance::Right variant or any variant that includes the right column in the 3x3 grid.

Source

pub const fn is_orthogonal(self) -> bool

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

Source

pub const fn is_diagonal(self) -> bool

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

Source

pub const fn is_edge(self) -> bool

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

Source

pub const fn is_corner(self) -> bool

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

Source

pub const fn to_symbol(self) -> &'static str

Converts the current Balance position into a symbol representation.

§Returns

A &'static str that visually represents the position using an emoji. Each position in the 3x3 grid is mapped to a unique symbol:

TopLeft: “↖️”
Top: “⬆️”
TopRight: “↗️”
Left: “⬅️”
Center: “⏺️”
Right: “➡️”
BottomLeft: “↙️”
Bottom: “⬇️”
BottomRight: “↘️”

§Examples

use balanced_direction::Balance;

let position = Balance::Top;
assert_eq!(position.to_symbol(), "⬆️");

let position = Balance::Center;
assert_eq!(position.to_symbol(), "⏺️");

Source §

pub const 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);

Source

pub const 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);

Source

pub const 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);

Source

pub const 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);

Source

pub const fn to_angle(self) -> f64

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

The angle is returned in the range [-180.0, 180.0] degrees.

§Returns

A f64 value representing the angle in degrees.

§Examples

use balanced_direction::Balance;

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

Source

pub const fn from_angle(angle: f64) -> Self

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

§Parameters

angle: A f64 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);

let balance = Balance::from_angle(270.0);
assert_eq!(balance, Balance::Bottom);

Source

pub const 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));

Source

pub const 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);

Source §

impl Balance

Source

pub const 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);

Source

pub const 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);

Source

pub const 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);

Source

pub const 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);

Source

pub const fn up_wrap(self) -> Self

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

Source

pub const fn down_wrap(self) -> Self

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

Source

pub const fn left_wrap(self) -> Self

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

Source

pub const fn right_wrap(self) -> Self

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

Source

pub const 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);

Source

pub const 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);

Source

pub const 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);

Source

pub const 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);

Source

pub const 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);

Source

pub const 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);

Source §

impl Balance

Source

pub const 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));

Source

pub const 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);

Source

pub const fn is_true(self) -> bool

(logic) Checks if the current logical state is Balance::BottomRight (True, True).

Source

pub const fn has_true(self) -> bool

(logic) Checks if the current logical state includes Balance::Bottom or Balance::Right.

Balance::TopRight (True, False)
Balance::Right (True, Unknown)
Balance::BottomLeft (False, True)
Balance::Bottom (Unknown, True)
Balance::BottomRight (True, True)

Source

pub const fn is_contradictory(self) -> bool

(logic) Checks if the current logical state is contradictory, representing opposing truths (TopRight or BottomLeft).

Balance::TopRight (True, False)
Balance::BottomLeft (False, True)

Source

pub const fn has_unknown(self) -> bool

(logic) Checks whether the current logical state has no certain value but is not contradictory.

Balance::Top (Unknown, False)
Balance::Left (False, Unknown)
Balance::Center (Unknown, Unknown)
Balance::Right (True, Unknown)
Balance::Bottom (Unknown, True)

Source

pub const fn is_uncertain(self) -> bool

(logic) Checks whether the current logical state is uncertain in terms of logical balance.

Equals:

is_contradictory() || has_unknown(),
or !is_certain().

These cases return true:

Balance::TopRight (True, False)
Balance::BottomLeft (False, True)
Balance::Top (Unknown, False)
Balance::Left (False, Unknown)
Balance::Center (Unknown, Unknown)
Balance::Right (True, Unknown)
Balance::Bottom (Unknown, True)

Source

pub const fn is_certain(self) -> bool

(logic) Returns whether the current logical state represents a certain state in logical balance (one of is_true() or is_false() is true).

Balance::TopLeft (False, False)
Balance::BottomRight (True, True)

Source

pub const fn has_false(self) -> bool

(logic) Determines whether the current logical state includes the Balance::Top or Balance::Left variant.

Balance::TopLeft (False, False)
Balance::Top (Unknown, False)
Balance::TopRight (True, False)
Balance::Left (False, Unknown)
Balance::BottomLeft (False, True)

Source

pub const fn is_false(self) -> bool

(logic) Checks if the current logical state is Balance::TopLeft (False, False).

Source

pub const fn to_bool(self) -> bool

Converts the Balance logical state into a boolean representation.

§Returns

A bool value that represents the certainty of the Balance logical state.

Returns true if the position is logically true (e.g., Balance::BottomRight).
Returns false if the position is logically false (e.g., Balance::TopLeft).

§Panics

Panics if the Balance logical state is uncertain. Uncertain states include cases where the position cannot be determined or does not logically map to true or false.

Use Balance::is_certain to check certainty of the Balance logical state.

§Examples

use balanced_direction::Balance;

let balance = Balance::BottomRight;
assert_eq!(balance.to_bool(), true);

let balance = Balance::TopLeft;
assert_eq!(balance.to_bool(), false);

let balance = Balance::Center;
// This will panic because `Balance::Center` is an uncertain logical state.
// balance.to_bool();

Source

pub const fn x_to_bool(self) -> bool

Converts the x-coordinate of the Balance position into a boolean representation.

§Returns

A bool value representing the logical state of the x-coordinate:

Returns true if the x-coordinate is logically true (1).
Returns false if the x-coordinate is logically false (-1).

§Panics

Panics if the x-coordinate is unknown (i.e., 0), as it cannot be converted into a boolean value.

§Examples

use balanced_direction::Balance;

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

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

let balance = Balance::Center;
// This will panic because the x-coordinate is unknown.
// balance.x_to_bool();

Source

pub const fn y_to_bool(self) -> bool

Converts the y-coordinate of the Balance position into a boolean representation.

§Returns

A bool value representing the logical state of the y-coordinate:

Returns true if the y-coordinate is logically true (1).
Returns false if the y-coordinate is logically false (-1).

§Panics

Panics if the y-coordinate is unknown (i.e., 0), as it cannot be converted into a boolean value.

§Examples

use balanced_direction::Balance;

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

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

let balance = Balance::Center;
// This will panic because the y-coordinate is unknown.
// balance.y_to_bool();

Source

pub const fn possibly(self) -> Self

Applies Digit::possibly on x and y.

Source

pub const fn necessary(self) -> Self

Applies Digit::necessary on x and y.

Source

pub const fn contingently(self) -> Self

Applies Digit::contingently on x and y.

Source

pub const fn absolute_positive(self) -> Self

Applies Digit::absolute_positive on x and y.

Source

pub const fn positive(self) -> Self

Applies Digit::positive on x and y.

Source

pub const fn not_negative(self) -> Self

Applies Digit::not_negative on x and y.

Source

pub const fn not_positive(self) -> Self

Applies Digit::not_positive on x and y.

Source

pub const fn negative(self) -> Self

Applies Digit::negative on x and y.

Source

pub const fn absolute_negative(self) -> Self

Applies Digit::absolute_negative on x and y.

Source

pub const fn ht_not(self) -> Self

Applies Digit::ht_not on x and y.

Source

pub const fn post(self) -> Self

Applies Digit::post on x and y.

Source

pub const fn pre(self) -> Self

Applies Digit::pre on x and y.

Source

pub const fn k3_imply(self, other: Self) -> Self

Applies Digit::k3_imply on x and y.

Source

pub const fn k3_equiv(self, other: Self) -> Self

Applies Digit::k3_equiv on x and y.

Equivalent to self * other.

Source

pub const fn ht_imply(self, other: Self) -> Self

Applies Digit::ht_imply on x and y.

Source

pub fn apply<FX, FY>(self, op_x: FX, op_y: FY) -> Self
where FX: Fn(Digit) -> Digit, FY: Fn(Digit) -> Digit,

Applies a transformation function x and another on y coordinates.

This function allows you to provide two different transformation functions, one for x (op_x) and another for y (op_y). These functions process the coordinates independently, and the resulting transformed x and y coordinates are combined into a new Balance.

§Parameters

op_x: A function that transforms the x coordinate.
op_y: A function that transforms the y coordinate.

§Returns

A new Balance object with the transformed x and y coordinates.

§Examples

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

let balance = Balance::Center;
let transformed = balance.apply(Digit::not_negative, Digit::not_positive);
assert_eq!(transformed, Balance::TopRight);

Source

pub fn apply_with<FX, FY>(self, op_x: FX, op_y: FY, other: Self) -> Self
where FX: Fn(Digit, Digit) -> Digit, FY: Fn(Digit, Digit) -> Digit,

Applies two transformation functions - one for x and one for y - on a Balance instance along with another Balance.

This function takes two coordinate transformation functions (op_x and op_y) as well as another Balance instance (other). It applies op_x to the x coordinates of both balances, and op_y to the y coordinates of both balances, combining the results into a new Balance.

§Parameters

op_x: A function that transforms the x coordinates of both balances.
op_y: A function that transforms the y coordinates of both balances.
other: The second Balance object to use for coordinate transformations.

§Returns

A new Balance object with transformed x and y based on the provided functions and the two input balances.

§Examples

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

let balance1 = Balance::TopRight;
let balance2 = Balance::BottomLeft;

let result = balance1.apply_with(
    |x1, x2| x1.k3_equiv(x2),
    |y1, y2| y1.k3_imply(y2),
    balance2
);

assert_eq!(result, Balance::BottomLeft);

Source