ST_ChangePoint function

The ST_ChangePoint function takes a curve and two points as input parameters. It replaces all occurrences of the first point in the specified curve with the second point and returns the resulting curve. The resulting geometry is represented in the spatial reference system of the specified geometry.

If the two points are not represented in the same spatial reference system as the curve, they will be converted to the spatial reference system used for the curve.

If the specified curve is empty, then an empty value is returned. If the specified curve is null, or if any of the specified points is null or empty, then null is returned.

Syntax

Parameter

curve: A value of type ST_Curve or one of its subtypes that represents the curve in which the points identified by old_point are changed tonew_point.
old_point: A value of type ST_Point that identifies the points in the curve that are changed to new_point.
new_point: A value of type ST_Point that represents the new locations of the points in the curve identified by old_point.

Return type

ST_Curve

Restrictions

The point to be changed in the curve must be one of the points used to define the curve.

If the curve has Z or M coordinates, then the specified points also must have Z or M coordinates.

Examples

Example 1

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.

The following code creates and populates the SAMPLE_LINES table.



CREATE TABLE sample_lines(id INTEGER, line ST_Linestring)

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

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

Example 2

This example changes all occurrences of the point (5, 5) to the point (6, 6) in the linestring.


SELECT cast(ST_AsText(ST_ChangePoint(line, ST_Point(5, 5),
                  ST_Point(6, 6))) as VARCHAR(100)) AS CP
FROM   sample_lines
WHERE  id=1

Result:


CP                                                                                 
---------------------------------------------------------------
LINESTRING (10 10, 6 6, 0 0, 10 0, 6 6, 0 10)

Example 3

This example changes all occurrences of the point (5, 5, 5) to the point (6, 6, 6) in the linestring.


SELECT cast(ST_AsText(ST_ChangePoint(line, ST_Point(5.0, 5.0, 5.0),
       ST_Point(6.0, 6.0, 6.0) )) as VARCHAR(100)) AS NEW
FROM   sample_lines
WHERE  id=2

Results:


NEW
----------------------------------------------------------------------

LINESTRING Z(0 0 4, 6 6 6, 10 10 6, 5 5 7)