Interface ISpatialMap<T>

Interface representing the common interface of a "spatial map", which is designed to be a convenient and efficient way to store items that reside on a grid and their locations. If you're about to use a List to store all the objects on a grid, consider using one of the provided ISpatialMap implementation instead.

Inherited Members

IReadOnlySpatialMap<T>.AsReadOnly()

IReadOnlySpatialMap<T>.CanAdd(T, Point)

IReadOnlySpatialMap<T>.CanAdd(T, Int32, Int32)

IReadOnlySpatialMap<T>.CanMove(T, Point)

IReadOnlySpatialMap<T>.CanMove(T, Int32, Int32)

IReadOnlySpatialMap<T>.CanMoveAll(Point, Point)

IReadOnlySpatialMap<T>.CanMoveAll(Int32, Int32, Int32, Int32)

IReadOnlySpatialMap<T>.Contains(T)

IReadOnlySpatialMap<T>.Contains(Point)

IReadOnlySpatialMap<T>.Contains(Int32, Int32)

IReadOnlySpatialMap<T>.GetItemsAt(Point)

IReadOnlySpatialMap<T>.GetItemsAt(Int32, Int32)

IReadOnlySpatialMap<T>.GetPositionOfOrNull(T)

IReadOnlySpatialMap<T>.TryGetPositionOf(T, Point)

IReadOnlySpatialMap<T>.GetPositionOf(T)

IReadOnlySpatialMap<T>.ToString(Func<T, String>)

IReadOnlySpatialMap<T>.Count

IReadOnlySpatialMap<T>.Items

IReadOnlySpatialMap<T>.Positions

IReadOnlySpatialMap<T>.ItemAdded

IReadOnlySpatialMap<T>.ItemMoved

IReadOnlySpatialMap<T>.ItemRemoved

Namespace: SadRogue.Primitives.SpatialMaps

Assembly: TheSadRogue.Primitives.dll

Syntax

public interface ISpatialMap<T> : IReadOnlySpatialMap<T>, IEnumerable<ItemPositionPair<T>>, IEnumerable

Type Parameters

Name	Description
T	The type of object that will be contained by the spatial map.

Remarks

When representing objects considered to be located on a 2D grid, there are two main categories of use cases that seem to be encountered repeatedly. The first is when you have a grid with well defined bounds, and intend to place or calculate one object or value for each location on the grid; the typical solution for this use case is to use an array to store the items (or an ArrayView<T>, which may be more convenient).

The other use case is when you have either an unbounded grid, or more commonly a series of objects where there is not likely to be exactly one object per position. This makes the array solution much less viable, since it would waste a lot of memory. Storing a list of all the objects is another possible option; but while this is fast for iterating over all objects on the grid, it makes retrieving the object (or all objects) at a specific position very inefficient. The traditional answer to that is something like Dictionary<Point, T>, but this can be complex to implement depending on the situation. There are multiple constraints you might want to enforce; some instances might want to ensure that a maximum of only one object is associated with a given location, whereas others might want to allow multiple objects at a location. The latter is particularly troublesome to implement efficiently in a way that minimizes allocations.

A "spatial map", therefore, is a data structure designed to implement position-to-object mappings like the ones described above simply and efficiently. It acts as an abstraction over all of the above types of constraints and more; and the library provides multiple implementations of the interface which are suited to various use cases.

Spatial maps allow you to add items at arbitrary positions, move items around, and remove them, all typically in constant time, rather than time proportional to the number of items stored. They also provide linear-time iteration through all items in the structure (just like Dictionary does), although also like Dictionary, this iteration will usually not be as fast as iterating through the items in a List, even though it shares the same asymptotic characteristics. Additionally, events are provided for when items are added, moved, and removed, which can allow you to respond to these as needed.

One common use case is using spatial maps to store objects that already have a Position field of some sort. In these cases, you will typically want to update the object's position in the spatial map whenever the object moves, so the spatial map's recorded position and the object's recorded position stay in sync.

Methods

Add(T, Point)

Tries to add the given item at the given position, and throws ArgumentException if the item cannot be added.

Declaration

void Add(T item, Point position)

Parameters

Type	Name	Description
T	item	Item to add.
Point	position	Position to add item to.

Add(T, Int32, Int32)

