Struct Map

pub struct Map<Tile> { /* private fields */ }

A Map keeps track of a tile grid.

Its coordinate system assumes that the origin is in the lower left, for compatibility with Direction.

While it is possible to clone a map, it is generally safe to assume that doing so is a sign that there’s a better approach possible.

Entry Points

• Map::new is most useful when the problem involves cartography.
• When a map is provided as the day’s input, use Map::try_from

Panics

Several internal methods assume that the width and height of the map can be represented in an i32. Very large maps may panic if that assumption is violated.

Implementations

impl<Tile> Map<Tile>

pub fn procedural( width: usize, height: usize, procedure: impl Fn(Point) -> Tile, ) -> Map<Tile>

Procedurally create a new Map from a function.

pub fn procedural_offset( offset: Point, width: usize, height: usize, procedure: impl Fn(Point) -> Tile, ) -> Map<Tile>

Procedurally create a new Map from a function, with an offset origin.

This offset can reduce dead space when the interesting part of a map is far from the origin.

pub fn width(&self) -> usize

Width of this map.

pub fn height(&self) -> usize

Height of this map.

pub fn offset(&self) -> Point

Offset of the lower left corner of this map from (0, 0).

pub fn low_x(&self) -> i32

Lowest x coordinate which is in bounds of this map.

pub fn high_x(&self) -> i32

Highest x coordinate which is in bounds of this map.

Note that this is inclusive; use ..= when using this to bound a range.

pub fn low_y(&self) -> i32

Lowest y coordinate which is in bounds of this map.

pub fn high_y(&self) -> i32

Highest y coordinate which is in bounds of this map.

Note that this is inclusive; use ..= when using this to bound a range.

pub fn bottom_left(&self) -> Point

The coordinates of the bottom left corner of this map.

This is inclusive; it is a valid index into the map.

pub fn top_left(&self) -> Point

The coordinates of the top left corner of this map.

This is inclusive; it is a valid index into the map.

pub fn bottom_right(&self) -> Point

The coordinates of the bottom right corner of this map.

This is inclusive; it is a valid index into the map.

pub fn top_right(&self) -> Point

The coordinates of the top right corner of this map.

This is inclusive; it is a valid index into the map.

pub fn iter(&self) -> impl Iterator<Item = (Point, &Tile)>

Iterate over the points and tiles of this map.

pub fn iter_mut(&mut self) -> impl Iterator<Item = (Point, &mut Tile)>

Iterate over the points of this tiles in this map, with mutable access to the tiles.

pub fn points(&self) -> impl Iterator<Item = Point>

Iterate over the points of this map without depending on the lifetime of self.

pub fn in_bounds(&self, point: Point) -> bool

true when a point is legal within the bounds of this map.

pub fn make_in_bounds(&self) -> impl Fn(Point) -> bool

Make a function which returns true when the parameter is within the bounds of this map, without depending on the lifetime of self.

pub fn adjacencies(&self, point: Point) -> impl Iterator<Item = Point>

Return an iterator of all legal points adjacent to the given point.

This iterator will return up to 8 elements; it includes diagonals.

pub fn orthogonal_adjacencies( &self, point: Point, ) -> impl Iterator<Item = Point>

Return an iterator of all legal points orthogonally adjacent to the given point,

This iterator will return up to 4 elements; it does not include diagonals.

pub fn make_adjacencies(&self, point: Point) -> impl Iterator<Item = Point>

where Tile: 'static,

Return an iterator of all legal points adjacent to the given point, without depending on the lifetime of self.

This iterator will return up to 8 elements; it includes diagonals.

This introduces a bound that the Tile type must not contain any references. It is also slightly less efficient than [self.adjacencies]. In general, that function should be preferred unless there are lifetime conflicts.

pub fn make_orthogonal_adjacencies( &self, point: Point, ) -> impl Iterator<Item = Point>

where Tile: 'static,

Return an iterator of all legal points orthogonally adjacent to the given point, without depending on the lifetime of self.

This iterator will return up to 4 elements; it does not include diagonals.

This introduces a bound that the Tile type must not contain any references. It is also slightly less efficient than [self.orthogonal_adjacencies]. In general, that function should be preferred unless there are lifetime conflicts.

pub fn project( &self, origin: Point, dx: i32, dy: i32, ) -> impl Iterator<Item = Point>

