Chubrik.LatLng64 1.0.0

LatLng64

A 64-bit struct that packs [latitude, longitude] into a single ulong with ±2.8 mm precision in populated latitudes and ±5.6 mm in polar zones. Decodes to clean decimals. Half the size of a (double, double) pair; ideal for geographic databases.

Install

dotnet add package Chubrik.LatLng64

Targets net8.0 and netstandard2.0. Both builds implement IEquatable<LatLng64>, IComparable, IComparable<LatLng64>, and IFormattable. The net8.0 build adds ISpanFormattable, IParsable<LatLng64>, ISpanParsable<LatLng64>, IUtf8SpanFormattable, and IUtf8SpanParsable<LatLng64>.

Quick start

using Chubrik.LatLng64;

var coord = new LatLng64(55.7558, 37.6173);
var (lat, lng) = coord.GetCoordinates();

// Persist as a single 64-bit value (great for a database column)
ulong raw = coord.Data;
var restored = LatLng64.FromData(raw);

API at a glance

Database storage

The Data property is a stable ulong — bytes are platform-independent and round-trip on any process. Entity Framework Core:

modelBuilder.Entity<Place>()
    .Property(p => p.Location)
    .HasConversion(v => v.Data, raw => LatLng64.FromData(raw));

JSON serialization

System.Text.Json doesn’t serialize LatLng64 out of the box. A small converter handles it — Data is wrapped as a JSON string to keep precision through JavaScript’s Number type (values exceed 2^53):

public sealed class LatLng64JsonConverter : JsonConverter<LatLng64>
{
    public override LatLng64 Read(
        ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
        => LatLng64.FromData(ulong.Parse(reader.GetString()!, CultureInfo.InvariantCulture));

    public override void Write(
        Utf8JsonWriter writer, LatLng64 value, JsonSerializerOptions options)
        => writer.WriteStringValue(value.Data.ToString(CultureInfo.InvariantCulture));
}

Register it via [JsonConverter(typeof(LatLng64JsonConverter))] on a property, or globally via JsonSerializerOptions.Converters.

Note: serializing a default(LatLng64) writes {"Data":"0"} and fails to deserialize back — initialize values before persisting.

Notes

• default(LatLng64) is intentionally invalid. Calling GetCoordinates, ToString, or TryFormat on it throws InvalidOperationException — uninitialized values fail loudly instead of silently mapping to (0, 0).
• NaN and ±Infinity are rejected. Constructor throws ArgumentOutOfRangeException; Parse throws OverflowException (TryParse returns false). Latitude must be in [−90, +90], longitude in [−180, +180].
• Parse / ToString are culture-sensitive. A null provider resolves to CultureInfo.CurrentCulture (not Invariant). Cultures with a , decimal separator use ; as the pair separator: "55,7558; 37,6173". For cross-machine text round-trips, pass an explicit CultureInfo — typically Invariant.
• CompareTo is not a spatial order. Orders by raw Data — deterministic and useful for sorting and database indexing, but geographically close points may be far apart in this order.

Precision by zone

The 64-bit budget is split unevenly across seven zones so that linear precision stays within ±2.8 mm in populated latitudes and ±5.6 mm in polar zones. Coarser angular longitude steps in higher zones compensate for the shrinking longitudinal degree (cos lat).

The split is asymmetric on purpose: only northern mid-latitudes host populated land; the southern counterpart is mostly open ocean, so the Antarctic zone absorbs the whole −60° … −85° range at coarser steps.

Comparison

License

Released under the MIT License.