Struct Path

Source

pub struct Path { /* private fields */ }

Expand description

Represents a sequence of movements in a grid, where each movement is represented by a Balance value indicating the direction of one step.

The Path struct provides various utilities to manipulate and analyze the sequence of movements, including iteration, transformation, normalization, and reversal.

§Examples

Creating a new Path:

use balanced_direction::{Balance, Path};

let movements = vec![Balance::Top, Balance::Right, Balance::Bottom];
let path = Path::new(movements);
assert_eq!(path.len(), 3);

Normalizing a Path:

use balanced_direction::{Balance, Path};

let movements = vec![Balance::Top, Balance::Top];
let path = Path::new(movements).normalized();
assert_eq!(path.to_vector(), (0, -2));

Reversing a Path:

use balanced_direction::{Balance, Path};

let movements = vec![Balance::Top, Balance::Right];
let path = Path::new(movements).reversed();
assert_eq!(path.to_vector(), (1, -1));

Implementations§

Source §

impl Path

Source

pub fn new(movements: Vec<Balance>) -> Self

Creates a new Path from a vector of movements.

Each movement in the vector represents a step in a 3x3 grid, where each step is a Balance value indicating direction or position.

§Arguments

movements - A Vec of Balance values representing the sequence of movements.

§Returns

A new Path instance containing the provided sequence of movements.

§Examples

use balanced_direction::{Balance, Path};

let movements = vec![Balance::Top, Balance::Right, Balance::Bottom];
let path = Path::new(movements);
assert_eq!(path.len(), 3);

Source

pub fn len(&self) -> usize

Returns the number of movements in the Path.

§Returns

An integer representing the number of elements in the Path.

Source

pub fn is_empty(&self) -> bool

Checks whether the Path is empty.

§Returns

true if the Path contains no movements, false otherwise.

Source

pub fn get(&self, index: usize) -> Option<&Balance>

Retrieves the Balance at the specified index in the Path.

§Arguments

index - The position of the Balance in the Path to retrieve.

§Returns

An Option containing a reference to the Balance if the index is valid, or None otherwise.

Source

pub fn iter(&self) -> impl Iterator<Item = &Balance>

Returns an iterator over immutable references to the Balance values in the Path.

The iterator allows traversing the sequence of movements without modifying it.

Source

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut Balance>

Returns an iterator over mutable references to the Balance values in the Path.

The iterator allows traversing the sequence of movements modifying it.

Source

pub fn push(&mut self, movement: Balance)

Appends a new movement to the end of the Path.

§Arguments

movement - The Balance value to be added to the Path.

Source

pub fn pop(&mut self) -> Option<Balance>

Removes the last movement from the Path, if any, and returns it.

§Returns

An Option containing the Balance value that was removed, or None if the Path is empty.

Source

pub fn clear(&mut self)

Clears all movements from the Path, leaving it empty.

Source

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

Converts the sequence of movements in the Path to a vector representation.

Each Balance value in the Path contributes a two-dimensional (i8, i8) vector, which represents its direction or position in the grid. The resulting vector is the cumulative sum of all movements in the sequence.

§Returns

A tuple (i8, i8) where:

The first element is the cumulative movement along the x-axis.
The second element is the cumulative movement along the y-axis.

§Examples

use balanced_direction::{Balance, Path};

let movements = vec![Balance::Top, Balance::Right, Balance::Top];
let path = Path::new(movements);
let vector = path.to_vector();
assert_eq!(vector, (1, -2)); // 1 step right, 2 steps up

Source

pub fn from_vector(x: i8, y: i8) -> Self

Converts a vector representation (x, y) into a Path.

This function takes two integers, x and y, representing cumulative movements along the x-axis and y-axis, respectively, in a 2D grid. It decomposes these movements into individual steps represented as a sequence of Balance values, which are stored in a Path.

Movements are calculated progressively by reducing the values of x and y by their sign in each step until both reach 0. Each step corresponds to a direction as determined by Balance::from_vector.

§Arguments

x - An i8 representing the movement along the x-axis.
y - An i8 representing the movement along the y-axis.

§Returns

A Path instance containing a sequence of movements that achieve the given x and y displacements.

§Examples

use balanced_direction::{Balance, Path};