Return an iterator of all legal points arrived at by applying the given deltas to the origin.

The origin point is always the first item in this iteration.

pub fn edge(&self, direction: Direction) -> Edge

Create an iterator over the points on the edge of this map.

Note that this iterator returns the points which are coordinates for each point on the edge, not the items of this map. You can use the Iterator::map combinator to map it to items from the map, if desired.

The edge is traversed in increasing order. It is a std::iter::DoubleEndedIterator, though, so it can be reversed if desired.

The input direction indicates which edge should be traversed.

pub fn translate(&mut self, dx: i32, dy: i32)

Translate all points in this map by a given amount.

Completes in O(1).

Example

Using the symbols X and O to indicate tiles, and . to indicate out-of-bounds space away from the origin, we start with this map:

XOOX
OXOX

After applying translate(2, 1), we end with this map:

..XOOX
..OXOX
......

pub fn convert_tile_type<NewTile>(self) -> Map<NewTile>

where Tile: Into<NewTile>,

Convert the underlying tile type of a map.

This produces a new map whose tiles are of a new underlying type.

impl<Tile: Clone> Map<Tile>

pub fn extract_interesting_region( &self, is_interesting: impl Fn(Point, &Tile) -> bool, ) -> Self

Reduce the map to that portion which is interesting according to some user-defined metric.

This can be helpful when preparing visualizations.

impl<Tile: Clone + Default> Map<Tile>

pub fn new(width: usize, height: usize) -> Map<Tile>

Create a new map of the specified dimensions.

Its lower left corner is at (0, 0).

pub fn new_offset(offset: Point, width: usize, height: usize) -> Map<Tile>

Create a new map of the specified dimensions.

Its lower left corner is at offset.

pub fn flip_vertical(&self) -> Map<Tile>

Create a copy of this map which has been flipped vertically: the axis of symmetry is horizontal.

This does not adjust the offset; the corners remain where they previously were.

pub fn flip_horizontal(&self) -> Map<Tile>

Create a copy of this map which has been flipped horizontally; the axis of symmetry is vertical.

This does not adjust the offset; the corners remain where they previously were.

pub fn rotate_left(&self) -> Map<Tile>

Create a copy of this map which has been rotated counter-clockwise.

This maintains the invariant that all points are in the positive quadrant, and assumes that the offset is (0, 0). If necessary, apply Self::translate before and after this operation to produce an appropriate new offset.

Panics

If the offset is not (0, 0).

pub fn rotate_right(&self) -> Map<Tile>

Create a copy of this map which has been rotated clockwise.

This maintains the invariant that all points are in the positive quadrant, and assumes that the offset is (0, 0). If necessary, apply Self::translate before and after this operation to produce an appropriate new offset.

Panics

If the offset is not (0, 0).

impl<Tile> Map<Tile>

where Tile: Clone + DisplayWidth + FromStr, <Tile as FromStr>::Err: 'static + Error + Send + Sync,

pub fn try_from<R>(input: R) -> Result<Self, MapConversionErr>

where R: BufRead,

Try to convert the contents of a reader into a map.

We don’t actually impl<T, R> TryFrom<R> for Map<T> because there’s a coherence conflict with the stdlib blanket impl

impl<T, U> std::convert::TryFrom<U> for T where U: std::convert::Into<T>;

Because there’s a chance that R also implements Into<Map<T>>, we can’t do it.

That doesn’t stop us from doing it here, and implementing the official trait for a few concrete types

impl<Tile> Map<Tile>

where Tile: Display + DisplayWidth,

pub fn to_string_with_override( &self, override_tiles: impl Fn(Point, &Tile) -> Option<String>, ) -> String

Produce a string from this Map, with certain tiles overridden.

This does not edit the map, just adjusts its presentation.

Panics

• If an override value’s returned string is not the same length as Tile::DISPLAY_WIDTH.

impl<Tile> Map<Tile>

where Tile: ToRgb,

pub fn render(&self, output: &Path, style: Style) -> Result<(), RenderError>

Render this map as a still image into an output file.

Depends on the map-render feature.

The output image is a gif under all circumstances. It is useful, though unenforced, that the output file name matches *.gif.

pub fn prepare_animation( &self, output: &Path, frame_duration: Duration, style: Style, ) -> Result<Animation, RenderError>

