Add new function search_sheet (#8)

- Update unit tests and docs for the function

Author: miaoyinyang

excelize.py

@@ -2054,6 +2054,51 @@ def remove_row(self, sheet: str, row: int) -> Optional[Exception]:
         )
         return None if err == "" else Exception(err)
 
+    def search_sheet(
+        self, sheet: str, value: str, *reg: bool
+    ) -> Tuple[List[str], Optional[Exception]]:
+        """
+        Get cell reference by given worksheet name, cell value, and regular
+        expression. The function doesn't support searching on the calculated
+        result, formatted numbers and conditional lookup currently. If it is a
+        merged cell, it will return the cell reference of the upper left cell of
+        the merged range reference.
+
+        Args:
+            sheet (str): The worksheet name
+            value (str): The cell value to search
+            *reg (bool): Specifies if search with regular expression
+
+        Returns:
+            Tuple[List[str], Optional[Exception]]: A tuple containing the
+            cell name and an exception if an error occurred, otherwise None.
+
+        Example:
+            An example of search the cell reference of the value of "100" on
+            Sheet1:
+
+            ```python
+            result, err = f.search_sheet("Sheet1", "100")
+            ```
+
+            An example of search the cell reference where the numerical value in
+            the range of "0-9" of Sheet1 is described:
+
+            ```python
+            result, err = f.search_sheet("Sheet1", "[0-9]", True)
+            ```
+        """
+        lib.SearchSheet.restype = types_go._StringArrayErrorResult
+        res = lib.SearchSheet(
+            self.file_index,
+            sheet.encode(ENCODE),
+            value.encode(ENCODE),
+            reg[0] if reg else False,
+        )
+        arr = c_value_to_py(res, StringArrayErrorResult()).arr
+        err = res.Err.decode(ENCODE)
+        return arr if arr else [], None if err == "" else Exception(err)
+
     def set_active_sheet(self, index: int) -> Optional[Exception]:
         """
         Set the default active sheet of the workbook by a given index. Note that

main.go

@@ -1773,6 +1773,31 @@ func SaveAs(idx int, name *C.char, opts *C.struct_Options) *C.char {
 	return C.CString(emptyString)
 }
 
+
+// SearchSheet provides a function to get cell reference by given worksheet name,
+// cell value, and regular expression. The function doesn't support searching
+// on the calculated result, formatted numbers and conditional lookup
+// currently. If it is a merged cell, it will return the cell reference of the
+// upper left cell of the merged range reference.
+//
+//export SearchSheet
+func SearchSheet(idx int, sheet, value *C.char, reg bool) C.struct_StringArrayErrorResult {
+	f, ok := files.Load(idx)
+	if !ok {
+		return C.struct_StringArrayErrorResult{Err: C.CString(errFilePtr)}
+	}
+	result, err := f.(*excelize.File).SearchSheet(C.GoString(sheet), C.GoString(value), reg)
+	if err != nil {
+		return C.struct_StringArrayErrorResult{Err: C.CString(err.Error())}
+	}
+	cArray := C.malloc(C.size_t(len(result)) * C.size_t(unsafe.Sizeof(uintptr(0))))
+	cArrayPtr := (*[1 << 30]*C.char)(cArray)
+	for i, v := range result {
+		cArrayPtr[i] = C.CString(v)
+	}
+	return C.struct_StringArrayErrorResult{ArrLen: C.int(len(result)), Arr: (**C.char)(cArray), Err: C.CString(emptyString)}
+}
+
 // SetActiveSheet provides a function to set the default active sheet of the
 // workbook by a given index. Note that the active index is different from the
 // ID returned by function GetSheetMap(). It should be greater than or equal

test_excelize.py

@@ -256,6 +256,22 @@ def test_style(self):
         self.assertEqual("100", val)
         self.assertIsNone(err)
 
+        result, err = f.search_sheet("Sheet1", "Hello")
+        self.assertIsNone(err)
+        self.assertEqual(result, ["A3", "A12"])
+
+        result, err = f.search_sheet("Sheet1", "H", True)
+        self.assertIsNone(err)
+        self.assertEqual(result, ["A3", "A12"])
+
+        result, err = f.search_sheet("Sheet1", "H", False)
+        self.assertIsNone(err)
+        self.assertEqual(result, [])
+
+        result, err = f.search_sheet("SheetN", "H", False)
+        self.assertEqual(str(err), "sheet SheetN does not exist")
+        self.assertEqual(result, [])
+
         self.assertIsNone(f.duplicate_row("Sheet1", 20))
         self.assertIsNone(f.duplicate_row_to("Sheet1", 20, 20))
         self.assertIsNone(f.insert_cols("Sheet1", "C", 2))

types_c.h

@@ -709,6 +709,13 @@ struct BoolErrorResult
     char *err;
 };
 
+struct StringArrayErrorResult
+{
+    int ArrLen;
+    char **Arr;
+    char *Err;
+};
+
 struct GetCellHyperLinkResult
 {
     bool link;

types_go.py

@@ -685,6 +685,12 @@ class _BoolErrorResult(Structure):
         ("err", c_char_p),
     ]
 
+class _StringArrayErrorResult(Structure):
+    _fields_ = [
+        ("ArrLen", c_int),
+        ("Arr", POINTER(POINTER(c_char))),
+        ("Err", c_char_p),
+    ]
 
 class _CellNameToCoordinatesResult(Structure):
     _fields_ = [

types_py.py

@@ -767,3 +767,9 @@ class WorkbookProtectionOptions:
     password: str = ""
     lock_structure: bool = False
     lock_windows: bool = False
+
+
+@dataclass
+class StringArrayErrorResult:
+    arr: Optional[List[str]] = None
+    err: str = ""