Class AdvancedMultiSpatialMap<T>

A more complex version of MultiSpatialMap<T> that does not require the items in it to implement IHasID, instead requiring the specification of a custom IEqualityComparer<T> to use for hashing and comparison of items.

Inheritance

Object

AdvancedMultiSpatialMap<T>

MultiSpatialMap<T>

Implements

ISpatialMap<T>

IReadOnlySpatialMap<T>

IEnumerable<ItemPositionPair<T>>

IEnumerable

Namespace: SadRogue.Primitives.SpatialMaps

Assembly: TheSadRogue.Primitives.dll

Syntax

public class AdvancedMultiSpatialMap<T> : Object, ISpatialMap<T>, IReadOnlySpatialMap<T>, IEnumerable<ItemPositionPair<T>>, IEnumerable

Type Parameters

Name	Description
T	The type of object that will be contained by this AdvancedMultiSpatialMap.

Remarks

This class is useful for cases where you do not want to implement IHasID, or if you need to use a value type in a spatial map. For simple cases, it is recommended to use MultiSpatialMap<T> instead.

Be mindful of the efficiency of your hashing function specified in the IEqualityComparer<T> -- it will in large part determine the performance of AdvancedMultiSpatialMap!

Constructors

AdvancedMultiSpatialMap(IEqualityComparer<T>, IListPool<T>, IEqualityComparer<Point>, Int32)

Constructor.

Declaration

public AdvancedMultiSpatialMap(IEqualityComparer<T> itemComparer, IListPool<T> listPool, IEqualityComparer<Point> pointComparer = null, int initialCapacity = 32)

Parameters

Type	Name	Description
IEqualityComparer<T>	itemComparer	Equality comparer to use for comparison and hashing of type T. Be especially mindful of the efficiency of its GetHashCode function, as it will determine the efficiency of many AdvancedMultiSpatialMap functions.
IListPool<T>	listPool	The list pool implementation to use. Specify NoPoolingListPool<T> to disable pooling entirely. This implementation may be shared with other spatial maps if you wish, however be aware that no thread safety is implemented by the default list pool implementations or the spatial map itself.
IEqualityComparer<Point>	pointComparer	Equality comparer to use for comparison and hashing of points, as object are added to/removed from/moved around the spatial map. Be especially mindful of the efficiency of its GetHashCode function, as it will determine the efficiency of many AdvancedMultiSpatialMap functions. Defaults to the default equality comparer for Point, which uses a fairly efficient generalized hashing algorithm.
Int32	initialCapacity	The initial maximum number of elements the AdvancedMultiSpatialMap can hold before it has to internally resize data structures. Defaults to 32.

AdvancedMultiSpatialMap(IEqualityComparer<T>, IEqualityComparer<Point>, Int32)

Constructor.

Declaration

public AdvancedMultiSpatialMap(IEqualityComparer<T> itemComparer, IEqualityComparer<Point> pointComparer = null, int initialCapacity = 32)

Parameters

Type	Name	Description
IEqualityComparer<T>	itemComparer	Equality comparer to use for comparison and hashing of type T. Be especially mindful of the efficiency of its GetHashCode function, as it will determine the efficiency of many AdvancedMultiSpatialMap functions.
IEqualityComparer<Point>	pointComparer	Equality comparer to use for comparison and hashing of points, as object are added to/removed from/moved around the spatial map. Be especially mindful of the efficiency of its GetHashCode function, as it will determine the efficiency of many AdvancedMultiSpatialMap functions. Defaults to the default equality comparer for Point, which uses a fairly efficient generalized hashing algorithm.
Int32	initialCapacity	The initial maximum number of elements the AdvancedMultiSpatialMap can hold before it has to internally resize data structures. Defaults to 32.

Properties

Count

The number of items in the spatial map.

Declaration

public int Count { get; }

Property Value

Type	Description
Int32

Items

Enumerable of the items stored in the spatial map: for use to iterate over all items with a foreach loop.

Declaration

public IEnumerable<T> Items { get; }

Property Value

Type	Description
IEnumerable<T>

Positions

Enumerable of all positions that contain items.

Declaration

public IEnumerable<Point> Positions { get; }

Property Value

Type	Description
IEnumerable<Point>

Methods

Add(T, Point)

Adds the given item at the given position, provided the item is not already in the spatial map. If the item is already added, throws ArgumentException.

Declaration

public void Add(T item, Point position)

Parameters

Type	Name	Description
T	item	The item to add.
Point	position	The position at which to add the new item.

Add(T, Int32, Int32)

Adds the given item at the given position, provided the item is not already in the spatial map. If the item is already added, throws ArgumentException.