let path = Path::from_vector(2, -1);
assert_eq!(path.to_vector(), (2, -1));

Source

pub fn normalized(&self) -> Self

Returns a normalized Path.

The normalized Path is constructed by converting the sequence of movements in the current Path into their cumulative vector representation using to_vector and then converting this vector back into a Path using from_vector.

This effectively removes redundant steps in the Path that cancel each other out, resulting in a minimal representation of the net movement.

§Examples

use balanced_direction::{Balance, Path};

let movements = vec![Balance::Top, Balance::Bottom, Balance::Right, Balance::Right];
let path = Path::new(movements);
let normalized_path = path.normalized();
assert_eq!(normalized_path.to_vector(), (2, 0)); // Two steps right

Source

pub fn reversed(&self) -> Self

Reverses the sequence of movements in the Path.

The reversed Path will have its movements ordered in the opposite direction compared to the original Path. The order of the movements is inverted, but the movements themselves remain unchanged.

§Returns

A new Path instance containing the reversed sequence of movements.

§Examples

use balanced_direction::{Balance, Path};

let movements = vec![Balance::Top, Balance::Right, Balance::Left];
let path = Path::new(movements);
let reversed_path = path.reversed();
assert_eq!(path.to_vector(), (0, -1));
assert_eq!(reversed_path.to_vector(), (0, -1));

Source

pub fn each(&self, f: impl Fn(Balance) -> Balance) -> Self

Applies a function f to each Balance in the Path and returns a new Path containing the results.

This method iterates over all movements in the Path, applies the function f to each movement, and collects the resulting Balance values into a new Path.

§Arguments

f - A function or closure of type Fn(Balance) -> Balance that takes a Balance as input and returns a transformed Balance.

§Returns

A new Path where each Balance is the result of applying f to the corresponding Balance in the original Path.

§Example

use balanced_direction::{Balance, Path};

let movements = vec![Balance::Top, Balance::Right, Balance::Left];
let path = Path::new(movements);
let transformed_path = path.each(Balance::up);
assert_eq!(
    transformed_path.to_vector(),
    (0, -3)
);

Source

pub fn each_with( &self, f: impl Fn(Balance, Balance) -> Balance, other: Balance, ) -> Self

Applies a function f, which takes two arguments of type Balance, and returns a transformed Balance, to each Balance in the current Path, using the provided other value as the second argument.

This method iterates over all movements in the Path and applies the function f to each movement and the other value. The results of the function application are collected into a new Path.

§Arguments

f - A function or closure of type Fn(Balance, Balance) -> Balance that takes two Balance arguments and returns a transformed Balance.
other - A Balance value that is passed as the second argument to the function f.

§Returns

A new Path instance where each Balance is the result of applying f to the corresponding Balance in the original Path and the other value.

§Example

use std::ops::Add;
use balanced_direction::{Balance, Path};

let movements = vec![Balance::Left, Balance::TopLeft];
let path = Path::new(movements);
let modified_path = path.each_with(Balance::add, Balance::Right);
assert_eq!(modified_path.to_vector(), (0, -1));

Source

pub fn each_zip( &self, f: impl Fn(Balance, Balance) -> Balance, other: &Self, ) -> Self

Applies a function f to corresponding pairs of Balance values from the current Path and the other Path, and returns a new Path containing the results.

This method iterates over the paired elements of the current Path and the provided other Path, applies the function f to each pair, and collects the results into a new Path.

§Arguments

f - A function or closure of type Fn(Balance, Balance) -> Balance that takes two Balance arguments (one from each Path) and returns a transformed Balance.
other - A reference to another Path whose Balance values will be paired with those of the current Path.

§Returns

A new Path where each Balance is the result of applying f to corresponding pairs of Balance values from the current Path and the other Path.

§Panics

Panics if the lengths of the two Paths are not equal, as the method expects both Paths to contain the same number of movements.

§Examples

use std::ops::Add;
use balanced_direction::{Balance, Path};

let path1 = Path::new(vec![Balance::Top, Balance::Right]);
let path2 = Path::new(vec![Balance::Bottom, Balance::Left]);

let result = path1.each_zip(Balance::add, &path2);
assert_eq!(result.to_vector(), (0, 0));