Struct Point

A structure that represents a standard 2D point. Provides numerous functions and operators that enable common grid/position-related math and operations.

Implements

IEquatable<Point>

IEquatable<(int x, int y)>

IMatchable<Point>

IMatchable<(int x, int y)>

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Namespace: SadRogue.Primitives

Assembly: TheSadRogue.Primitives.dll

Syntax

[DataContract]
public readonly struct Point : IEquatable<Point>, IEquatable<(int x, int y)>, IMatchable<Point>, IMatchable<(int x, int y)>

Remarks

Point instances can be created using the standard Point c = new Point(x, y) syntax. In addition, you may create a point from a c# 7 tuple, like Point c = (x, y);. As well, Point supports C# Deconstruction syntax.

Point also provides operators and static helper functions that perform common grid math/operations, as well as interoperability with other grid-based classes like Direction.

Constructors

Point(int, int)

Constructor.

Declaration

public Point(int x, int y)

Parameters

Type	Name	Description
int	x	X-value for the coordinate.
int	y	Y-value for the coordinate.

Fields

None

Point value that represents None or no position (since Point is not a nullable type). You can use this constant instead of null if you wish to avoid the use of Point?.

Declaration

public static readonly Point None

Field Value

Type	Description
Point

Remarks

This constant has (x, y) values (int.MinValue, int.MinValue), so a position with those x/y values is not considered a valid coordinate by many functions.

X

X-value of the position.

Declaration

[DataMember]
public readonly int X

Field Value

Type	Description
int

Y

Y-value of the position.

Declaration

[DataMember]
public readonly int Y

Field Value

Type	Description
int

Zero

Point value representing Zero (eg, (0, 0)).

Declaration

public static readonly Point Zero

Field Value

Type	Description
Point

Methods

BearingOfLine(Point)

Calculates the degree bearing of a line with the given delta-x and delta-y values, where 0 degrees points in the direction Up.

Declaration

public static double BearingOfLine(Point deltaChange)

Parameters

Type	Name	Description
Point	deltaChange	Vector, where deltaChange.X is the change in x-values across the line, and deltaChange.Y is the change in y-values across the line.

Returns

Type	Description
double	The degree bearing of the line with the given dx and dy values.

BearingOfLine(Point, Point)

Calculates degree bearing of the line (start => end), where 0 points in the direction Up.

Declaration

public static double BearingOfLine(Point start, Point end)

Parameters

Type	Name	Description
Point	start	Position of line starting point.
Point	end	Position of line ending point.

Returns

Type	Description
double	The degree bearing of the line specified by the two given points.

BearingOfLine(int, int)

Calculates the degree bearing of a line with the given delta-x and delta-y values, where 0 degrees points in the direction Up.

Declaration

public static double BearingOfLine(int dx, int dy)

Parameters

Type	Name	Description
int	dx	Change in x-value across the line.
int	dy	Change in y-value across the line.

Returns

Type	Description
double	The degree bearing of the line with the given dx and dy values.

BearingOfLine(int, int, int, int)

Calculates degree bearing of the line (start => end), where 0 points in the direction Up.

Declaration

public static double BearingOfLine(int startX, int startY, int endX, int endY)

Parameters

Type	Name	Description
int	startX	X-value of the position of line starting point.
int	startY	Y-value of the position of line starting point.
int	endX	X-value of the position of line ending point.
int	endY	Y-value of the position of line ending point.

Returns

Type	Description
double	The degree bearing of the line specified by the two given points.

Deconstruct(out int, out int)

Adds support for C# Deconstruction syntax.

Declaration

public void Deconstruct(out int x, out int y)

Parameters

Type	Name	Description
int	x
int	y

Equals(Point)

True if the given coordinate has equal x and y values to the current one.

Declaration

public bool Equals(Point other)

Parameters

Type	Name	Description
Point	other	Position to compare.

Returns

Type	Description
bool	True if the two positions are equal, false if not.

Equals(object?)

Same as operator == in this case; returns false if obj is not a Point.