Tries to add the given item at the given position, and throws ArgumentException if the item cannot be added.

Declaration

void Add(T item, int x, int y)

Parameters

Type	Name	Description
T	item	Item to add.
Int32	x	X-value of the position to add item to.
Int32	y	Y-value of the position to add item to.

Clear()

Clears all items out of the spatial map.

Declaration

void Clear()

Move(T, Point)

Moves the given item from its current location to the specified one. Throws ArgumentException if the item cannot be moved.

Declaration

void Move(T item, Point target)

Parameters

Type	Name	Description
T	item	Item to move.
Point	target	Location to move item to.

Move(T, Int32, Int32)

Moves the given item from its current location to the specified one. Throws ArgumentException if the item cannot be moved.

Declaration

void Move(T item, int targetX, int targetY)

Parameters

Type	Name	Description
T	item	Item to move
Int32	targetX	X-value of the location to move item to.
Int32	targetY	Y-value of the location to move item to.

MoveAll(Point, Point)

Moves all items at the specified source location to the target location. Throws ArgumentException if one or more items cannot be moved or there are no items to be moved.

Declaration

void MoveAll(Point current, Point target)

Parameters

Type	Name	Description
Point	current	Location to move items from.
Point	target	Location to move items to.

MoveAll(Int32, Int32, Int32, Int32)

Moves all items at the specified source location to the target location. Throws ArgumentException if one or more items cannot be moved or there are no items to be moved.

Declaration

void MoveAll(int currentX, int currentY, int targetX, int targetY)

Parameters

Type	Name	Description
Int32	currentX	X-value of the location to move items from.
Int32	currentY	Y-value of the location to move items from.
Int32	targetX	X-value of the location to move items to.
Int32	targetY	Y-value of the location to move items to.

MoveValid(Point, Point)

Moves all items at the specified source location that can be moved to the target location. Returns all items that were moved.

Declaration

List<T> MoveValid(Point current, Point target)

Parameters

Type	Name	Description
Point	current	Location to move items from.
Point	target	Location to move items to.

Returns

Type	Description
List<T>	All items that were moved, or an empty list if no items were moved.

MoveValid(Point, Point, List<T>)

Moves all items at the specified source location that can be moved to the target location. Adds all items that were moved to the given list.

Declaration

void MoveValid(Point current, Point target, List<T> itemsMovedOutput)

Parameters

Type	Name	Description
Point	current	Location to move items from.
Point	target	Location to move items to.
List<T>	itemsMovedOutput	A list to which all items successfully moved are added.

MoveValid(Int32, Int32, Int32, Int32)

Moves all items at the specified location that can be moved to the target one. Returns all items that were moved.

Declaration

List<T> MoveValid(int currentX, int currentY, int targetX, int targetY)

Parameters

Type	Name	Description
Int32	currentX	X-value of the location to move items from.
Int32	currentY	Y-value of the location to move items from.
Int32	targetX	X-value of the location to move items to.
Int32	targetY	Y-value of the location to move items to.

Returns

Type	Description
List<T>	All items that were moved, or nothing if no items were moved.

MoveValid(Int32, Int32, Int32, Int32, List<T>)

Moves all items at the specified source location that can be moved to the target location. Adds all items that were moved to the given list.

Declaration

void MoveValid(int currentX, int currentY, int targetX, int targetY, List<T> itemsMovedOutput)

Parameters

Type	Name	Description
Int32	currentX	X-value of the location to move items from.
Int32	currentY	Y-value of the location to move items from.
Int32	targetX	X-value of the location to move items to.
Int32	targetY	Y-value of the location to move items to.
List<T>	itemsMovedOutput	A list to which all items successfully moved are added.

Remove(T)

Removes the given item from the spatial map. Throws ArgumentException if the item cannot be removed.

Declaration

void Remove(T item)

Parameters

Type	Name	Description
T	item	The item to remove.

Remove(Point)

Removes all items at the specified location from the spatial map. Returns all items that were removed.

Declaration

List<T> Remove(Point position)

Parameters

Type	Name	Description
Point	position	Position to remove items from.

Returns

Type	Description
List<T>	All items that were removed, or an empty list if no items were removed.

Remove(Int32, Int32)

Removes all items at the specified location from the spatial map. Returns all items that were removed.

Declaration

List<T> Remove(int x, int y)

