# WL#14160: ST_LineInterpolatePoint

This WL implements a new function, ST_LineInterpolatePoint(*linestring*, *fractional_distance*), that takes a linestring and a fractional distance in the range [0.0, 1.0] and returns the point along that linestring at that distance from the starting point.

The function is implemented for linestrings in all spatial reference systems, both Cartesian and geographic.

Example use case: ST_LineInterpolatePoint is used to find points along a line, e.g., along a road or along a recording av a GPS tracked vehicle. At which point will the user be half way: ST_LineInterpolatePoint(<line>, 0.5).

- F-1
- The function MUST return NULL if any of its arguments are NULL.
- F-2
- If the geometry argument is not a syntactically well-formed geometry, the function MUST raise ER_GIS_INVALID_DATA during function evaluation.
- F-3
- If the geometry argument is a syntactically well-formed geometry in an undefined SRS, the function MUST raise ER_SRS_NOT_FOUND during function evaluation.
- F-4
- If the geometry argument is a syntactically well-formed geometry but not a linestring, the function MUST raise ER_UNEXPECTED_GEOMETRY_TYPE during function evaluation.
- F-5
- If the geometry argument is a geometry in a geographic SRS and a longitude value is not in the range (-180,180] (in degrees -- other limits in other units), the function MUST raise ER_GEOMETRY_PARAM_LONGITUDE_OUT_OF_RANGE. (*)
- F-6
- If the geometry argument is a geometry in a geographic SRS and a latitude value is not in the range [-90,90] (in degrees -- other limits in other units), the function MUST raise ER_GEOMETRY_PARAM_LATITUDE_OUT_OF_RANGE. (*)
- F-7
- If the fractional distance parameter is outside the range [0.0, 1.0], the function MUST raise ER_DATA_OUT_OF_RANGE during function evaluation.
- F-8
- If the geometry argument is a syntactically well-formed linestring and the fractional distance parameter is within the range [0.0, 1.0], the function MUST return the point at that distance from the starting point of the linestring along the linestring, measured in fraction of the total length of the linestring.
- F-9
- If the geometry argument is a syntactically well-formed linestring in a geographic SRS and the fractional_distance is 1.0 then the result may not be exactly the last point of the linestring but a point close to it due to numerical inaccuracies in the computation.
- F-10
- The return type of the function MUST be POINT.

(*) The exact limits will deviate slightly because of floating point arithmetics.

- I-1
- The syntax of interface SQL01 is extended with function ST_LineInterpolatePoint(
*linestring*,*fractional_length*). - I-2
- No new errors.
- I-3
- No new warnings.

## Item_func_st_lineinterpolatepoint

The Item_func_st_lineinterpolatepoint class implements the SQL level ST_LineInterpolatePoint function. The class is placed in sql/item_geofunc.{h,cc}. Class declarations and definitions are supposed to be sorted in alphabetical order in these files.

A link between the SQL level function name and class is added to sql/item_create.cc.

The SQL level function interface is tested by an MTR test in mysql-test/suite/gis/t/st_lineinterpolatepoint.test.

## gis::line_interpolate_point and gis::Line_interpolate_point

The gis::Line_interpolate_point functor (sql/gis/line_interpolate_functor.{h,cc}) and gis::line_interpolate_point function (sql/gis/line_interpolate.{h,cc}) implement the interface to the Boost Geometry line_interpolate function. The functor may throw exceptions, while the function is declared nothrow and will wrap the functor in try-catch and translate exceptions to my_error calls.

The function is unit tested by tests in unittest/gunit/gis_line_interpolate_point-t.cc. These tests handle boundary testing that don't affect the SQL level interface.