Declaration

public override bool Equals(object? obj)

Parameters

Type	Name	Description
object	obj	The object to compare the current Point to.

Returns

Type	Description
bool	True if obj is a Point instance, and the two positions are equal, false otherwise.

Overrides

ValueType.Equals(object)

Equals((int x, int y))

True if the given position has equal x and y values to the current one.

Declaration

public bool Equals((int x, int y) other)

Parameters

Type	Name	Description
(int x, int y)	other	Tuple to compare.

Returns

Type	Description
bool	True if the two positions are equal, false if not.

EuclideanDistanceMagnitude(Point)

Returns the result of the euclidean distance formula, without the square root, given the dx and dy values between two points -- eg., (deltaChange.X * deltaChange.X) + (deltaChange.Y

• deltaChange.Y). Use this if you only care about the magnitude of the distance -- eg., if you're trying to compare two distances. Omitting the square root provides a speed increase.

Declaration

public static double EuclideanDistanceMagnitude(Point deltaChange)

Parameters

Type	Name	Description
Point	deltaChange	Vector, where deltaChange.X is the change in x-values between the two points, and deltaChange.Y is the change in y-values between the two points.

Returns

Type	Description
double	The "magnitude" of the euclidean distance of two locations with the given dx and dy values -- basically the distance formula without the square root.

EuclideanDistanceMagnitude(Point, Point)

Returns the result of the euclidean distance formula, without the square root -- eg., (c2.X - c1.X) * (c2.X - c1.X) + (c2.Y - c1.Y) * (c2.Y - c1.Y). Use this if you only care about the magnitude of the distance -- eg., if you're trying to compare two distances. Omitting the square root provides a speed increase.

Declaration

public static double EuclideanDistanceMagnitude(Point c1, Point c2)

Parameters

Type	Name	Description
Point	c1	The first point.
Point	c2	The second point.

Returns

Type	Description
double	The "magnitude" of the euclidean distance between the two points -- basically the distance formula without the square root.

EuclideanDistanceMagnitude(int, int)

Returns the result of the euclidean distance formula, without the square root, given the dx and dy values between two points -- eg., (deltaChange.X * deltaChange.X) + (deltaChange.Y

• deltaChange.Y). Use this if you only care about the magnitude of the distance -- eg., if you're trying to compare two distances. Omitting the square root provides a speed increase.

Declaration

public static double EuclideanDistanceMagnitude(int dx, int dy)

Parameters

Type	Name	Description
int	dx	Change in x-values between the two points.
int	dy	Change in y-values between the two points.

Returns

Type	Description
double	The "magnitude" of the euclidean distance of two locations with the given dx and dy values -- basically the distance formula without the square root.

EuclideanDistanceMagnitude(int, int, int, int)

Returns the result of the euclidean distance formula, without the square root -- eg., (c2.X - c1.X) * (c2.X - c1.X) + (c2.Y - c1.Y) * (c2.Y - c1.Y). Use this if you only care about the magnitude of the distance -- eg., if you're trying to compare two distances. Omitting the square root provides a speed increase.

Declaration

public static double EuclideanDistanceMagnitude(int firstX, int firstY, int secondX, int secondY)

Parameters

Type	Name	Description
int	firstX	X-value for the first point.
int	firstY	Y-value for the first point.
int	secondX	X-value for the second point.
int	secondY	Y-value for the second point.

Returns

Type	Description
double	The "magnitude" of the euclidean distance between the two points -- basically the distance formula without the square root.

FromIndex(int, int)

Reverses the ToIndex functions, returning the position represented by a given index.

Declaration

public static Point FromIndex(int index, int width)

Parameters

Type	Name	Description
int	index	The index in 1D form.
int	width	The width of the 2D array.

Returns

Type	Description
Point	The position represented by the 1D index given.

GetHashCode()

Returns a hash code for the Point. It should provide very good performance when points are used in Dictionary or HashSet, because it's very fast and produces a fairly low collision rate.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	The hash-code for the Point.

