Struct BoardArea 

pub struct BoardArea { /* private fields */ }

Set of Point2D with small(ish) memory footprint.

Area is bound to game board Size2D given at construction time and only positions on that board can be its members. Point2D outside of it is not a member of any BoardArea and is silently ignored by contains(), add_point() and remove_point().

Examples

use sokoban_elements::*;

let mut area = BoardArea::new(Size2D::new(10, 10));
assert!(area.is_empty());

assert!(area.add_point(Point2D::new(3, 4)));
assert!(!area.add_point(Point2D::new(3, 4))); // ...it was already there

area.extend([Point2D::new(1, 8), Point2D::new(7, 2)]);
assert_eq!(area.len(), 3);
assert!(area.contains(Point2D::new(7, 2)));

// Positions off the board are never members.
assert!(!area.add_point(Point2D::new(42, 0)));
assert!(!area.contains(Point2D::new(42, 0)));

// Iteration is row-major, from top-left to bottom-right.
assert_eq!(
    Vec::from_iter(&area),
    vec![Point2D::new(7, 2), Point2D::new(3, 4), Point2D::new(1, 8)]
);

let other = BoardArea::from_points(area.board_size(), [Point2D::new(3, 4)]);
assert!(other.is_subset(&area));
assert_eq!(
    Vec::from_iter(&area.difference(&other).unwrap()),
    vec![Point2D::new(7, 2), Point2D::new(1, 8)]
);

Todo

• operator implementations (BitOr, BitAnd, BitXor, Sub, Not) for set operations
• retain()
• Display
• serde support

Implementations

impl BoardArea

pub fn new(for_board_size: Size2D) -> Self

Constructs empty area for board of for_board_size.

pub fn from_points<I: IntoIterator<Item = Point2D>>( for_board_size: Size2D, points: I, ) -> Self

Constructs area for board of for_board_size, containing points.

Positions in points that are off board are ignored - see add_point().

There is deliberately no FromIterator implementation: board_size() can’t be recovered from a stream of positions, since their bounding box is not the board they live on.

pub fn board_size(&self) -> Size2D

Size of game board self was constructed for.

Only positions on that board can be members of self.

pub fn len(&self) -> usize

Count of Point2D in self.

pub fn is_empty(&self) -> bool

Returns true if self contains no Point2D.

pub fn clear(&mut self)

Removes all Point2D from self, leaving board_size() unchanged.

pub fn contains(&self, value: Point2D) -> bool

Returns true if value is member of self.

Positions off board_size() are never members, so false is returned for them.

pub fn add_point(&mut self, value: Point2D) -> bool

Adds value to self, returning true if it wasn’t already there.

Positions off board_size() can’t be members of self. They are silently ignored - false is returned and self is left unchanged.

The check is not merely defensive: Point2D::idx() saturates instead of failing, so on a 10x10 board (15, 0) computes the same 1D index as on-board (5, 1). Without it, adding the former would silently set the latter.

Examples

use sokoban_elements::*;

let mut area = BoardArea::new(Size2D::new(10, 10));

assert!(area.add_point(Point2D::new(5, 1)));
assert!(!area.add_point(Point2D::new(5, 1)));

assert!(!area.add_point(Point2D::new(15, 0)));
assert_eq!(area.len(), 1);

pub fn remove_point(&mut self, value: Point2D) -> bool

Removes value from self, returning true if it was present in self.

Positions off board_size() are never members, so false is returned for them and self is left unchanged.

pub fn bounds(&self) -> Option<(Point2D, Point2D)>

Bounding box of self, as (top_left, bottom_right) corners.

Returns None for empty area.

Corners are extremes of member coordinates taken independently per axis, which means they are not necessarily members of self themselves.

Examples

use sokoban_elements::*;

let empty = BoardArea::new(Size2D::new(10, 10));
assert_eq!(empty.bounds(), None);

let area =
    BoardArea::from_points(Size2D::new(10, 10), [Point2D::new(7, 2), Point2D::new(3, 8)]);

// Neither corner is a member of `area`.
assert_eq!(area.bounds(), Some((Point2D::new(3, 2), Point2D::new(7, 8))));
assert_eq!(area.min_x(), Some(3));
assert_eq!(area.max_y(), Some(8));

pub fn min_x(&self) -> Option<usize>

Smallest x of all members of self, or None for empty area.

See bounds().

pub fn min_y(&self) -> Option<usize>

Smallest y of all members of self, or None for empty area.

See bounds().

pub fn max_x(&self) -> Option<usize>

Largest x of all members of self, or None for empty area.

See bounds().

pub fn max_y(&self) -> Option<usize>

Largest y of all members of self, or None for empty area.

See bounds().

pub fn union(&self, other: &Self) -> Option<Self>

Set union - positions that are in self, in other, or in both.

Returns None if self and other were constructed for boards of different board_size(), because areas of differently sized boards are not comparable.

Examples

use sokoban_elements::*;

let size = Size2D::new(10, 10);
let left = BoardArea::from_points(size, [Point2D::new(1, 1), Point2D::new(2, 2)]);
let right = BoardArea::from_points(size, [Point2D::new(2, 2), Point2D::new(3, 3)]);

assert_eq!(left.union(&right).unwrap().len(), 3);
assert_eq!(left.intersection(&right).unwrap().len(), 1);

// Areas of differently sized boards are not comparable.
let other_board = BoardArea::new(Size2D::new(5, 5));
assert_eq!(left.union(&other_board), None);

pub fn intersection(&self, other: &Self) -> Option<Self>

Set intersection - positions that are in both self and other.

Returns None for areas of differently sized boards - see union().

pub fn difference(&self, other: &Self) -> Option<Self>

Set difference - positions that are in self but not in other.

Returns None for areas of differently sized boards - see union().

pub fn symmetric_difference(&self, other: &Self) -> Option<Self>

Set symmetric difference - positions that are in self or in other, but not in both.

Returns None for areas of differently sized boards - see union().

pub fn is_subset(&self, other: &Self) -> bool

Returns true if every member of self is also member of other.

Areas of differently sized boards are not comparable, and for them false is returned. Note that this scopes the usual empty set law to boards of equal size: empty area is subset of every area of the same board_size(), and of no other.

pub fn is_superset(&self, other: &Self) -> bool

Returns true if every member of other is also member of self.

Areas of differently sized boards are not comparable - see is_subset().

pub fn is_disjoint(&self, other: &Self) -> bool

Returns true if self and other have no members in common.

Areas of differently sized boards are not comparable, and for them true is returned. This is the same answer given for genuinely non-overlapping areas of one board, so it can’t be used to tell “no common members” from “not comparable” - compare board_size() first if that distinction matters.

pub fn iter(&self) -> BoardAreaIter<'_>

Iterator over members of self, in row-major order.

Trait Implementations

impl Clone for BoardArea

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BoardArea

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

Formats the value using the given formatter.

impl Eq for BoardArea

impl<'a> Extend<&'a Point2D> for BoardArea

fn extend<T: IntoIterator<Item = &'a Point2D>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl Extend<Point2D> for BoardArea

fn extend<T: IntoIterator<Item = Point2D>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<'a> IntoIterator for &'a BoardArea

type Item = Point2D

The type of the elements being iterated over.

type IntoIter = BoardAreaIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for BoardArea

type Item = Point2D

The type of the elements being iterated over.

type IntoIter = BoardAreaIntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for BoardArea

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for BoardArea