# `Geometry`

Any one of the six shapes: a point, a path, an area or a set of any of those.

Use it when one field must hold whichever shape comes in, such as uploaded map data. When you know the shape, use that type, since the compiler then checks it.

## Shape

One of these, each with its own fields:

| Variant | Field | Type | Required? |
|---|---|---|---|
| `Geometry.point` | `point` | [`Point`](/docs/types/type-point.md) | Yes |
| `Geometry.line_string` | `line_string` | [`LineString`](/docs/types/type-line-string.md) | Yes |
| `Geometry.polygon` | `polygon` | [`Polygon`](/docs/types/type-polygon.md) | Yes |
| `Geometry.multi_point` | `multi_point` | [`MultiPoint`](/docs/types/type-multi-point.md) | Yes |
| `Geometry.multi_line_string` | `multi_line_string` | [`MultiLineString`](/docs/types/type-multi-line-string.md) | Yes |
| `Geometry.multi_polygon` | `multi_polygon` | [`MultiPolygon`](/docs/types/type-multi-polygon.md) | Yes |

## Example

```jadpo
Geometry.point { point: Point { latitude: 51.5072 longitude: -0.1276 altitude: none } }
```

These operations give one: `geo.from_geojson` and `geo.from_wkt`.

## Good to know

- `geo.from_geojson` and `geo.from_wkt` read one from outside text.
- `match` takes it apart, with one arm for each shape.
- `==` tells you whether two are the same. `<` and `list.sort_by` don't take it.

## In JSON

A GeoJSON geometry, with each position's longitude first, in a request, a response or `json.write`:

```json
{"type":"Point","coordinates":[-0.1276,51.5072]}
{"type":"LineString","coordinates":[[0,0],[1,1]]}
{"type":"Polygon","coordinates":[[[0,0],[1,0],[1,1],[0,1],[0,0]]]}
```

## Details

<details>
<summary>Text form, storage, how it is shown, and operations</summary>

`Geometry` is in the group Geospatial, and has been in Jadpo since 0.1.0.

### Text form

It has no single text form, so `text.from` and `text.parse` don't take it.

### How it is stored

It is stored in one column named for the field, of type `geography`. `{"type":"MultiPoint","coordinates":[[0,0],[1,1]]}` is stored as `'SRID=4326;MULTIPOINT (0 0, 1 1)'::geography`.

### How it is shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `{"type":"Point","coordinates":[-0.1276,51.5072]}` | `51.5072° N, 0.1276° W` |
| `{"type":"LineString","coordinates":[[0,0],[1,1]]}` | `(0°, 0°; 1° N, 1° E)` |
| `{"type":"Polygon","coordinates":[[[0,0],[1,0],[1,1],[0,1],[0,0]]]}` | `((0°, 0°; 0°, 1° E; 1° N, 1° E; 1° N, 0°; 0°, 0°))` |
| `{"type":"MultiPoint","coordinates":[[0,0],[1,1]]}` | `(0°, 0°; 1° N, 1° E)` |
| `{"type":"MultiLineString","coordinates":[[[0,0],[1,1]]]}` | `((0°, 0°; 1° N, 1° E))` |
| `{"type":"MultiPolygon","coordinates":[[[[0,0],[1,0],[1,1],[0,1],[0,0]]]]}` | `(((0°, 0°; 0°, 1° E; 1° N, 1° E; 1° N, 0°; 0°, 0°)))` |

### Operations

- `geo.bounding_box(shape: T) -> BoundingBox`: The smallest box of parallels and meridians holding the shape, an edge's highest or lowest point counted, across the antimeridian when that box is narrower; a shape holding a pole runs from -180 to 180.
- `geo.centroid(shape: T) -> Point`: The shape's centre on the sphere, as PostGIS's `ST_Centroid(x, false)` finds it: each point a unit vector, weighted by area, length or count by the shape's kind, summed, and back to latitude and longitude. It may lie outside a concave polygon.
- `geo.contains(a: T, b: U) -> Bool`: Whether no point of `b` lies outside `a`, edges included. `a` may be a `BoundingBox`, whose sides are compared directly, or a `Circle`, holding the points within its radius of its centre.
- `geo.from_geojson(text: Text) -> Geometry`: The geometry GeoJSON text (RFC 7946) writes, each position longitude first: `{"type":"Point","coordinates":[-0.1276,51.5072]}`, any of the six, held as the `Geometry` of its kind, each ring wound by the right-hand rule. A coordinate out of its range fails with `out_of_range`, and text that isn't one of the six geometries, a polygon whose rings aren't valid or a geometry mixing altitudes included, with `malformed`, which the call's `attempt` maps.
- `geo.from_wkt(text: Text) -> Geometry`: The geometry WKT or EWKT text writes, longitude first: `POLYGON((-0.2 51.49,-0.05 51.49,-0.05 51.54,-0.2 51.49))`, any of the six, with `Z` for an altitude, held as the `Geometry` of its kind. `SRID=4326;` may lead; another system, or a coordinate out of its range, fails with `out_of_range`, and text that isn't one of the six geometries, a polygon whose rings aren't valid included, with `malformed`, which the call's `attempt` maps.
- `geo.intersects(a: T, b: U) -> Bool`: Whether the two share at least one point, edges included.
- `geo.to_wkt(shape: T) -> Text`: The shape as WKT, longitude first, as PostGIS's `ST_AsText` writes it: `POINT(-0.1276 51.5072)`, `POINT Z (-0.1276 51.5072 35)` with an altitude, each ring in the order it holds its points.
- `geo.within(a: T, b: U, distance: Length?) -> Bool`: `geo.contains(b, a)`; or, with `distance:`, whether two points are at most that far apart, as `geo.distance` measures them.

It also takes `text.format`, `json.read`, `json.write` and `==`. [How every standard type behaves](/docs/every-standard-type-meets-one-contract.md) says how they work.

</details>