Parameters

Type	Name	Description
Int32	x	X-value of the position to remove items from.
Int32	y	Y-value of the position to remove items from.

Returns

Type	Description
List<T>	All items that were removed, or nothing if no items were removed.

TryAdd(T, Point)

Tries to add the given item at the given position. Does nothing and returns false if the item cannot be added.

Declaration

bool TryAdd(T item, Point position)

Parameters

Type	Name	Description
T	item	Item to add.
Point	position	Position to add item to.

Returns

Type	Description
Boolean	True if the item was successfully added; false otherwise.

TryAdd(T, Int32, Int32)

Tries to add the given item at the given position. Does nothing and returns false if the item cannot be added.

Declaration

bool TryAdd(T item, int x, int y)

Parameters

Type	Name	Description
T	item	Item to add.
Int32	x	X-value of the position to add item to.
Int32	y	Y-value of the position to add item to.

Returns

Type	Description
Boolean	True if the item was successfully added; false otherwise.

TryMove(T, Point)

Attempts to move the given item from its current location to the specified one. Does nothing and returns false if the item cannot be moved to the given location.

Declaration

bool TryMove(T item, Point target)

Parameters

Type	Name	Description
T	item	Item to move.
Point	target	Location to move item to.

Returns

Type	Description
Boolean	True if the item was moved; false if not.

TryMove(T, Int32, Int32)

Attempts to move the given item from its current location to the specified one. Does nothing and returns false if the item cannot be moved to the given location.

Declaration

bool TryMove(T item, int targetX, int targetY)

Parameters

Type	Name	Description
T	item	Item to move.
Int32	targetX	X-value of the location to move item to.
Int32	targetY	Y-value of the location to move item to.

Returns

Type	Description
Boolean	True if the item was moved; false if not.

TryMoveAll(Point, Point)

Moves all items at the specified source location to the target location. Returns false if one or more items cannot be moved or there are no items to be moved.

Declaration

bool TryMoveAll(Point current, Point target)

Parameters

Type	Name	Description
Point	current	Location to move items from.
Point	target	Location to move items to.

Returns

Type	Description
Boolean	True if all items at current were moved to target; false otherwise.

TryMoveAll(Int32, Int32, Int32, Int32)

Moves all items at the specified source location to the target location. Returns false if one or more items cannot be moved or there are no items to be moved.

Declaration

bool TryMoveAll(int currentX, int currentY, int targetX, int targetY)

Parameters

Type	Name	Description
Int32	currentX	X-value of the location to move items from.
Int32	currentY	Y-value of the location to move items from.
Int32	targetX	X-value of the location to move items to.
Int32	targetY	Y-value of the location to move items to.

Returns

Type	Description
Boolean	True if all items at (currentX, currentY) were moved to (targetX, targetY); false otherwise.

TryRemove(T)

Attempts to remove the given item from the spatial map. Does nothing and return false if the item cannot be removed.

Declaration

bool TryRemove(T item)

Parameters

Type	Name	Description
T	item	The item to remove.

Returns

Type	Description
Boolean	True if the item was successfully removed; false otherwise.

TryRemove(Point)

Attempts to remove all items at the specified location from the spatial map. Returns true if the items were successfully removed; false if one or more failed.

Declaration

bool TryRemove(Point position)

Parameters

Type	Name	Description
Point	position	Position to remove items from.

Returns

Type	Description
Boolean	True if the items were successfully removed; false otherwise

TryRemove(Int32, Int32)

Attempts to remove all items at the specified location from the spatial map. Returns true if the items were successfully removed; false if one or more failed.

Declaration

bool TryRemove(int x, int y)

Parameters

Type	Name	Description
Int32	x	X-value of the position to remove items from.
Int32	y	Y-value of the position to remove items from.

Returns

Type	Description
Boolean	True if the items were successfully removed; false otherwise

Extension Methods

PropertyChangedEventHelpers.SafelySetProperty<TObject, TProperty>(TObject, ref TProperty, TProperty, EventHandler<ValueChangedEventArgs<TProperty>>)

PropertyChangedEventHelpers.SafelySetProperty<TObject, TProperty>(TObject, ref TProperty, TProperty, EventHandler<ValueChangedEventArgs<TProperty>>, EventHandler<ValueChangedEventArgs<TProperty>>)