Overrides

ValueType.GetHashCode()

Remarks

This hashing algorithm is a very simple algorithm that is quite fast. Its rate of collisions will be fairly low for most traditional coordinate ranges. In particular, most sensible positive coordinate ranges (at least everything in the range (0, 0) -> (8192, 8192)) produce no collisions. Including coordinates with negative values increases the likelihood that collisions will occur; but the range (-4096, -4096) -> (4096, 4096) produces only 8,192 collisions and no single hash value has more than a single collision.

Particularly since Dictionary and HashSet implements prime modulus rather than simple bit masks or shifts, this collision rate should virtually never impact performance over these ranges (or even higher ranges, likely). Since the algorithm is also fast, this makes it a good fit for a general-case hashing algorithm in C#.

Matches(Point)

True if the given coordinate has equal x and y values to the current one.

Declaration

public bool Matches(Point other)

Parameters

Type	Name	Description
Point	other	Position to compare.

Returns

Type	Description
bool	True if the two positions are equal, false if not.

Matches((int x, int y))

True if the given position has equal x and y values to the current one.

Declaration

public bool Matches((int x, int y) other)

Parameters

Type	Name	Description
(int x, int y)	other	Point to compare.

Returns

Type	Description
bool	True if the two positions are equal, false if not.

Midpoint(Point, Point)

Returns the midpoint between the two points.

Declaration

public static Point Midpoint(Point c1, Point c2)

Parameters

Type	Name	Description
Point	c1	The first point.
Point	c2	The second point.

Returns

Type	Description
Point	The midpoint between c1 and c2.

Midpoint(int, int, int, int)

Returns the midpoint between the two points.

Declaration

public static Point Midpoint(int firstX, int firstY, int secondX, int secondY)

Parameters

Type	Name	Description
int	firstX	X-value for the first point.
int	firstY	Y-value for the first point.
int	secondX	X-value for the second point.
int	secondY	Y-value for the second point.

Returns

Type	Description
Point	The midpoint between the two points.

Rotate(double)

Rotates a single point around the origin (0, 0).

Declaration

public Point Rotate(double degrees)

Parameters

Type	Name	Description
double	degrees	The amount of Degrees to rotate this point clockwise

Returns

Type	Description
Point	The equivalent point after a rotation

Rotate(double, Point)

Rotates a single point around the origin point.

Declaration

public Point Rotate(double degrees, Point origin)

Parameters

Type	Name	Description
double	degrees	The amount of Degrees to rotate this point
Point	origin	The Point around which to rotate

Returns

Type	Description
Point	The equivalent point after a rotation

Rotate(double, int, int)

Rotates a single point around the origin point.

Declaration

public Point Rotate(double degrees, int originX, int originY)

Parameters

Type	Name	Description
double	degrees	The amount of Degrees to rotate this point
int	originX	X-value of the location around which to rotate
int	originY	Y-value of the location around which to rotate

Returns

Type	Description
Point	The equivalent point after a rotation

ToIndex(int)

Returns a value that can be used to uniquely index this location 1D array.

Declaration

public int ToIndex(int width)

Parameters

Type	Name	Description
int	width	The width of the 2D map/array this location is referring to -- used to do the math to calculate index.

Returns

Type	Description
int	The 1D index of this Point.

ToIndex(int, int, int)

Returns y * width + x.

Declaration

public static int ToIndex(int x, int y, int width)

Parameters

Type	Name	Description
int	x	X-value of the coordinate.
int	y	Y-value of the coordinate.
int	width	The width of the 2D array, used to do the math to calculate index.

Returns

Type	Description
int	The 1D index of the position specified.

ToPolarCoordinate()

Returns a Polar Coordinate that is equivalent to this (Cartesian) Coordinate

Declaration

public PolarCoordinate ToPolarCoordinate()

Returns

Type	Description
PolarCoordinate	The Equivalent Polar Coordinate

ToString()

Returns representation (X, Y).

Declaration

