ScriptForge - (SF_Calc) new GetRangeAddress() method

The GetRangeAddress() method accepts 2 arguments:
GetRangeAddress(Range, AddressItem)

- a range as a string, to be understood as the extended definition
described in the help pages

- the item to be extracted from the given range, either:
firstrow
firstcol
lastrow
lastcol
sheet

The returned value is either:
- a Long
- a String when sheet is requested
- an array of all these values when no item is given

The method is available for both Basic and Python user scripts

Change-Id: I6156b176e29cf47207a079d10552443467dd2f6d
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/124551
Tested-by: Jean-Pierre Ledure <jp@ledure.be>
Tested-by: Jenkins
Reviewed-by: Jean-Pierre Ledure <jp@ledure.be>

3 files changed, 73 insertions, 0 deletions

diff --git a/wizards/source/scriptforge/SF_PythonHelper.xba b/wizards/source/scriptforge/SF_PythonHelper.xba
index 5b919ba5abe1..f32e077d83d0 100644
--- a/wizards/source/scriptforge/SF_PythonHelper.xba
+++ b/wizards/source/scriptforge/SF_PythonHelper.xba
@@ -777,6 +777,7 @@ Try:
 						Select Case Script
 							Case "Charts"			:	vReturn = vBasicObject.Charts(vArgs(0), vArgs(1))
 							Case "Forms"			:	vReturn = vBasicObject.Forms(vArgs(0), vArgs(1))
+							Case "GetRangeAddress"	:	vReturn = vBasicObject.GetRangeAddress(vArgs(0), vArgs(1))
 							Case "GetFormula"		:	vReturn = vBasicObject.GetFormula(vArgs(0))
 							Case "GetValue"			:	vReturn = vBasicObject.GetValue(vArgs(0))
 							Case "SetArray"			:	vReturn = vBasicObject.SetArray(vArgs(0), vArgs(1))
diff --git a/wizards/source/scriptforge/python/scriptforge.py b/wizards/source/scriptforge/python/scriptforge.py
index 4643ade07229..ebd33ab9a7f2 100644
--- a/wizards/source/scriptforge/python/scriptforge.py
+++ b/wizards/source/scriptforge/python/scriptforge.py
@@ -1974,6 +1974,9 @@ class SFDocuments:
         def GetFormula(self, range):
             return self.ExecMethod(self.vbMethod + self.flgArrayRet, 'GetFormula', range)
 
+        def GetRangeAddress(self, range, addressitem = ''):
+            return self.ExecMethod(self.vbMethod + self.flgArrayArg, 'GetRangeAddress', range, addressitem)
+
         def GetValue(self, range):
             return self.ExecMethod(self.vbMethod + self.flgArrayRet, 'GetValue', range)
 
diff --git a/wizards/source/sfdocuments/SF_Calc.xba b/wizards/source/sfdocuments/SF_Calc.xba
index 75642598fa66..6fc937c93637 100644
--- a/wizards/source/sfdocuments/SF_Calc.xba
+++ b/wizards/source/sfdocuments/SF_Calc.xba
@@ -1315,6 +1315,74 @@ Catch:
 End Function	'	SFDocuments.SF_Calc.GetProperty
 
 REM -----------------------------------------------------------------------------
+Public Function GetRangeAddress(Optional ByVal Range As Variant _
+							, Optional ByVal AddressItem As Variant _
+							) As Variant
+'''	Extracts from a range expressed in A1-style one or more of its coordinates
+'''	Args:
+'''		Range: the range as a string from which to extract the coordinates
+'''		AddressItem: either "firstrow", "firstcol" (topleft cell), "lastrow", "lastcol" (bottom right cell), "sheet" or omitted
+'''	Returns:
+'''		Either:
+'''			- one of the cell coordinates as a Long (coordinates start with 1)
+'''				when Range is a single cell, row2 and row1 return the same value
+'''			- the sheet name as a string
+'''			- all of them as a zero-based array in the order firstrow, firstcol, lastrow, lastcol, sheet
+'''	Exceptions:
+'''	Examples:
+'''		row2 = oDoc.GetRangeAddress("'$SheetX'.E2:J4", "row2")		'	4
+'''		arr = oDoc.GetRangeAddress("'$SheetX'.E2:J4")				'	(2, 5, 4, 10, "SheetX")
+
+Dim vRangeAddress As Variant		'	Return value
+Dim oAddress As Object				'	Alias of input range as _Address
+Dim oCellRange As Object			'	com.sun.star.table.XCellRange
+Const cstThisSub = "SFDocuments.Calc.GetRangeAddress"
+Const cstSubArgs = "Range, [AddressItem=""firstrow""|""firstcol""|""lastrow""|""lastcol""|""sheet""]"
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+	vRangeAddress = 0
+
+Check:
+	If IsMissing(AddressItem) Or IsEmpty(AddressItem) Then AddressItem = ""
+
+	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
+		If Not _IsStillAlive() Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Range, "Range", V_STRING) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(AddressItem, "AddressItem", V_STRING _
+				, Array("firstrow", "firstcol", "firstcolumn", "lastrow", "lastcol", "lastcolumn", "sheet", "sheetname", "")) Then GoTo Finally
+	End If
+
+Try:
+	Set oAddress = _ParseAddress(Range)
+	Set oCellRange = oAddress.XCellRange
+	
+	With oCellRange
+		Select Case UCase(AddressItem)
+			Case "FIRSTROW"						:	vRangeAddress = CLng(.RangeAddress.StartRow + 1)
+			Case "FIRSTCOL", "FIRSTCOLUMN"		:	vRangeAddress = CLng(.RangeAddress.StartColumn + 1)
+			Case "LASTROW"						:	vRangeAddress = CLng(.RangeAddress.EndRow + 1)
+			Case "LASTCOL", "LASTCOLUMN"		:	vRangeAddress = CLng(.RangeAddress.EndColumn + 1)
+			Case "SHEET", "SHEETNAME"			:	vRangeAddress = .Spreadsheet.Name
+			Case ""
+				vRangeAddress = Array( _
+								CLng(.RangeAddress.StartRow + 1) _
+								, CLng(.RangeAddress.StartColumn + 1) _
+								, CLng(.RangeAddress.EndRow + 1) _
+								, CLng(.RangeAddress.EndColumn + 1) _
+								, .Spreadsheet.Name _
+								)
+		End Select
+	End With
+
+Finally:
+	GetRangeAddress = vRangeAddress
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Function
+Catch:
+	GoTo Finally
+End Function	'	SF_Documents.SF_Calc.GetRangeAddress
+
+REM -----------------------------------------------------------------------------
 Public Function GetValue(Optional ByVal Range As Variant) As Variant
 '''	Get the value(s) stored in the given range of cells
 '''	Args:
@@ -1617,6 +1685,7 @@ Public Function Methods() As Variant
 					, "ExportAsPDF" _
 					, "GetColumnName" _
 					, "GetFormula" _
+					, "GetRangeAddress" _
 					, "GetValue" _
 					, "ImportFromCSVFile" _
 					, "ImportFromDatabase" _