Linestring Functions

{{ocientgeo}} linestring functions can perform alterations or access descriptive information on linestring objects st addpoint adds a point to the given linestring at the specified 0 indexed location syntax st addpoint(geo linestring, geo point to add \[, location ] ) argument data type description geo linestring linestring a linestring to be altered by adding the geo point to add at a specified location the function throws an error if geo linestring is any data type except for linestring or null geo point to add point a point value to be added to the geo linestring location integer optional represents a numeric 0 indexed location in the geo linestring where geo point to add is appended if you do not specify this value, the function defaults to appending the geo point to add argument to the end of geo linestring a location value of 1 also appends to the end the function throws an error if the location argument is outside the bounds of the geo linestring or if it is a value of less than 1 example select st addpoint( st linestring('linestring(1 2, 1 3)'), st point(1, 4), 1\); output linestring(1 000000 2 000000, 1 000000 4 000000, 1 000000 3 000000) st endpoint returns the endpoint of a specified linestring the returned value is a point syntax st endpoint(geo) argument data type description geo linestring a line to be computed to return its endpoint if this value is a polygon , point , or is empty, then the function returns null if this value is a non geospatial type, the function throws an error example select st endpoint(st linestring('linestring(1 2, 1 3, 1 4)')); output point(1,4) st lineinterpolatepoint returns a point along a linestring based on a specified fraction of its total length syntax st lineinterpolatepoint(line, fraction) argument data type description line linestring a line used to compute an interpolated point fraction double a decimal value between 0 and 1 that represents a fraction of the total length of the line the function returns a point at this fraction of the length the function throws an error if this value is not between 0 and 1 example in this example, the function computes a point halfway (0 5) along the specified line select st lineinterpolatepoint(st linestring('linestring(1 2, 2 1)'), 0 5); output point(1 5 1 5) st linelocatepoint similar to /#stlineinterpolatepoint , this function computes a fraction based on where a specified point is located along the length of a specified linestring syntax st linelocatepoint(line, point) argument data type description line linestring a linestring used to compute a fraction based off the interpolated point value point point a point used to calculate a fraction based on where it is located along the line value if the function cannot interpolate this value from the line , the function returns 0 0 example in this example, the function computes a fraction that represents where the point (1 5, 1 5) lies along the line select st linelocatepoint( st linestring('linestring(1 2, 2 1)'), st point(1 5, 1 5)); output 0 5 st linesubstring returns a linestring that is a substring of a specified line that starts and ends at the specified fractions of its total length syntax st linesubstring(line, start fraction, end fraction) argument data type description line linestring a linestring used to compute a substring line based on the start fraction and end fraction values start fraction double a decimal value between 0 and 1 that represents a fractional point of the total length of the line the function uses this fractional point as the start point for the substring the function throws an error if the start fraction is greater than the end fraction end fraction double a decimal value between 0 and 1 that represents a fractional point of the total length of line the function uses this fractional point as the endpoint for the substring example in this example, the function generates a subsection of the provided linestring, spanning from the start fraction value (0 5) that represents the halfway point of the original linestring, to the end fraction value (1 0) that represents the endpoint select st linesubstring(st linestring('linestring(1 2, 2 1)'), 0 5, 1 0); output linestring(1 50 1 50, 2 0 1 0) st pointn returns the point value at a specified index of the specified linestring if out of bounds, the function returns null syntax st pointn(geo, index) argument data type description geo linestring a linestring that is used to return one of its point values if you specify a point or polygon value, this function returns null index integer an index location of one of the point values in the geo value this is one based, meaning the first index location starts at 1 negative values count backward from the end of the linestring in other words, an index value of 1 returns that last point value example select st pointn( st linestring( st point \[]\(st point(1, 2), st point(1, 3), st point(1, 4))), 3\); output st point(1,4) st removepoint removes a point value at a specified index from the specified line syntax st removepoint(geo, index) argument data type description geo linestring a linestring that is to be altered by removing one of its point values index integer an index of one of the point values in the geo value this is zero based, meaning the first index location starts at 0 and the last index is length(geo) 1 example select st removepoint(st linestring('linestring(1 2, 1 3, 1 4)'), 1); output linestring(1 0 2 0, 1 0 4 0) st setpoint replaces a point value in a specified linestring at a specified index the function returns the altered linestring with the replaced point syntax st setpoint(geo, index, geo point to replace) argument data type description geo linestring a linestring that is to be altered with a new point value index integer an index location of one of the point values in the geo linestring this is zero based, meaning the first index location starts at 0 negative values count backward from the end of the geo value in other words, an index value of 1 returns the last point value geo point to replace point a point value to replace the value at the specified index location if this value is not a point type or null, the function throws an error example in this example, the function replaces the point value located at the 2 index location, meaning it is the second from the last in the sequence select st setpoint( st linestring('linestring(1 2, 1 3, 1 4)'), 2, st point(1, 5)); output linestring(1 000000 2 000000, 1 000000 5 000000, 1 000000 4 000000) st startpoint returns the starting point value of the line if this value is empty, the function returns null if you specify a polygon , point , or null, then the function returns null if you specify a non geography value, the function throws an error syntax st startpoint(geo) argument data type description geo linestring a line to be computed to return its starting point if this value is a polygon , point , or is empty, then the function returns null if this value is a non geospatial type, the function throws an error example select st startpoint(st linestring('linestring(1 2, 1 3, 1 4)')); output st point(1,2) related links docid\ ogtviwl gtbgv0chhrh 3 docid 276iafpj50xtsav3j0fte