Class Point

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

Inheritance
Object
Point
Namespace: SadRogue.Primitives
Assembly: TheSadRogue.Primitives.dll
Syntax
public sealed class Point : ValueType, IEquatable<Point>, IEquatable<(int, int)>, IMatchable<Point>, IMatchable<(int, int)>
Remarks

Point instances can be created using the standard Point c = new Point(x, y) syntax. In addition, you may create a coord 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(Int32, Int32)

Constructor.

Declaration
public Point(int x, int y)
Parameters
Type Name Description
Int32 x

X-value for the coordinate.
Int32 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
public readonly int X
Field Value
Type Description
Int32

Y

Y-value of the position.

Declaration
public readonly int Y
Field Value
Type Description
Int32

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(Int32, Int32)

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
Int32 dx

Change in x-value across the line.
Int32 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(Int32, Int32, Int32, Int32)

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
Int32 startX

X-value of the position of line starting point.
Int32 startY

Y-value of the position of line starting point.
Int32 endX

X-value of the position of line ending point.
Int32 endY

X-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 Int32, out Int32)

Adds support for C# Deconstruction syntax.

Declaration
public void Deconstruct(out int x, out int y)
Parameters
Type Name Description
Int32 x
Int32 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
Boolean

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
Boolean

True if obj is a Coord instance, and the two positions are equal, false otherwise.

Equals((Int32, Int32))

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

Declaration
public bool Equals((int, int) other)
Parameters
Type Name Description
(, )<Int32, Int32> other

Tuple to compare.
Returns
Type Description
Boolean

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(Int32, Int32)

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
Int32 dx

Change in x-values between the two points.
Int32 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(Int32, Int32, Int32, Int32)

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
Int32 firstX

X-value for the first point.
Int32 firstY

Y-value for the first point.
Int32 secondX

X-value for the second point.
Int32 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(Int32, Int32)

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
Int32 index

The index in 1D form.
Int32 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
Int32

The hash-code for the Point.
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 bitmasks 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
Boolean

True if the two positions are equal, false if not.

Matches((Int32, Int32))

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

Declaration
public bool Matches((int, int) other)
Parameters
Type Name Description
(, )<Int32, Int32> other

Point to compare.
Returns
Type Description
Boolean

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(Int32, Int32, Int32, Int32)

Returns the midpoint between the two points.

Declaration
public static Point Midpoint(int firstX, int firstY, int secondX, int secondY)
Parameters
Type Name Description
Int32 firstX

X-value for the first point.
Int32 firstY

Y-value for the first point.
Int32 secondX

X-value for the second point.
Int32 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, Int32, Int32)

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
Int32 originX

X-value of the location around which to rotate
Int32 originY

Y-value of the location around which to rotate
Returns
Type Description
Point

The equivalent point after a rotation

ToIndex(Int32)

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

Declaration
public int ToIndex(int width)
Parameters
Type Name Description
Int32 width

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

The 1D index of this Point.

ToIndex(Int32, Int32, Int32)

Returns y * width + x.

Declaration
public static int ToIndex(int x, int y, int width)
Parameters
Type Name Description
Int32 x

X-value of the coordinate.
Int32 y

Y-value of the coordinate.
Int32 width

The width of the 2D array, used to do the math to calculate index.
Returns
Type Description
Int32

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)

ToXValue(Int32, Int32)

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
Int32 index

The index in 1D form.
Int32 width

The width of the 2D array.
Returns
Type Description
Int32

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

ToYValue(Int32, Int32)

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
Int32 index

The index in 1D form.
Int32 width

The width of the 2D array.
Returns
Type Description
Int32

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(Int32, Int32)

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
Int32 dx

Change in x-value to apply.
Int32 dy

Change in y-value to apply.
Returns
Type Description
Point

The position (X + dx, Y + dy)

WithX(Int32)

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

Declaration
public Point WithX(int x)
Parameters
Type Name Description
Int32 x

X-value for the new Point.
Returns
Type Description
Point

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

WithY(Int32)

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

Declaration
public Point WithY(int y)
Parameters
Type Name Description
Int32 y