public override string ToString()

Returns

Type	Description
string	String (X, Y)

Overrides

ValueType.ToString()

ToXValue(int, int)

Reverses the ToIndex functions, returning only the X-value for the given index.

Declaration

public static int ToXValue(int index, int width)

Parameters

Type	Name	Description
int	index	The index in 1D form.
int	width	The width of the 2D array.

Returns

Type	Description
int	The X-value for the location represented by the given index.

ToYValue(int, int)

Reverses the ToIndex functions, returning only the Y-value for the given index.

Declaration

public static int ToYValue(int index, int width)

Parameters

Type	Name	Description
int	index	The index in 1D form.
int	width	The width of the 2D array.

Returns

Type	Description
int	The Y-value for the location represented by the given index.

Translate(Point)

Returns the position resulting from adding dx to the X-value of the position, and dy to the Y-value of the position.

Declaration

public Point Translate(Point deltaChange)

Parameters

Type	Name	Description
Point	deltaChange	Vector where deltaChange.X represents the delta-x value and deltaChange.Y represents the delta-y value.

Returns

Type	Description
Point	The position (X + deltaChange.X, Y + deltaChange.Y)

Translate(int, int)

Returns the position resulting from adding dx to the X-value of the position, and dy to the Y-value of the position.

Declaration

public Point Translate(int dx, int dy)

Parameters

Type	Name	Description
int	dx	Change in x-value to apply.
int	dy	Change in y-value to apply.

Returns

Type	Description
Point	The position (X + dx, Y + dy)

WithX(int)

Creates a new Point with its X value moved to the given one.

Declaration

public Point WithX(int x)

Parameters

Type	Name	Description
int	x	X-value for the new Point.

Returns

Type	Description
Point	A new Point, with its X value changed to the given one.

WithY(int)

Creates a new Point with its Y value moved to the given one.

Declaration

public Point WithY(int y)

Parameters

Type	Name	Description
int	y	Y-value for the new Point.

Returns

Type	Description
Point	A new Point, with its Y value changed to the given one.

Operators

operator +(Point, Direction)

Translates the given position by one unit in the given direction.

Declaration

public static Point operator +(Point c, Direction d)

Parameters

Type	Name	Description
Point	c
Direction	d

Returns

Type	Description
Point	Position (c.X + d.DeltaX, c.Y + d.DeltaY)

operator +(Point, Point)

Returns the position (c1.X + c2.X, c1.Y + c2.Y).

Declaration

public static Point operator +(Point c1, Point c2)

Parameters

Type	Name	Description
Point	c1
Point	c2

Returns

Type	Description
Point	The position (c1.X + c2.X, c1.Y + c2.Y)

operator +(Point, int)

Adds scalar i to the x and y values of c.

Declaration

public static Point operator +(Point c, int i)

Parameters

Type	Name	Description
Point	c
int	i

Returns

Type	Description
Point	Position (c.X + i, c.Y + i).

operator +(Point, (int x, int y))

Adds the x and y values of a tuple of two integers to a Point.

Declaration

public static Point operator +(Point c, (int x, int y) tuple)

Parameters

Type	Name	Description
Point	c
(int x, int y)	tuple

Returns

Type	Description
Point	Position (c.X + tuple.x, c.Y + tuple.y).

operator +((int x, int y), Point)

Adds the x and y values of a Point to the corresponding values of a tuple of two integers.

Declaration

public static (int x, int y) operator +((int x, int y) tuple, Point c)

Parameters

Type	Name	Description
(int x, int y)	tuple
Point	c

Returns

Type	Description
(int x, int y)	A tuple (tuple.x + c.X, tuple.y + c.Y).

operator /(Point, Point)

Divides the x/y components of c1 by the x/y components of c2, rounding each resulting value to the nearest integer.

Declaration

public static Point operator /(Point c1, Point c2)

Parameters

Type	Name	Description
Point	c1
Point	c2

Returns

Type	Description
Point	Position (c1.X / c2.X, c1.Y / c2.Y), with each value rounded to the nearest integer.

