Class GeoCoordinate

Namespace

Trellis.Primitives

Assembly

Trellis.Primitives.dll

A geographic latitude and longitude in decimal degrees.

[JsonConverter(typeof(CompositeValueObjectJsonConverter<GeoCoordinate>))]
public sealed class GeoCoordinate : ValueObject, IComparable<ValueObject>, IComparable, IEquatable<ValueObject>

Inheritance

object

ValueObject

GeoCoordinate

Implements

IComparable<ValueObject>

IComparable

IEquatable<ValueObject>

Inherited Members

ValueObject.Equals(object)

ValueObject.Equals(ValueObject)

ValueObject.GetHashCode()

ValueObject.CompareTo(ValueObject)

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

MaybeExtensions.AsMaybe<T>(T)

MaybeExtensions.ToResult<TValue>(TValue)

NullableExtensions.ToResult<T>(T?, Func<Error>)

NullableExtensions.ToResult<T>(T?, Error)

AggregateTestMutator.ClearMaybeField<TEntity, TValue>(TEntity, Expression<Func<TEntity, Maybe<TValue>>>)

AggregateTestMutator.SetMaybeField<TEntity, TValue>(TEntity, Expression<Func<TEntity, Maybe<TValue>>>, TValue?)

Remarks

Components are finite and stored without rounding or normalization. Equality and ordering use latitude followed by longitude, not geographic equivalence or a distance tolerance. JSON is an object with numeric latitude and longitude properties.

Fields

MeanEarthRadiusMeters

Mean Earth radius used by the spherical distance and bounds calculations.

public const double MeanEarthRadiusMeters = 6371008.8

Field Value

double

Properties

Latitude

Gets the latitude in decimal degrees, from -90 through 90 inclusive.

public double Latitude { get; }

Property Value

double

Longitude

Gets the longitude in decimal degrees, from -180 through 180 inclusive.

public double Longitude { get; }

Property Value

double

Methods

Create(double, double)

Creates a coordinate from trusted values, throwing when either component is invalid.

public static GeoCoordinate Create(double latitude, double longitude)

Parameters

latitude double

Latitude in decimal degrees.

longitude double

Longitude in decimal degrees.

Returns

GeoCoordinate

The validated coordinate.

Remarks

Use TryCreate(double, double, string?) for untrusted input and inside Result pipelines.

Exceptions

InvalidOperationException

A component is non-finite or outside its valid range.

DistanceMetersTo(GeoCoordinate)

Computes the approximate shortest great-circle distance to another coordinate in meters.

public double DistanceMetersTo(GeoCoordinate other)

Parameters

other GeoCoordinate

The destination coordinate.

Returns

double

A finite, non-negative distance in meters.

Remarks

Uses the haversine formula with a fixed mean Earth radius of 6,371,008.8 meters. This spherical approximation is not an ellipsoidal geodesic or a surveying calculation and does not account for altitude. It runs in memory, not as an EF Core SQL expression.

Exceptions

ArgumentNullException

other is null.

GetEqualityComponents(ref EqualityComponents)

When overridden in a derived class, adds the components that define equality for this value object.

protected override void GetEqualityComponents(ref EqualityComponents components)

Parameters

components EqualityComponents

The sink that collects this value object's equality components.

Examples

protected override void GetEqualityComponents(ref EqualityComponents components)
{
    components.Add(Street);
    components.Add(City);
    components.Add(PostalCode);
}

Remarks

This method is used by Equals(ValueObject?), GetHashCode(), and CompareTo(ValueObject?) to determine equality and ordering. Components must be added in a consistent order.

Guidelines:

• Add all properties that define the value object's identity
• For derived classes, call base.GetEqualityComponents(ref components) first
• Add components in a consistent, deterministic order
• Do not allocate: the sink exists so comparisons stay allocation-free

ToString()

Returns the invariant representation (latitude, longitude).

public override string ToString()

Returns

string

The unrounded components formatted with invariant culture.

TryCreate(double, double, string?)

Validates both components and creates a geographic coordinate.

public static Result<GeoCoordinate> TryCreate(double latitude, double longitude, string? fieldName = null)

Parameters

latitude double

Latitude in decimal degrees, from -90 through 90 inclusive.

longitude double

Longitude in decimal degrees, from -180 through 180 inclusive.

fieldName string

Optional owner name or JSON Pointer; component errors are reported beneath it.

Returns

Result<GeoCoordinate>

A coordinate or all component validation failures.

Remarks

NaN and infinity are rejected. Without an owner, errors use /latitude and /longitude; location produces /location/latitude and /location/longitude. Existing JSON Pointers are preserved.