ENH: add is_empty (#79)

* ENH: add is_empty * add to docs * consistency fixes for modules and API doc --------- Co-authored-by: Benoit Bovy <benbovy@gmail.com>
benbovy · Feb 4, 2025 · 4f52729 · 4f52729
1 parent 5b58ec9
commit 4f52729
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 1 deletion.
diff --git a/docs/api.rst b/docs/api.rst
@@ -20,6 +20,7 @@ objects without side-effects (except for ``prepare`` and ``destroy_prepared``).
    is_geography
    get_dimension
    get_type_id
+   is_empty
    get_x
    get_y
    is_prepared

diff --git a/src/geography.cpp b/src/geography.cpp
@@ -223,6 +223,10 @@ std::int8_t get_type_id(PyObjectGeography obj) {
     return static_cast<std::int8_t>(obj.as_geog_ptr()->geog_type());
 }
 
+bool is_empty(PyObjectGeography obj) {
+    return s2geog::s2_is_empty(obj.as_geog_ptr()->geog());
+}
+
 int get_dimension(PyObjectGeography obj) {
     // note: in case of a collection with features of different dimensions:
     // - Geography::dimension() returns -1
@@ -357,7 +361,27 @@ void init_geography(py::module &m) {
 
     )pbdoc");
 
-    m.def("get_dimension", py::vectorize(&get_dimension), py::arg("geography"), R"pbdoc(
+    m.def("is_empty",
+          py::vectorize(&is_empty),
+          py::arg("geography"),
+          py::pos_only(),
+          R"pbdoc(is_empty(geography, /)
+
+        Returns True if the geography object is empty, False otherwise.
+
+        Parameters
+        ----------
+        a : :py:class:`Geography` or array_like
+            Geography object(s).
+
+    )pbdoc");
+
+    m.def("get_dimension",
+          py::vectorize(&get_dimension),
+          py::arg("geography"),
+          py::pos_only(),
+          R"pbdoc(get_dimension(geography, /)
+
         Returns the inherent dimensionality of a geography.
 
         Parameters

diff --git a/src/spherely.pyi b/src/spherely.pyi
@@ -219,6 +219,7 @@ is_geography: _VFunc_Nin1_Nout1[Literal["is_geography"], bool, bool]
 is_prepared: _VFunc_Nin1_Nout1[Literal["is_prepared"], bool, bool]
 prepare: _VFunc_Nin1_Nout1[Literal["prepare"], Geography, Any]
 destroy_prepared: _VFunc_Nin1_Nout1[Literal["destroy_prepared"], Geography, Any]
+is_empty: _VFunc_Nin1_Nout1[Literal["is_empty"], bool, bool]
 
 # predicates
 

diff --git a/tests/test_accessors.py b/tests/test_accessors.py
@@ -87,6 +87,24 @@ def test_convex_hull(geog, expected) -> None:
     assert spherely.equals(actual, expected)
 
 
+def test_is_empty():
+    arr = spherely.from_wkt(
+        [
+            "POINT (0 0)",
+            "POINT EMPTY",
+            "LINESTRING (0 0, 1 1)",
+            "LINESTRING EMPTY",
+            "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))",
+            "POLYGON EMPTY",
+            "GEOMETRYCOLLECTION EMPTY",
+            "GEOMETRYCOLLECTION (POINT EMPTY)",
+        ]
+    )
+    result = spherely.is_empty(arr)
+    expected = np.array([False, True, False, True, False, True, True, True])
+    np.testing.assert_array_equal(result, expected)
+
+
 @pytest.mark.parametrize(
     "geog_a, geog_b, expected",
     [