From e329dab38034c273621fbab39a0792673bae8f42 Mon Sep 17 00:00:00 2001
From: ajfriend <ajfriend@gmail.com>
Date: Sat, 9 Mar 2024 15:40:01 -0800
Subject: [PATCH] Add note indicating that there is no guaranteed ordering of
 cells for many functions

---
 src/h3/api/basic_int/__init__.py | 38 +++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py
index 9113735e..b0c7e9b8 100644
--- a/src/h3/api/basic_int/__init__.py
+++ b/src/h3/api/basic_int/__init__.py
@@ -257,7 +257,7 @@ def cell_to_boundary(h):
 
 def grid_disk(h, k=1):
     """
-    Return unordered set of cells with H3 distance ``<= k`` from ``h``.
+    Return unordered collection of cells with H3 distance ``<= k`` from ``h``.
     That is, the 'filled-in' disk.
 
     Parameters
@@ -269,6 +269,10 @@ def grid_disk(h, k=1):
     Returns
     -------
     unordered collection of H3Cell
+
+    Notes
+    -----
+    There is currently no guaranteed order of the output cells.
     """
     mv = _cy.grid_disk(_in_scalar(h), k)
 
@@ -277,7 +281,7 @@ def grid_disk(h, k=1):
 
 def grid_ring(h, k=1):
     """
-    Return unordered set of cells with H3 distance ``== k`` from ``h``.
+    Return unordered collection of cells with H3 distance ``== k`` from ``h``.
     That is, the "hollow" ring.
 
     Parameters
@@ -289,6 +293,10 @@ def grid_ring(h, k=1):
     Returns
     -------
     unordered collection of H3Cell
+
+    Notes
+    -----
+    There is currently no guaranteed order of the output cells.
     """
     mv = _cy.grid_ring(_in_scalar(h), k)
 
@@ -297,7 +305,7 @@ def grid_ring(h, k=1):
 
 def cell_to_children(h, res=None):
     """
-    Children of a cell.
+    Children of a cell as an unordered collection.
 
     Parameters
     ----------
@@ -309,6 +317,10 @@ def cell_to_children(h, res=None):
     Returns
     -------
     unordered collection of H3Cell
+
+    Notes
+    -----
+    There is currently no guaranteed order of the output cells.
     """
     mv = _cy.cell_to_children(_in_scalar(h), res)
 
@@ -329,6 +341,10 @@ def compact_cells(cells):
     Returns
     -------
     unordered collection of H3Cell
+
+    Notes
+    -----
+    There is currently no guaranteed order of the output cells.
     """
     # todo: does compact_cells work on mixed-resolution collections?
     hu = _in_collection(cells)
@@ -358,6 +374,10 @@ def uncompact_cells(cells, res):
     todo: add test to make sure an error is returned when input
     contains cell smaller than output res.
     https://github.com/uber/h3/blob/master/src/h3lib/lib/h3Index.c#L425
+
+    Notes
+    -----
+    There is currently no guaranteed order of the output cells.
     """
     hc = _in_collection(cells)
     hu = _cy.uncompact_cells(hc, res)
@@ -395,6 +415,10 @@ def h3shape_to_cells(h3shape, res):
      '862830947ffffff',
      '862830957ffffff',
      '86283095fffffff'}
+
+    Notes
+    -----
+    There is currently no guaranteed order of the output cells.
     """
 
     # todo: not sure if i want this dispatch logic here. maybe in the objects?
@@ -456,6 +480,10 @@ def geo_to_cells(geo, res):
         Both H3Poly and H3MultiPoly implement the interface.
     res : int
         Resolution of desired output cells.
+
+    Notes
+    -----
+    There is currently no guaranteed order of the output cells.
     """
     h3shape = geo_to_h3shape(geo)
     return h3shape_to_cells(h3shape, res)
@@ -728,6 +756,10 @@ def get_res0_cells():
     Returns
     -------
     unordered collection of H3Cell
+
+    Notes
+    -----
+    There is currently no guaranteed order of the output cells.
     """
     mv = _cy.get_res0_cells()