Declaration

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

Parameters

Type	Name	Description
T	item	The 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.

AsReadOnly()

Returns a read-only reference to the spatial map. Convenient for "safely" exposing the spatial as a property, without allowing direct modification.

Declaration

public IReadOnlySpatialMap<T> AsReadOnly()

Returns

Type	Description
IReadOnlySpatialMap<T>	The current spatial map, as a "read-only" reference.

CanAdd(T, Point)

Returns true if the given item can be added at the given position, eg. if the item is not already in the spatial map; false otherwise.

Declaration

public bool CanAdd(T newItem, Point position)

Parameters

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

Returns

Type	Description
Boolean	True if the item can be successfully added at the position given; false otherwise.

CanAdd(T, Int32, Int32)

Returns true if the given item can be added at the given position, eg. if the item is not already in the spatial map; false otherwise.

Declaration

public bool CanAdd(T newItem, int x, int y)

Parameters

Type	Name	Description
T	newItem	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 can be successfully added at the position given; false otherwise.

CanMove(T, Point)

Returns true if the given item can be moved from its current location to the specified one, eg. the item is contained within the spatial map; false otherwise.

Declaration

public bool CanMove(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 given item can be moved to the given position; false otherwise.

CanMove(T, Int32, Int32)

Returns true if the given item can be moved from its current location to the specified one, eg. the item is contained within the spatial map; false otherwise.

Declaration

public bool CanMove(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 given item can be moved to the given position; false otherwise.

CanMoveAll(Point, Point)

Returns true if there are items at current and all items at that position can be moved to target; false otherwise.

Declaration

public bool CanMoveAll(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 the position current can be moved to the position target; false if one or more items cannot be moved or there are no items to move.

CanMoveAll(Int32, Int32, Int32, Int32)

Returns true if there are items at the current position specified, and all items at that position can be moved to the target position; false otherwise.

Declaration

public bool CanMoveAll(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 the position current can be moved to the position target; false if one or more items cannot be moved or there are no items to move.

Clear()

Clears all items out of the spatial map.

Declaration

public void Clear()

Contains(T)

Returns whether or not the spatial map contains the given item.

Declaration

public bool Contains(T item)

Parameters

Type	Name	Description
T	item	The item to check for.

Returns

Type	Description
Boolean	True if the given item is contained in the spatial map, false if not.

Contains(Point)

Returns if there is an item in the spatial map at the given position or not.

Declaration

public bool Contains(Point position)

Parameters

Type	Name	Description
Point	position	The position to check for.

Returns

Type	Description
Boolean	True if there is some item at the given position, false if not.

Contains(Int32, Int32)

Returns if there is an item in the spatial map at the given position or not.

Declaration

public bool Contains(int x, int y)

Parameters

Type	Name	Description
Int32	x	The x-value of the position to check for.
Int32	y	The y-value of the position to check for.

Returns

Type	Description
Boolean	True if there is some item at the given position, false if not.

GetEnumerator()

Used by foreach loop, so that the class will give ISpatialTuple objects when used in a foreach loop. Generally should never be called explicitly.

Declaration

public IEnumerator<ItemPositionPair<T>> GetEnumerator()

Returns

Type	Description
IEnumerator<ItemPositionPair<T>>	An enumerator for the spatial map.

GetItemsAt(Point)

Gets the item(s) at the given position if there are any items, or returns nothing if there is nothing at that position.

Declaration

public ListEnumerator<T> GetItemsAt(Point position)

Parameters

Type	Name	Description
Point	position	The position to return the item(s) for.

Returns

Type	Description
ListEnumerator<T>	The item(s) at the given position if there are any items, or nothing if there is nothing at that position.

GetItemsAt(Int32, Int32)

Gets the item(s) at the given position if there are any items, or returns nothing if there is nothing at that position.

Declaration

public ListEnumerator<T> GetItemsAt(int x, int y)

Parameters

Type	Name	Description
Int32	x	The x-value of the position to return the item(s) for.
Int32	y	The y-value of the position to return the item(s) for.

Returns

Type	Description
ListEnumerator<T>	The item(s) at the given position if there are any items, or nothing if there is nothing at that position.

GetPositionOf(T)

Gets the position associated with the given item in the spatial map. If the item does not exist in the spatial map, throws ArgumentException.

Declaration

public Point GetPositionOf(T item)

Parameters

Type	Name	Description
T	item	The item to get the position for.

Returns

Type	Description
Point	The position associated with the given item.

GetPositionOfOrNull(T)

Gets the position associated with the given item in the spatial map, or null if that item is not found.

Declaration

public Nullable<Point> GetPositionOfOrNull(T item)

Parameters

Type	Name	Description
T	item	The item to get the position for.

Returns

Type	Description
Nullable<Point>	The position associated with the given item, if it exists in the spatial map, or null if the item does not exist.

Move(T, Point)

Moves the item specified to the position specified. If the item does not exist in the spatial map, the function throws ArgumentException.

Declaration

public void Move(T item, Point target)

Parameters

Type	Name	Description
T	item	The item to move.
Point	target	The position to move it to.

Move(T, Int32, Int32)

Moves the item specified to the position specified. If the item does not exist in the spatial map, the function throws ArgumentException.

Declaration

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

Parameters

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

MoveAll(Point, Point)

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

Declaration

public 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 there are no items to be moved.

Declaration

public 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

public 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

public 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

public 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

public 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 item specified, if it exists. Throws ArgumentException if the item is not in the spatial map.

Declaration

public 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

public 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

public 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.

ToString()

Returns a string representation of the spatial map.

Declaration

public override string ToString()

Returns

Type	Description
String	A string representation of the spatial map.

ToString(Func<T, String>)

Returns a string representation of the spatial map, allowing display of the spatial map's items in a specified way.

Declaration

public string ToString(Func<T, string> itemStringifier)

Parameters

Type	Name	Description
Func<T, String>	itemStringifier	Function that turns an item into a string.

Returns

Type	Description
String	A string representation of the spatial map.

TryAdd(T, Point)

Adds the given item at the given position, provided the item is not already in the spatial map. If the item is already added, returns false.

Declaration

public bool TryAdd(T item, Point position)

Parameters

Type	Name	Description
T	item	The item to add.
Point	position	The position at which to add the new item.

Returns

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

TryAdd(T, Int32, Int32)

Adds the given item at the given position, provided the item is not already in the spatial map. If the item is already added, returns false.

Declaration

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

Parameters

Type	Name	Description
T	item	The 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.

TryGetPositionOf(T, out Point)

Attempts to get the position of the given item in the spatial map. If successful, the function will return true and the position will be stored in the position parameter. If the item was not found, position will have the default value for Point, and the function will return false.

Declaration

public bool TryGetPositionOf(T item, out Point position)

Parameters

Type	Name	Description
T	item	Item to retrieve the position of.
Point	position	The position of the item if found, or default(Point) if not.

Returns

Type	Description
Boolean	True if the item was found in the spatial map, 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

public 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

public 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

public 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

public 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)

Removes the item specified, if it exists. If the item is not in the spatial map, returns false.

Declaration

public 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

public 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

public 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

Events

ItemAdded

Event that is fired directly after an item has been added to the spatial map.

Declaration

public event EventHandler<ItemEventArgs<T>> ItemAdded

Event Type

Type	Description
EventHandler<ItemEventArgs<T>>

ItemMoved

Event that is fired directly after an item in the spatial map has been moved.

Declaration

public event EventHandler<ItemMovedEventArgs<T>> ItemMoved

Event Type

Type	Description
EventHandler<ItemMovedEventArgs<T>>

ItemRemoved

Event that is fired directly after an item has been removed from the spatial map.

Declaration

public event EventHandler<ItemEventArgs<T>> ItemRemoved

Event Type

Type	Description
EventHandler<ItemEventArgs<T>>

Explicit Interface Implementations

IReadOnlySpatialMap<T>.GetItemsAt(Point)

Gets the item(s) at the given position if there are any items, or returns nothing if there is nothing at that position.

Declaration

IEnumerable<T> IReadOnlySpatialMap<T>.GetItemsAt(Point position)

Parameters

Type	Name	Description
Point	position	The position to return the item(s) for.

Returns

Type	Description
IEnumerable<T>	The item(s) at the given position if there are any items, or nothing if there is nothing at that position.

IReadOnlySpatialMap<T>.GetItemsAt(Int32, Int32)

Gets the item(s) at the given position if there are any items, or returns nothing if there is nothing at that position.

Declaration

IEnumerable<T> IReadOnlySpatialMap<T>.GetItemsAt(int x, int y)

Parameters

Type	Name	Description
Int32	x	The x-value of the position to return the item(s) for.
Int32	y	The y-value of the position to return the item(s) for.

Returns

Type	Description
IEnumerable<T>	The item(s) at the given position if there are any items, or nothing if there is nothing at that position.

Implements

ISpatialMap<T>

IReadOnlySpatialMap<T>

System.Collections.Generic.IEnumerable<T>

System.Collections.IEnumerable

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>>)