Merge pull request #645 from Maxxen/main-dev

Add `st_interpolatepoint`, `st_locatealong`, `st_locatebetween`, `st_linelocatepoint`

Author: Maxxen

.clang-format

@@ -27,6 +27,7 @@ AlwaysBreakTemplateDeclarations: Yes
 IncludeBlocks: Regroup
 Language: Cpp
 AccessModifierOffset: -4
+CommentPragmas:  '^[^ ]'
 ---
 Language: Java
 SpaceAfterCStyleCast: true

docs/functions.md

@@ -63,6 +63,7 @@
 | [`ST_HasM`](#st_hasm) | Check if the input geometry has M values. |
 | [`ST_HasZ`](#st_hasz) | Check if the input geometry has Z values. |
 | [`ST_Hilbert`](#st_hilbert) | Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box. |
+| [`ST_InterpolatePoint`](#st_interpolatepoint) | Computes the closest point on a LINESTRING to a given POINT and returns the interpolated M value of that point. |
 | [`ST_Intersection`](#st_intersection) | Returns the intersection of two geometries |
 | [`ST_Intersects`](#st_intersects) | Returns true if the geometries intersect |
 | [`ST_Intersects_Extent`](#st_intersects_extent) | Returns true if the extent of two geometries intersects |
@@ -75,9 +76,12 @@
 | [`ST_Length_Spheroid`](#st_length_spheroid) | Returns the length of the input geometry in meters, using an ellipsoidal model of the earth |
 | [`ST_LineInterpolatePoint`](#st_lineinterpolatepoint) | Returns a point interpolated along a line at a fraction of total 2D length. |
 | [`ST_LineInterpolatePoints`](#st_lineinterpolatepoints) | Returns a multi-point interpolated along a line at a fraction of total 2D length. |
+| [`ST_LineLocatePoint`](#st_linelocatepoint) | Returns the location on a line closest to a point as a fraction of the total 2D length of the line. |
 | [`ST_LineMerge`](#st_linemerge) | "Merges" the input line geometry, optionally taking direction into account. |
 | [`ST_LineString2DFromWKB`](#st_linestring2dfromwkb) | Deserialize a LINESTRING_2D from a WKB encoded blob |
 | [`ST_LineSubstring`](#st_linesubstring) | Returns a substring of a line between two fractions of total 2D length. |
+| [`ST_LocateAlong`](#st_locatealong) | Returns a point or multi-point, containing the point(s) at the geometry with the given measure |
+| [`ST_LocateBetween`](#st_locatebetween) | Returns a geometry or geometry collection created by filtering and interpolating vertices within a range of "M" values |
 | [`ST_M`](#st_m) | Returns the M coordinate of a point geometry |
 | [`ST_MMax`](#st_mmax) | Returns the maximum M coordinate of a geometry |
 | [`ST_MMin`](#st_mmin) | Returns the minimum M coordinate of a geometry |
@@ -1491,6 +1495,24 @@ For the BOX_2D and BOX_2DF variants, the center of the box is used as the point
 
 ----
 
+### ST_InterpolatePoint
+
+
+#### Signature
+
+```sql
+DOUBLE ST_InterpolatePoint (line GEOMETRY, point GEOMETRY)
+```
+
+#### Description
+
+Computes the closest point on a LINESTRING to a given POINT and returns the interpolated M value of that point.
+
+First argument must be a linestring and must have a M dimension. The second argument must be a point. 
+Neither argument can be empty.
+
+----
+
 ### ST_Intersection
 
 
@@ -1683,6 +1705,21 @@ otherwise, the result is a multi-point with points repeated at the fraction inte
 
 ----
 
+### ST_LineLocatePoint
+
+
+#### Signature
+
+```sql
+DOUBLE ST_LineLocatePoint (line GEOMETRY, point GEOMETRY)
+```
+
+#### Description
+
+Returns the location on a line closest to a point as a fraction of the total 2D length of the line.
+
+----
+
 ### ST_LineMerge
 
 
@@ -1729,6 +1766,52 @@ Returns a substring of a line between two fractions of total 2D length.
 
 ----
 
+### ST_LocateAlong
+
+
+#### Signatures
+
+```sql
+GEOMETRY ST_LocateAlong (line GEOMETRY, measure DOUBLE, offset DOUBLE)
+GEOMETRY ST_LocateAlong (line GEOMETRY, measure DOUBLE)
+```
+
+#### Description
+
+Returns a point or multi-point, containing the point(s) at the geometry with the given measure
+
+For a LINESTRING, or MULTILINESTRING, the location is determined by interpolating between M values
+For a POINT and MULTIPOINT, the point is returned if the measure matches the M value of the vertex, otherwise an empty geometry is returned
+For a POLYGON, only the exterior ring is considered, and treated as a LINESTRING
+
+If offset is provided, the resulting point(s) is offset by the given amount perpendicular to the line direction.
+
+----
+
+### ST_LocateBetween
+
+
+#### Signatures
+
+```sql
+GEOMETRY ST_LocateBetween (line GEOMETRY, start_measure DOUBLE, end_measure DOUBLE, offset DOUBLE)
+GEOMETRY ST_LocateBetween (line GEOMETRY, start_measure DOUBLE, end_measure DOUBLE)
+```
+
+#### Description
+
+Returns a geometry or geometry collection created by filtering and interpolating vertices within a range of "M" values
+
+Creates a geometry or geometry collection, containing the parts formed by vertices that have an "M" value within the "start_measure" and "end_measure" range
+
+For LINESTRING or MULTILINESTRING, if a line segment would cross either the upper or lower bound, a vertex is added by interpolating the coordinates at the "intersection"
+For a POINT and MULTIPOINT, the point is added to the collection if its vertex has an "M" value within the range, otherwise it is skipped
+For a POLYGON, only the exterior ring is considered, and treated like a LINESTRING
+
+If offset is provided, the resulting vertices are offset by the given amount perpendicular to the line direction.
+
+----
+
 ### ST_M