ST_AppendPoint function

The ST_AppendPoint function takes a curve and a point as input parameters and extends the curve by the specified point. If the specified curve has Z or M coordinates, then the point must also have Z or M coordinates. The resulting curve is represented in the spatial reference system of the specified curve.

If the point to be appended is not represented in the same spatial reference system as the curve, it will be converted to the other spatial reference system.

If the specified curve is closed or simple, the resulting curve might not be closed or simple anymore. If the specified curve or point is null, or if the curve is empty, then null is returned. If the point to be appended is empty, then the specified curve is returned unchanged and a warning is raised (SQLSTATE 01HS3).

Syntax

Parameter

curve: A value of type ST_Curve or one of its subtypes that represents the curve to which point will be appended.
point: A value of type ST_Point that represents the point that is appended to curve.

Return type

ST_Curve

Examples

In the following examples, the lines of results have been reformatted for readability. The spacing in your results will vary according to your online display.

This code creates two linestrings, each with three points.



CREATE TABLE sample_lines(id integer, line ST_Linestring)

INSERT INTO sample_lines VALUES
    (1, ST_LineString('linestring (10 10, 10 0, 0 0 )', 0) )

INSERT INTO sample_lines VALUES
    (2, ST_LineString('linestring z (0 0 4, 5 5 5, 10 10 6)', 0) )

Example 1

This example adds the point (5, 5) to the end of a linestring.


SELECT CAST(ST_AsText(ST_AppendPoint(line, ST_Point(5, 5, 0))) 
    AS VARCHAR(70)) New
FROM   sample_lines
WHERE  id=1

Results:


NEW
--------------------------------------------------------------
LINESTRING (10 10, 10 0, 0 0, 5 5)

Example 2

This example adds the point (15, 15, 7) to the end of a linestring with Z coordinates.


SELECT CAST(ST_AsText(ST_AppendPoint(line, ST_Point(15.0, 15.0, 7.0, 0))) 
   AS VARCHAR(70)) New
FROM   sample_lines
WHERE  id=2

Results:


NEW
----------------------------------------------------------------
LINESTRING Z(0 0 4, 5 5 5, 10 10 6, 15 15 7)