operator /(Point, double)

Divides the x and y of c by i, rounding resulting values to the nearest integer.

Declaration

public static Point operator /(Point c, double i)

Parameters

Type	Name	Description
Point	c
double	i

Returns

Type	Description
Point	(c.X / i, c.Y / i), with the resulting values rounded to the nearest integer.

operator /(Point, (int x, int y))

Divides the x/y values of a Point by the x/y values of a tuple of two integers, rounding to the nearest integer.

Declaration

public static Point operator /(Point c, (int x, int y) tuple)

Parameters

Type	Name	Description
Point	c
(int x, int y)	tuple

Returns

Type	Description
Point	Position (c.X / tuple.x, c.Y / tuple.y), with each value rounded to the nearest integer.

operator /((int x, int y), Point)

Divides the x/y values of a tuple of two integers by the x/y values of a Point, rounding to the nearest integer.

Declaration

public static (int x, int y) operator /((int x, int y) tuple, Point c)

Parameters

Type	Name	Description
(int x, int y)	tuple
Point	c

Returns

Type	Description
(int x, int y)	Position (tuple.x / c.X, tuple.y / c.Y), with each value rounded to the nearest integer.

operator ==(Point, Point)

True if c1.X == c2.X and c1.Y == c2.Y.

Declaration

public static bool operator ==(Point c1, Point c2)

Parameters

Type	Name	Description
Point	c1
Point	c2

Returns

Type	Description
bool	True if the two positions are equal, false if not.

operator ==(Point, (int x, int y))

True if the two point's x and y values are equal.

Declaration

public static bool operator ==(Point c, (int x, int y) tuple)

Parameters

Type	Name	Description
Point	c
(int x, int y)	tuple

Returns

Type	Description
bool	True if the two positions are equal, false if not.

operator ==((int x, int y), Point)

True if the two point's x and y values are equal.

Declaration

public static bool operator ==((int x, int y) tuple, Point c)

Parameters

Type	Name	Description
(int x, int y)	tuple
Point	c

Returns

Type	Description
bool	True if the two positions are equal, false if not.

implicit operator PolarCoordinate(Point)

Implicitly converts a Point to its equivalent polar coordinate.

Declaration

public static implicit operator PolarCoordinate(Point pos)

Parameters

Type	Name	Description
Point	pos	Point to convert.

Returns

Type	Description
PolarCoordinate	A PolarCoordinate equivalent to this cartesian point.

implicit operator (int x, int y)(Point)

Implicitly converts a Point to an equivalent tuple of two integers.

Declaration

public static implicit operator (int x, int y)(Point c)

Parameters

Type	Name	Description
Point	c

Returns

Type	Description
(int x, int y)

implicit operator Point((int x, int y))

Implicitly converts a tuple of two integers to an equivalent Point.

Declaration

public static implicit operator Point((int x, int y) tuple)

Parameters

Type	Name	Description
(int x, int y)	tuple

Returns

Type	Description
Point

operator !=(Point, Point)

True if either the x-values or y-values are not equal.

Declaration

public static bool operator !=(Point c1, Point c2)

Parameters

Type	Name	Description
Point	c1
Point	c2

Returns

Type	Description
bool	True if either the x-values or y-values are not equal, false if they are both equal.

operator !=(Point, (int x, int y))

True if either the x-values or y-values are not equal.

Declaration

public static bool operator !=(Point c, (int x, int y) tuple)

Parameters

Type	Name	Description
Point	c
(int x, int y)	tuple

Returns

Type	Description
bool	True if either the x-values or y-values are not equal, false if they are both equal.

operator !=((int x, int y), Point)

True if either the x-values or y-values are not equal.

Declaration

public static bool operator !=((int x, int y) tuple, Point c)

Parameters

Type	Name	Description
(int x, int y)	tuple
Point	c

Returns

Type	Description
bool	True if either the x-values or y-values are not equal, false if they are both equal.

