Class AdvancedSpatialMap<T>

A more complex version of SpatialMap<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

AdvancedSpatialMap<T>

SpatialMap<T>

Implements

ISpatialMap<T>

IReadOnlySpatialMap<T>

IEnumerable<ItemPositionPair<T>>

IEnumerable

Namespace: SadRogue.Primitives.SpatialMaps

Assembly: TheSadRogue.Primitives.dll

Syntax

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

Remarks

This class is useful for cases where you do not want to or cannot implement IHasID, or if you need to use a value type in a spatial map. For simple cases, it is recommended to use SpatialMap<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 AdvancedSpatialMap!

Constructors

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

Constructor.

Declaration

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

Tries to add the given item at the given position, provided the item is not already in the spatial map and the position is not already filled. If either of those are the case, throws ArgumentException.

Declaration

public 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, provided the item is not already in the spatial map and the position is not already filled. If either of those are the case, throws ArgumentException.

Declaration

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

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. the item is not already in the spatial map and the position is not already filled; 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. the item is not already in the spatial map and the position is not already filled; 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. if the item does exists in the spatial map and if the new position is not already filled by some other item; false otherwise. However, if the item is already at the specified position, always returns true.

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. if the item exists in the spatial map and if the new position is not already filled by some other item; 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 the item at the current position specified can be moved to the target position, eg. if an item exists at the current position and the new position is not already filled by some other item; 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.

CanMoveAll(Int32, Int32, Int32, Int32)

Returns true if the item at the current position specified can be moved to the target position, eg. if an item exists at the current position and the new position is not already filled by some other item; 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.

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

GetItem(Point)

Gets the item at the given position. Throws ArgumentException no item exists at the given location.

Declaration

public T GetItem(Point position)

Parameters

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

Returns

Type	Description
T	The item at the given position.

Remarks

Intended to be a more convenient function as compared to GetItemsAt(Point), since this spatial map implementation only allows a single item to at any given location at a time.

Exceptions

Type	Condition
ArgumentException	No item is present in the spatial map at the given position.

GetItem(Int32, Int32)

Gets the item at the given position. Throws ArgumentException no item exists at the given location.

Declaration

public T GetItem(int x, int y)

Parameters

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

Returns

Type	Description
T	The item at the given position.

Remarks

Intended to be a more convenient function as compared to GetItemsAt(Point), since this spatial map implementation only allows a single item to at any given location at a time.

Exceptions

Type	Condition
ArgumentException	No item is present in the spatial map at the given position.

GetItemOrDefault(Point)

Gets the item at the given position, or default(T) if no item exists.

Declaration

public T GetItemOrDefault(Point position)

Parameters

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

Returns

Type	Description
T	The item at the given position, or default(T) if no item exists at that location.

Remarks

Intended to be a more convenient function as compared to GetItemsAt(Point), since this spatial map implementation only allows a single item to at any given location at a time.

GetItemOrDefault(Int32, Int32)

Gets the item at the given position, or default(T) if no item exists.

Declaration

public T GetItemOrDefault(int x, int y)

Parameters

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

Returns

Type	Description
T	The item at the given position, or default(T) if no item exists at that location.

Remarks

Intended to be a more convenient function as compared to GetItemsAt(Int32, Int32), since this spatial map implementation only allows a single item to at any given location at a time.

GetItemsAt(Point)

Gets the item at the given position as a 1-element enumerable if there is any item there, or nothing if there is nothing at that position.

Declaration

public IEnumerable<T> GetItemsAt(Point position)

Parameters

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

Returns

Type	Description
IEnumerable<T>	The item at the given position as a 1-element enumerable, if there is an item there, or nothing if there is no item there.

Remarks

Since this implementation guarantees that only one item can be at any given location at once, the return value is guaranteed to be at most one element. You may find it more convenient to use the GetItem(Point) function when you know you are dealing with a SpatialMap/AdvancedSpatialMap instance.

GetItemsAt(Int32, Int32)

Gets the item at the given position as a 1-element enumerable if there is any item there, or nothing if there is nothing at that position.

Declaration

public IEnumerable<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 at the given position as a 1-element enumerable, if there is an item there, or nothing if there is no item there.

Remarks

Since this implementation guarantees that only one item can be at any given location at once, the return value is guaranteed to be at most one element. You may find it more convenient to use the GetItem(Int32, Int32) function when you know you are dealing with a SpatialMap/AdvancedSpatialMap instance.

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. Throws ArgumentException if the item does not exist in the spatial map or if the position is already filled by some other item.

Declaration

public 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 item specified to the position specified. Throws ArgumentException if the item does not exist in the spatial map or if the position is already filled by some other item.

Declaration

public 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 the item at the specified source location to the target location. Throws ArgumentException if one or more items cannot be moved, eg. if no item exists at the current position or the new position is already filled by some other item.

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 the item at the specified source location to the target location. Throws ArgumentException if one or more items cannot be moved, eg. if no item exists at the current position or the new position is already filled by some other item.

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 whatever is at position current, if anything, to the target position, if it is a valid move. If something was moved, it returns what was moved. If nothing was moved, eg. either there was nothing at current or already something at target, returns nothing.

Declaration

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

Parameters

Type	Name	Description
Point	current	The position of the item to move.
Point	target	The position to move the item to.

Returns

Type	Description
List<T>	The item moved as a 1-element list if something was moved, or nothing if no item was moved.

Remarks

Since this implementation of ISpatialMap guarantees that only one item may be at any given location at a time, the returned values will either be none, or a single value.

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 whatever is at the "current" position specified, if anything, to the "target" position, if it is a valid move. If something was moved, it returns what was moved. If nothing was moved, eg. either there was nothing at the "current" position given, or already something at the "target" position given, it returns nothing.

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 item from.
Int32	currentY	Y-value of the location to move item from.
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
List<T>	The item moved as a 1-element IEnumerable if something was moved, or nothing if no item was moved.

Remarks

Since this implementation of ISpatialMap guarantees that only one item may be at any given location at a time, the returned values will either be none, or a single value.

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. Throws ArgumentException if the item specified was not in the spatial map.

Declaration

public void Remove(T item)

Parameters

Type	Name	Description
T	item	The item to remove.

Remove(Point)

Removes whatever is at the given position, if anything, and returns the item removed as a 1-element IEnumerable. Returns nothing if no item was at the position specified.

Declaration

public List<T> Remove(Point position)

Parameters

Type	Name	Description
Point	position	The position of the item to remove.

Returns

Type	Description
List<T>	The item removed as a 1-element list, if something was removed; an empty list if no item was found at that position.

Remarks

Since this implementation of ISpatialMap guarantees that only one item can be at any given location at a time, the returned value is guaranteed to be either nothing or a single element.

Remove(Int32, Int32)

Removes whatever is at the given position, if anything, and returns the item removed as a 1-element IEnumerable. Returns nothing if no item was at the position specified.

Declaration

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

Parameters

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

Returns

Type	Description
List<T>	The item removed as a 1-element IEnumerable, if something was removed; nothing if no item was found at that position.

Remarks

Since this implementation guarantees that only one item can be at any given location at a time, the returned value is guaranteed to be either nothing or a single element.

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)

Tries to add the given item at the given position, provided the item is not already in the spatial map and the position is not already filled. If either of those are the case, returns false.

Declaration

public 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, provided the item is not already in the spatial map and the position is not already filled. If either of those are the case, returns false.

Declaration

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

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 the item specified was not in the spatial map, does nothing and 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 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>>

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