Prepare an animation from this map.

Depends on the map-render feature.

This returns an Animation object which can have frames added to it. This method does not automatically render this Map frame to the Animation. This enables you to set up the animation ahead of time with dummy data.

The major constraint is that all subsequent maps added as frames must have dimensions identical to this Map’s.

The animation will loop infinitely, displaying each frame for frame_duration.

impl<Tile> Map<Tile>

where Tile: Clone + ContextInto<Traversable, Context = ()>,

pub fn reachable_from( &self, point: Point, visit: impl FnMut(Point, &Tile) -> bool, )

Visit every non-obstructed tile reachable from the initial point.

If the visitor ever returns true, processing halts and no further points are visited.

pub fn navigate(&self, from: Point, to: Point) -> Option<Vec<Direction>>

navigate between the given points using A*

impl<Tile: Clone + ContextInto<Traversable>> Map<Tile>

pub fn reachable_from_ctx( &self, context: &<Tile as ContextInto<Traversable>>::Context, point: Point, visit: impl FnMut(Point, &Tile) -> bool, )

Visit every non-obstructed tile reachable from the initial point.

If the visitor ever returns true, processing halts and no further points are visited.

pub fn navigate_ctx( &self, context: &<Tile as ContextInto<Traversable>>::Context, from: Point, to: Point, ) -> Option<Vec<Direction>>

navigate between the given points using A*

Trait Implementations

impl<Tile: Clone> Clone for Map<Tile>

fn clone(&self) -> Map<Tile>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Tile> Debug for Map<Tile>

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

Formats the value using the given formatter.

impl<Tile: Default> Default for Map<Tile>

fn default() -> Map<Tile>

Returns the “default value” for a type.

impl<Tile> Display for Map<Tile>

where Tile: Display + DisplayWidth,

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

Formats the value using the given formatter.

impl<Tile, Row> From<&[Row]> for Map<Tile>

where Tile: Clone, Row: AsRef<[Tile]>,

fn from(source: &[Row]) -> Map<Tile>

Convert an input 2d array into a map.

Note that the input array must already be arranged with the y axis as the outer array and the orientation such that source[0][0] is the lower left corner of the map.

Panics if the input array is not rectangular.

impl<Tile: Hash> Hash for Map<Tile>

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<Tile> Index<(usize, usize)> for Map<Tile>

type Output = Tile

The returned type after indexing.

fn index(&self, (x, y): (usize, usize)) -> &Tile

Performs the indexing (container[index]) operation.

impl<Tile> Index<Point> for Map<Tile>

fn index(&self, point: Point) -> &Tile

Panics if point.x < 0 || point.y < 0

type Output = Tile

The returned type after indexing.

impl<Tile> IndexMut<(usize, usize)> for Map<Tile>

fn index_mut(&mut self, (x, y): (usize, usize)) -> &mut Tile

Performs the mutable indexing (container[index]) operation.

impl<Tile> IndexMut<Point> for Map<Tile>

fn index_mut(&mut self, point: Point) -> &mut Tile

Panics if point.x < 0 || point.y < 0

impl<Tile: PartialEq> PartialEq for Map<Tile>

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

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

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<Tile> TryFrom<&Path> for Map<Tile>

where Tile: Clone + DisplayWidth + FromStr, <Tile as FromStr>::Err: 'static + Error + Send + Sync,

fn try_from(path: &Path) -> Result<Self, Self::Error>

the input should be in natural graphical order: its first characters are the top left.

type Error = Error

The type returned in the event of a conversion error.

impl<Tile> TryFrom<&str> for Map<Tile>

where Tile: Clone + DisplayWidth + FromStr, <Tile as FromStr>::Err: 'static + Error + Send + Sync,

fn try_from(input: &str) -> Result<Self, Self::Error>

the input should be in natural graphical order: its first characters are the top left.

type Error = MapConversionErr

The type returned in the event of a conversion error.

impl<Tile> TryFrom<File> for Map<Tile>

where Tile: Clone + DisplayWidth + FromStr, <Tile as FromStr>::Err: 'static + Error + Send + Sync,

fn try_from(input: File) -> Result<Self, Self::Error>

the input should be in natural graphical order: its first characters are the top left.

type Error = MapConversionErr

The type returned in the event of a conversion error.

impl<Tile: Eq> Eq for Map<Tile>