operator *(Point, Point)

Multiplies the x and y values of the points together.

Declaration

public static Point operator *(Point c1, Point c2)

Parameters

Type	Name	Description
Point	c1
Point	c2

Returns

Type	Description
Point	Position (c1.X * c2.X, c1.Y * c2.Y)

operator *(Point, double)

Multiplies the x and y value of c by i, rounding the result to the nearest integer.

Declaration

public static Point operator *(Point c, double i)

Parameters

Type	Name	Description
Point	c
double	i

Returns

Type	Description
Point	Position (c.X * i, c.Y * i), with the resulting values rounded to nearest integer.

operator *(Point, int)

Multiplies the x and y of c by i.

Declaration

public static Point operator *(Point c, int i)

Parameters

Type	Name	Description
Point	c
int	i

Returns

Type	Description
Point	Coordinate (c.X * i, c.Y * i)

operator *(Point, (int x, int y))

Multiples the x and y values of a Point by the x and y values of a tuple of two integers.

Declaration

public static Point operator *(Point c, (int x, int y) tuple)

Parameters

Type	Name	Description
Point	c
(int x, int y)	tuple

Returns

Type	Description
Point	Position (c.X * tuple.x, c.Y * tuple.y).

operator *((int x, int y), Point)

Multiples the x and y values of a tuple of two integers by the x and y values of a Point.

Declaration

public static (int x, int y) operator *((int x, int y) tuple, Point c)

Parameters

Type	Name	Description
(int x, int y)	tuple
Point	c

Returns

Type	Description
(int x, int y)	Position (tuple.x * c.X, tuple.y * c.Y).

operator -(Point, Direction)

Returns the coordinate (point.X - direction.DeltaX, point.Y - direction.DeltaY).

Declaration

public static Point operator -(Point point, Direction direction)

Parameters

Type	Name	Description
Point	point
Direction	direction

Returns

Type	Description
Point	The coordinate (point.X - direction.DeltaX, point.Y - direction.DeltaY).

operator -(Point, Point)

Returns the coordinate (c1.X - c2.X, c1.Y - c2.Y).

Declaration

public static Point operator -(Point c1, Point c2)

Parameters

Type	Name	Description
Point	c1
Point	c2

Returns

Type	Description
Point	The coordinate(c1 - c2).

operator -(Point, int)

Subtracts scalar i from the x and y values of c.

Declaration

public static Point operator -(Point c, int i)

Parameters

Type	Name	Description
Point	c
int	i

Returns

Type	Description
Point	The coordinate (c.X - i, c.Y - i).

operator -(Point, (int x, int y))

Subtracts the x and y values of a tuple of two integers from a Point.

Declaration

public static Point operator -(Point c, (int x, int y) tuple)

Parameters

Type	Name	Description
Point	c
(int x, int y)	tuple

Returns

Type	Description
Point	Position (c.X - tuple.x, c.Y - tuple.y).

operator -((int x, int y), Point)

Subtracts the x and y values of a Point from a tuple of two integers.

Declaration

public static (int x, int y) operator -((int x, int y) tuple, Point c)

Parameters

Type	Name	Description
(int x, int y)	tuple
Point	c

Returns

Type	Description
(int x, int y)	A tuple (tuple.x - c.X, tuple.y - c.Y).

Implements

IEquatable<T>

IEquatable<T>

IMatchable<T>

IMatchable<T>

Extension Methods

PointExtensions.Add(Point, Direction)

PointExtensions.Add(Point, Point)

PointExtensions.Add(Point, int)

PointExtensions.Divide(Point, Point)

PointExtensions.Divide(Point, double)

PointExtensions.Divide(Point, int)

PointExtensions.Matches(Point, Point)

PointExtensions.Multiply(Point, Point)

PointExtensions.Multiply(Point, double)

PointExtensions.Multiply(Point, int)

PointExtensions.Subtract(Point, Direction)

PointExtensions.Subtract(Point, Point)

PointExtensions.Subtract(Point, int)

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