Add new functions: join_cell_name and split_cell_name

- Update unit tests

Author: xuri

excelize.py

@@ -2716,7 +2716,7 @@ def get_active_sheet_index(self) -> int:
         Returns:
             int: The active sheet index
         """
-        lib.GetActiveSheetIndex.restype = c_int
+        lib.GetActiveSheetIndex.restype = c_longlong
         res = lib.GetActiveSheetIndex(self.file_index)
         return res
 
@@ -6134,6 +6134,27 @@ def coordinates_to_cell_name(col: int, row: int, *is_absolute: bool) -> str:
     raise RuntimeError(err)
 
 
+def join_cell_name(col: str, row: int) -> str:
+    """
+    Joins cell name from column name and row number.
+
+    Args:
+        col (str): The column name
+        row (int): The row number
+
+    Returns:
+        str: Return a cell name if no error occurred, otherwise raise a
+        RuntimeError with the message.
+    """
+    prepare_args([col, row], [argsRule("col", [str]), argsRule("row", [int])])
+    lib.JoinCellName.restype = types_go._StringErrorResult
+    res = lib.JoinCellName(col.encode(ENCODE), c_longlong(row))
+    err = res.err.decode(ENCODE)
+    if not err:
+        return res.val.decode(ENCODE)
+    raise RuntimeError(err)
+
+
 def new_file() -> File:
     """
     Create new file by default template.
@@ -6201,3 +6222,36 @@ def open_reader(buffer: bytes, *opts: Options) -> Optional[File]:
     if err == "":
         return File(res.val)
     raise RuntimeError(err)
+
+
+def split_cell_name(cell: str) -> Tuple[str, int]:
+    """
+    Splits cell name to column name and row number.
+
+    Args:
+        cell (str): The cell reference
+
+    Returns:
+        Tuple[str, int]: Return a tuple containing column name and row number if
+        no error occurred, otherwise raise a RuntimeError with the message.
+
+    Example:
+        For example:
+
+        ```python
+        try:
+            col, row = excelize.split_cell_name("AK74") # return "AK", 74
+        except (RuntimeError, TypeError) as err:
+            print(err)
+        ```
+    """
+    prepare_args([cell], [argsRule("cell", [str])])
+    lib.SplitCellName.restype = types_go._StringIntErrorResult
+    res = lib.SplitCellName(cell.encode(ENCODE))
+    err = res.err.decode(ENCODE)
+    if not err:
+        return (
+            res.strVal.decode(ENCODE),
+            res.intVal,
+        )
+    raise RuntimeError(err)

main.go

@@ -1636,6 +1636,17 @@ func InsertRows(idx int, sheet *C.char, row, n int) *C.char {
 	return C.CString(emptyString)
 }
 
+// JoinCellName joins cell name from column name and row number.
+//
+//export JoinCellName
+func JoinCellName(col *C.char, row int) C.struct_StringErrorResult {
+	result, err := excelize.JoinCellName(C.GoString(col), row)
+	if err != nil {
+		return C.struct_StringErrorResult{err: C.CString(err.Error())}
+	}
+	return C.struct_StringErrorResult{val: C.CString(result), err: C.CString(emptyString)}
+}
+
 // MergeCell provides a function to merge cells by given range reference and
 // sheet name. Merging cells only keeps the upper-left cell value, and
 // discards the other values.
@@ -2918,6 +2929,17 @@ func SetWorkbookProps(idx int, opts *C.struct_WorkbookPropsOptions) *C.char {
 	return C.CString(emptyString)
 }
 
+// SplitCellName splits cell name to column name and row number.
+//
+//export SplitCellName
+func SplitCellName(cell *C.char, row int) C.struct_StringIntErrorResult {
+	col, row, err := excelize.SplitCellName(C.GoString(cell))
+	if err != nil {
+		return C.struct_StringIntErrorResult{err: C.CString(err.Error())}
+	}
+	return C.struct_StringIntErrorResult{intVal: C.int(row), strVal: C.CString(col), err: C.CString(emptyString)}
+}
+
 // UngroupSheets provides a function to ungroup worksheets.
 //
 //export UngroupSheets

test_excelize.py

@@ -2227,6 +2227,18 @@ def test_doc_props(self):
         self.assertIsNone(f.save_as(os.path.join("test", "TestDocProps.xlsx")))
         self.assertIsNone(f.close())
 
+    def test_join_cell_name(self):
+        self.assertEqual(excelize.join_cell_name("A", 1), "A1")
+        with self.assertRaises(RuntimeError) as context:
+           excelize.join_cell_name("", 0)
+        self.assertEqual(str(context.exception), 'invalid column name ""')
+        with self.assertRaises(TypeError) as context:
+            excelize.join_cell_name(1, 1)
+        self.assertEqual(
+            str(context.exception),
+            "expected type str for argument 'col', but got int",
+        )
+
     def test_merge_cell(self):
         f = excelize.new_file()
         self.assertIsNone(f.set_sheet_row("Sheet1", "A1", ["A1", "B1"]))
@@ -2393,6 +2405,20 @@ def test_sheet_visible(self):
         self.assertIsNone(f.save_as(os.path.join("test", "TestSheetVisible.xlsx")))
         self.assertIsNone(f.close())
 
+    def test_split_cell_name(self):
+        col, row = excelize.split_cell_name("AK74")
+        self.assertEqual(col, "AK")
+        self.assertEqual(row, 74)
+        with self.assertRaises(RuntimeError) as context:
+            excelize.split_cell_name("")
+        self.assertEqual(str(context.exception), 'invalid cell name ""')
+        with self.assertRaises(TypeError) as context:
+            excelize.split_cell_name(1)
+        self.assertEqual(
+            str(context.exception),
+            "expected type str for argument 'cell', but got int",
+        )
+
     def test_workbook_props(self):
         f = excelize.new_file()
         expected = excelize.WorkbookPropsOptions(

types_c.h

@@ -748,6 +748,13 @@ struct StringErrorResult
     char *err;
 };
 
+struct StringIntErrorResult
+{
+    char *strVal;
+    int intVal;
+    char *err;
+};
+
 struct IntErrorResult
 {
     int val;

types_go.py

@@ -719,6 +719,14 @@ class _StringErrorResult(Structure):
     ]
 
 
+class _StringIntErrorResult(Structure):
+    _fields_ = [
+        ("strVal", c_char_p),
+        ("intVal", c_int),
+        ("err", c_char_p),
+    ]
+
+
 class _IntErrorResult(Structure):
     _fields_ = [
         ("val", c_int),