Add support for geospatial queries

[nirinchev]

Description

Fixes #3299

Summary

Adds initial support for geo queries. In this first version, we're not introducing new datatypes, so users will need to make sure their own types conform to the shape expected for geo queries. We're providing a few helper shapes to write queries against, though those can only be used for querying and cannot be stored in the database.

Example point definition

public partial class CustomGeoPoint : TestEmbeddedObject
{
    [MapTo("coordinates")]
    private IList<double> Coordinates { get; } = null!;

    [MapTo("type")]
    private string Type { get; set; } = "Point";

    public double Latitude => Coordinates.Count > 1 ? Coordinates[1] : throw new Exception($"Invalid coordinate array. Expected at least 2 elements, but got: {Coordinates.Count}");

    public double Longitude => Coordinates.Count > 1 ? Coordinates[0] : throw new Exception($"Invalid coordinate array. Expected at least 2 elements, but got: {Coordinates.Count}");

    public CustomGeoPoint(double latitude, double longitude)
    {
        Coordinates.Add(longitude);
        Coordinates.Add(latitude);
    }
}

Example query

var circle = new GeoCircle((23.459, 49.983), Distance.FromKilometers(10));

// Above example uses implicit conversion from a tuple to GeoPoint, you can also use the explicit one
var circle = new GeoCircle(new GeoPoint(latitude: 23.459, longitude: 49.983), Distance.FromKilometers(10));

// Construct a polygon from a collection of points. First and last one need to be the same
// in order to close the polygon.
var polygon = new GeoPolygon((10, 10), (10, 20), (0, 20), (10, 10));

// Construct a polygon with holes
var outerRing = new GeoPoint[] { (10, 10), (10, 20), (0, 20), (10, 10));
var hole1 = new GeoPoint[] { (1, 1), (1, 2), (0, 2), (1, 1));
var hole2 = new GeoPoint[] { (5, 5), (5, 6), (4, 6), (5, 5));
var polygon = new GeoPolygon(outerRing, hole1, hole2);

// Construct a box from bottom left and top right corners
var box = new GeoBox(bottomLeftCorner: (0, 0), topRightCorner: (10, 10));

// Query using LINQ
var query = realm.all<Company>().Where(c => QueryMethods.GeoWithin(c.Location, circle));

// Query using RQL
var query = realm.All<Company>().Filter("Location geoWithin $0", circle);

TODO

• Changelog entry
• Tests (if applicable)

[coveralls]

Pull Request Test Coverage Report for Build 5188514108

• 215 of 218 (98.62%) changed or added relevant lines in 19 files are covered.
• 3 unchanged lines in 1 file lost coverage.
• Overall coverage increased (+0.4%) to 82.288%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
Realm/Realm/DatabaseTypes/QueryArgument.cs	55	56	98.21%
Realm/Realm/Linq/RealmResultsVisitor.cs	10	11	90.91%
Realm/Realm/Native/Queries/NativeQueryArgument.cs	27	28	96.43%

Files with Coverage Reduction	New Missed Lines	%
Realm/Realm/Handles/SubscriptionSetHandle.cs	3	95.41%

Totals
Change from base Build 5142624676:	0.4%
Covered Lines:	6120
Relevant Lines:	7295

---

💛 - Coveralls

[papafe]

In the docs for the class it says that each ring needs to have at least 3 points, not 4

[nirinchev]

The docs say 3 distinct points and the first and the last must match, implying at least 4 points.

[papafe]

Same here, I thought in this case the polygon would be considered close anyways

[nirinchev]

That was the case at some point, but Core changed it, so we now need to explicitly close the polygon. Will update the docs.

[nirinchev]

Actually, I can see that MongoDB is more relaxed than GeoJSON, so might be worth doing it for the SDKs as well.

[papafe]

Apart from those few notes it looks fine