Class AutoSyncAdvancedMultiSpatialMap<T>

A version of AdvancedMultiSpatialMap<T> which takes items that implement IPositionable, and uses that interface's properties/events to automatically ensure items are recorded at the proper positions in the spatial map when they move and that the position fields are updated if the spatial map's move functions are used.

Inheritance

Object

AutoSyncAdvancedMultiSpatialMap<T>

AutoSyncMultiSpatialMap<T>

Implements

ISpatialMap<T>

IReadOnlySpatialMap<T>

IEnumerable<ItemPositionPair<T>>

IEnumerable

Namespace: SadRogue.Primitives.SpatialMaps

Assembly: TheSadRogue.Primitives.dll

Syntax

public class AutoSyncAdvancedMultiSpatialMap<T> : Object, ISpatialMap<T>, IReadOnlySpatialMap<T>, IEnumerable<ItemPositionPair<T>>, IEnumerable where T : class, IPositionable

Type Parameters

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

Remarks

This class automatically keeps the spatial map position of each object synced up with their Position property; you may either use the Move functions of the spatial map, in which case the Position fields of the objects are updated as appropriate, or you may change the Position field, in which case the spatial map position is updated to match.

If you want to manually control the positions of items in the spatial map, you should use AdvancedMultiSpatialMap<T> instead.

Constructors

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

Constructor.

Declaration

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

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

Constructor.

Declaration

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

Adds the given item at its 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)

Parameters

Type	Name	Description
T	item	The item to add.

Add(T, Point)

Changes the position field of the given item to the given value, and then adds it to the spatial map, 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)

Changes the position field of the given item to the given value, and then adds it to the spatial map, 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)

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

Declaration

public bool CanAdd(T newItem)

Parameters

Type	Name	Description
T	newItem	Item to add.

Returns

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

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, updating its Position field accordingly. 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, updating its Position field accordingly. If the item does not exist in the spatial map or is already at the target position, 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, updating their Position fields accordingly. 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, updating their Position fields accordingly. 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)

Adds the given item at its 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)

Parameters

Type	Name	Description
T	item	The item to add.

Returns

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

TryAdd(T, Point)

Changes the position field of the given item to the given value, and then adds it to the spatial map, provided the item is not already in the spatial map. If the item is already added, nothing is changed and the function 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)

Changes the position field of the given item to the given value, and then adds it to the spatial map, provided the item is not already in the spatial map. If the item is already added, nothing is changed and the function 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. Must match the item's Position field.
Int32	y	y-value of the position to add item to. Must match the item's Position field.

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)

Declaration

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

Parameters

Type	Name	Description
Point	position

Returns

Type	Description
IEnumerable<T>

IReadOnlySpatialMap<T>.GetItemsAt(Int32, Int32)

Declaration

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

Parameters

Type	Name	Description
Int32	x
Int32	y

Returns

Type	Description
IEnumerable<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>>)