From 95c1cc499b26bb719fdd38e58a8bf098022f5ad5 Mon Sep 17 00:00:00 2001 From: Max Gabrielsson Date: Thu, 19 Sep 2024 14:42:23 +0200 Subject: [PATCH] update st_collectionextract docs --- docs/functions.md | 25 +++++++++++++++---- .../functions/scalar/st_collectionextract.cpp | 20 +++++++++++++-- 2 files changed, 38 insertions(+), 7 deletions(-) diff --git a/docs/functions.md b/docs/functions.md index ff62170e..cc829ceb 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -16,7 +16,7 @@ | [`ST_Buffer`](#st_buffer) | Returns a buffer around the input geometry at the target distance | | [`ST_Centroid`](#st_centroid) | Calculates the centroid of a geometry | | [`ST_Collect`](#st_collect) | Collects a list of geometries into a collection geometry. | -| [`ST_CollectionExtract`](#st_collectionextract) | Extracts a sub-geometry from a collection geometry | +| [`ST_CollectionExtract`](#st_collectionextract) | Extracts geometries from a GeometryCollection into a typed multi geometry. | | [`ST_Contains`](#st_contains) | Returns true if geom1 contains geom2. | | [`ST_ContainsProperly`](#st_containsproperly) | Returns true if geom1 "properly contains" geom2 | | [`ST_ConvexHull`](#st_convexhull) | Returns the convex hull enclosing the geometry | @@ -458,19 +458,34 @@ MULTIPOINT (1 2, 3 4) #### Signatures ```sql -GEOMETRY ST_CollectionExtract (col0 GEOMETRY) -GEOMETRY ST_CollectionExtract (col0 GEOMETRY, col1 INTEGER) +GEOMETRY ST_CollectionExtract (geom GEOMETRY) +GEOMETRY ST_CollectionExtract (geom GEOMETRY, type INTEGER) ``` #### Description -Extracts a sub-geometry from a collection geometry +Extracts geometries from a GeometryCollection into a typed multi geometry. + +If the input geometry is a GeometryCollection, the function will return a multi geometry, determined by the `type` parameter. +- if `type` = 1, returns a MultiPoint containg all the Points in the collection +- if `type` = 2, returns a MultiLineString containg all the LineStrings in the collection +- if `type` = 3, returns a MultiPolygon containg all the Polygons in the collection + +If no `type` parameters is provided, the function will return a multi geometry matching the highest "surface dimension" +of the contained geometries. E.g. if the collection contains only Points, a MultiPoint will be returned. But if the +collection contains both Points and LineStrings, a MultiLineString will be returned. Similarly, if the collection +contains Polygons, a MultiPolygon will be returned. Contained geometries of a lower surface dimension will be ignored. + +If the input geometry contains nested GeometryCollections, their geometries will be extracted recursively and included +into the final multi geometry as well. + +If the input geometry is not a GeometryCollection, the function will return the input geometry as is. #### Example ```sql select st_collectionextract('MULTIPOINT(1 2,3 4)'::geometry, 1); --- POINT(1 2) +-- MULTIPOINT (1 2, 3 4) ``` ---- diff --git a/spatial/src/spatial/core/functions/scalar/st_collectionextract.cpp b/spatial/src/spatial/core/functions/scalar/st_collectionextract.cpp index 9fdee12d..78c3f7d9 100644 --- a/spatial/src/spatial/core/functions/scalar/st_collectionextract.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_collectionextract.cpp @@ -158,12 +158,27 @@ static void CollectionExtractAutoFunction(DataChunk &args, ExpressionState &stat //------------------------------------------------------------------------------ static constexpr const char *DOC_DESCRIPTION = R"( - Extracts a sub-geometry from a collection geometry +Extracts geometries from a GeometryCollection into a typed multi geometry. + +If the input geometry is a GeometryCollection, the function will return a multi geometry, determined by the `type` parameter. +- if `type` = 1, returns a MultiPoint containg all the Points in the collection +- if `type` = 2, returns a MultiLineString containg all the LineStrings in the collection +- if `type` = 3, returns a MultiPolygon containg all the Polygons in the collection + +If no `type` parameters is provided, the function will return a multi geometry matching the highest "surface dimension" +of the contained geometries. E.g. if the collection contains only Points, a MultiPoint will be returned. But if the +collection contains both Points and LineStrings, a MultiLineString will be returned. Similarly, if the collection +contains Polygons, a MultiPolygon will be returned. Contained geometries of a lower surface dimension will be ignored. + +If the input geometry contains nested GeometryCollections, their geometries will be extracted recursively and included +into the final multi geometry as well. + +If the input geometry is not a GeometryCollection, the function will return the input geometry as is. )"; static constexpr const char *DOC_EXAMPLE = R"( select st_collectionextract('MULTIPOINT(1 2,3 4)'::geometry, 1); --- POINT(1 2) +-- MULTIPOINT (1 2, 3 4) )"; static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "construction"}}; @@ -182,6 +197,7 @@ void CoreScalarFunctions::RegisterStCollectionExtract(DatabaseInstance &db) { ExtensionUtil::RegisterFunction(db, set); DocUtil::AddDocumentation(db, "ST_CollectionExtract", DOC_DESCRIPTION, DOC_EXAMPLE, DOC_TAGS); + DocUtil::AddFunctionParameterNames(db, "ST_CollectionExtract", {"geom", "type"}); } } // namespace core