Y-value for the new Point.
Returns
Type Description
Point

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

Operators

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

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

Addition(Point, Int32)

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
Int32 i
Returns
Type Description
Point

Position (c.X + i, c.Y + i.

Addition(Point, (Int32, Int32))

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

Declaration
public static Point operator +(Point c, (int, int) tuple)
Parameters
Type Name Description
Point c
(, )<Int32, Int32> tuple
Returns
Type Description
Point

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

Addition((Int32, Int32), Point)

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

Declaration
public static (int, int) operator +((int, int) tuple, Point c)
Parameters
Type Name Description
(, )<Int32, Int32> tuple
Point c
Returns
Type Description
(, )<Int32, Int32>

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

Division(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.

Division(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.

Division(Point, (Int32, Int32))

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, int) tuple)
Parameters
Type Name Description
Point c
(, )<Int32, Int32> tuple
Returns
Type Description
Point

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

Division((Int32, Int32), 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, int) operator /((int, int) tuple, Point c)
Parameters
Type Name Description
(, )<Int32, Int32> tuple
Point c
Returns
Type Description
(, )<Int32, Int32>

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

Equality(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
Boolean

True if the two positions are equal, false if not.

Equality(Point, (Int32, Int32))

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

Declaration
public static bool operator ==(Point c, (int, int) tuple)
Parameters
Type Name Description
Point c
(, )<Int32, Int32> tuple
Returns
Type Description
Boolean

True if the two positions are equal, false if not.

Equality((Int32, Int32), Point)

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

Declaration
public static bool operator ==((int, int) tuple, Point c)
Parameters
Type Name Description
(, )<Int32, Int32> tuple
Point c
Returns
Type Description
Boolean

True if the two positions are equal, false if not.

Implicit(Point to PolarCoordinate)

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(Point to (Int32, Int32))

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

Declaration
public static implicit operator (int, int)(Point c)
Parameters
Type Name Description
Point c
Returns
Type Description
(, )<Int32, Int32>

Implicit((Int32, Int32) to Point)

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

Declaration
public static implicit operator Point((int, int) tuple)
Parameters
Type Name Description
(, )<Int32, Int32> tuple
Returns
Type Description
Point

Inequality(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
Boolean

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

Inequality(Point, (Int32, Int32))

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

Declaration
public static bool operator !=(Point c, (int, int) tuple)
Parameters
Type Name Description
Point c
(, )<Int32, Int32> tuple
Returns
Type Description
Boolean

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

Inequality((Int32, Int32), Point)

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

Declaration
public static bool operator !=((int, int) tuple, Point c)
Parameters
Type Name Description
(, )<Int32, Int32> tuple
Point c
Returns
Type Description
Boolean

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

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

Multiply(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.

Multiply(Point, Int32)

Multiplies the x and y of c by i.

Declaration
public static Point operator *(Point c, int i)
Parameters
Type Name Description
Point c
Int32 i
Returns
Type Description
Point

Coordinate (c.X * i, c.Y * i)

Multiply(Point, (Int32, Int32))

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, int) tuple)
Parameters
Type Name Description
Point c
(, )<Int32, Int32> tuple
Returns
Type Description
Point

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

Multiply((Int32, Int32), 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, int) operator *((int, int) tuple, Point c)
Parameters
Type Name Description
(, )<Int32, Int32> tuple
Point c
Returns
Type Description
(, )<Int32, Int32>

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

Subtraction(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).

Subtraction(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).

Subtraction(Point, Int32)

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
Int32 i
Returns
Type Description
Point

The coordinate (c.X - i, c.Y - i).

Subtraction(Point, (Int32, Int32))

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

Declaration
public static Point operator -(Point c, (int, int) tuple)
Parameters
Type Name Description
Point c
(, )<Int32, Int32> tuple
Returns
Type Description
Point

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

Subtraction((Int32, Int32), Point)

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

Declaration
public static (int, int) operator -((int, int) tuple, Point c)
Parameters
Type Name Description
(, )<Int32, Int32> tuple
Point c
Returns
Type Description
(, )<Int32, Int32>

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

Implements

Extension Methods