12.17.7.3 LineString and MultiLineString Property Functions

A LineString consists of Point values. You can extract particular points of a LineString, count the number of points that it contains, or obtain its length.

Some functions in this section also work for MultiLineString values.

• EndPoint(ls)

  ST_EndPoint() and EndPoint() are synonyms. For more information, see the description of ST_EndPoint().

• GLength(ls)

  Returns a double-precision number indicating the length of the LineString or MultiLineString value ls in its associated spatial reference. The length of a MultiLineString value is equal to the sum of the lengths of its elements. If the argument is NULL or an empty geometry, the return value is NULL.

  mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
  mysql> SELECT GLength(GeomFromText(@ls));
  +----------------------------+
  | GLength(GeomFromText(@ls)) |
  +----------------------------+
  |         2.8284271247461903 |
  +----------------------------+
  
  mysql> SET @mls = 'MultiLineString((1 1,2 2,3 3),(4 4,5 5))';
  mysql> SELECT GLength(GeomFromText(@mls));
  +-----------------------------+
  | GLength(GeomFromText(@mls)) |
  +-----------------------------+
  |           4.242640687119286 |
  +-----------------------------+

  GLength() is a nonstandard name. It corresponds to the OpenGIS Length() function. (There is an existing SQL function Length() that calculates the length of string values.)

• IsClosed(ls)

  ST_IsClosed() and IsClosed() are synonyms. For more information, see the description of ST_IsClosed().

• NumPoints(ls)

  ST_NumPoints() and NumPoints() are synonyms. For more information, see the description of ST_NumPoints().

• PointN(ls, N)

  ST_PointN() and PointN() are synonyms. For more information, see the description of ST_PointN().

• ST_EndPoint(ls)

  Returns the Point that is the endpoint of the LineString value ls. If the argument is NULL or an empty geometry, the return value is NULL.

  mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
  mysql> SELECT ST_AsText(ST_EndPoint(ST_GeomFromText(@ls)));
  +----------------------------------------------+
  | ST_AsText(ST_EndPoint(ST_GeomFromText(@ls))) |
  +----------------------------------------------+
  | POINT(3 3)                                   |
  +----------------------------------------------+

  ST_EndPoint() and EndPoint() are synonyms.

• ST_IsClosed(ls)

  For a LineString value ls, ST_IsClosed() returns 1 if ls is closed (that is, its ST_StartPoint() and ST_EndPoint() values are the same). If the argument is NULL or an empty geometry, the return value is NULL.

  For a MultiLineString value ls, ST_IsClosed() returns 1 if ls is closed (that is, the ST_StartPoint() and ST_EndPoint() values are the same for each LineString in ls).

  ST_IsClosed() returns 0 if ls is not closed.

  mysql> SET @ls1 = 'LineString(1 1,2 2,3 3,2 2)';
  mysql> SET @ls2 = 'LineString(1 1,2 2,3 3,1 1)';
  
  mysql> SELECT ST_IsClosed(ST_GeomFromText(@ls1));
  +------------------------------------+
  | ST_IsClosed(ST_GeomFromText(@ls1)) |
  +------------------------------------+
  |                                  0 |
  +------------------------------------+
  
  mysql> SELECT ST_IsClosed(ST_GeomFromText(@ls2));
  +------------------------------------+
  | ST_IsClosed(ST_GeomFromText(@ls2)) |
  +------------------------------------+
  |                                  1 |
  +------------------------------------+
  
  mysql> SET @ls3 = 'MultiLineString((1 1,2 2,3 3),(4 4,5 5))';
  
  mysql> SELECT ST_IsClosed(ST_GeomFromText(@ls3));
  +------------------------------------+
  | ST_IsClosed(ST_GeomFromText(@ls3)) |
  +------------------------------------+
  |                                  0 |
  +------------------------------------+

  ST_IsClosed() and IsClosed() are synonyms.

• ST_NumPoints(ls)

  Returns the number of Point objects in the LineString value ls. If the argument is NULL or an empty geometry, the return value is NULL.

  mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
  mysql> SELECT ST_NumPoints(ST_GeomFromText(@ls));
  +------------------------------------+
  | ST_NumPoints(ST_GeomFromText(@ls)) |
  +------------------------------------+
  |                                  3 |
  +------------------------------------+

  ST_NumPoints() and NumPoints() are synonyms.

• ST_PointN(ls, N)

  Returns the N-th Point in the Linestring value ls. Points are numbered beginning with 1. If any argument is NULL or the geometry argument is an empty geometry, the return value is NULL.

  mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
  mysql> SELECT ST_AsText(ST_PointN(ST_GeomFromText(@ls),2));
  +----------------------------------------------+
  | ST_AsText(ST_PointN(ST_GeomFromText(@ls),2)) |
  +----------------------------------------------+
  | POINT(2 2)                                   |
  +----------------------------------------------+

  ST_PointN() and PointN() are synonyms.

• ST_StartPoint(ls)

  Returns the Point that is the start point of the LineString value ls. If the argument is NULL or an empty geometry, the return value is NULL.

  mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
  mysql> SELECT ST_AsText(ST_StartPoint(ST_GeomFromText(@ls)));
  +------------------------------------------------+
  | ST_AsText(ST_StartPoint(ST_GeomFromText(@ls))) |
  +------------------------------------------------+
  | POINT(1 1)                                     |
  +------------------------------------------------+

  ST_StartPoint() and StartPoint() are synonyms.

• StartPoint(ls)

  ST_StartPoint() and StartPoint() are synonyms. For more information, see the description of ST_StartPoint().