WL#12657: ST_Length with unit

Affects: Server-8.0   —   Status: Complete   —   Priority: Medium

ST_Length currently takes one parameter -- the geometry to compute the length of. This WL implements a second, optional, parameter that names the unit of length to use in the result, conforming with SQL/MM Part 3 Spatial (ISO/IEC 13249-3:2015), Sect. 5.1.41.

F-1
ST_Length SHALL return NULL if any argument is NULL.
F-2
ST_Length SHALL NOT return NULL if the first argument is a MULTILINSTRING or and LINESTRING and the second argument is not NULL.
F-3 a)
If a linear unit is specified, the unit is supported by MySQL (*), and the SRID is 0, ST_Length MUST raise ER_GEOMETRY_IN_UNKNOWN_LENGTH_UNIT.
F-3 b)
If a linear unit is specified, the unit is supported by MySQL (*), and the SRID is not 0, the result of ST_Length MUST be in that unit.
F-4
If the unit is specified, but is not supported by MySQL (*), ST_Length MUST raise ER_UNIT_NOT_FOUND.
F-5
If a unit is not specified and the geometry parameter are in a Cartesian SRS, the result of ST_Length MUST be in the unit of the SRS of the geometry.
F-6
If a unit is not specified and the geometry parameter are in a geographic SRS, the result of ST_Length MUST be in meters.
  • Supported unit are listed in the view INFORMATION_SCHEMA.ST_UNITS_OF_MEASURE.
I-1
No new files.
I-2
No new syntax.
I-3
No new commands.
I-4
No new tools.
I-5
Interface SQL01 is extended: Function ST_Length is extended with a new, optional, parameter specifying a linear unit of measure (as a text string). If specified, the result will be in this unit. This is a pure extension. Existing behavior is not affected.

ST_Length

Extend the item and structures in item_create.cc to take an optional second parameter, using SQL_FN_V_LIST.

The conversion path is added at the end of Item_func_st_length::val_real(), checking and using the unit argument only if the calculation succeeds. The method used for finding the unit conversion factor is the same as introduced and used in WL#11000 for ST_Distance with unit: a map from strings to unit information.