feat: Update CopySheet and RenameSheet methods to return boolean status

- Modified CopySheet method to return a boolean indicating whether the sheet was successfully copied.
- Enhanced RenameSheet method to return a boolean indicating whether the sheet was successfully renamed.
- Updated XML documentation to reflect the new return values for both methods.

These changes provide better feedback on the operations' success when copying or renaming sheets.

Author: fahadadeel

FileFormat.Cells/Workbook.cs

@@ -287,8 +287,11 @@ public bool RemoveSheet(string sheetName)
         /// Renames an existing sheet within the workbook.
         /// </summary>
         /// <param name="existingSheetName">The current name of the sheet to be renamed.</param>
-        /// <param name="newSheetName">The new name to be assigned to the sheet.</param>
-        public void RenameSheet(string existingSheetName, string newSheetName)
+        /// <param name="newSheetName">The new name for the sheet.</param>
+        /// <returns>
+        /// Returns <c>true</c> if the sheet is successfully renamed; otherwise, <c>false</c>.
+        /// </returns>
+        public bool RenameSheet(string existingSheetName, string newSheetName)
         {
             // Find the sheet by its existing name
             var sheet = workbookpart.Workbook.Descendants<Sheet>().FirstOrDefault(s => s.Name == existingSheetName);
@@ -301,15 +304,20 @@ public void RenameSheet(string existingSheetName, string newSheetName)
 
                 // Synchronize the Worksheets property with the Sheets of the workbook
                 SyncWorksheets();
+                return true; // Sheet renamed successfully
             }
+            return false; // Sheet not found, rename failed
         }
 
         /// <summary>
         /// Copies an existing sheet within the workbook to a new sheet.
         /// </summary>
         /// <param name="sourceSheetName">The name of the sheet to be copied.</param>
         /// <param name="newSheetName">The name of the new sheet to be created.</param>
-        public void CopySheet(string sourceSheetName, string newSheetName)
+        /// <returns>
+        /// Returns <c>true</c> if the sheet is successfully copied; otherwise, <c>false</c>.
+        /// </returns>
+        public bool CopySheet(string sourceSheetName, string newSheetName)
         {
             // Find the source sheet by its name
             Sheet sourceSheet = workbookpart.Workbook.Descendants<Sheet>().FirstOrDefault(s => s.Name == sourceSheetName);
@@ -335,7 +343,10 @@ public void CopySheet(string sourceSheetName, string newSheetName)
                 // Append the new sheet to the workbook
                 workbookpart.Workbook.Sheets.Append(newSheet);
                 workbookpart.Workbook.Save(); // Save changes to the workbook
+
+                return true; // Sheet copied successfully
             }
+            return false; // Source sheet not found, copy failed
         }
 
 
@@ -405,6 +416,50 @@ public void SetSheetVisibility(string sheetName, SheetVisibility visibility)
             }
         }
 
+        /// <summary>
+        /// Retrieves a list of hidden or very hidden sheets from the workbook.
+        /// </summary>
+        /// <returns>A list of tuples where each tuple contains the sheet ID and sheet name for hidden sheets.</returns>
+        /// <exception cref="InvalidOperationException">Thrown when the workbook part is not initialized.</exception>
+        /// <exception cref="ArgumentNullException">Thrown when a sheet's ID or Name is null.</exception>
+        public List<Tuple<string, string>> GetHiddenSheets()
+        {
+            if (workbookpart is null)
+                throw new InvalidOperationException("WorkbookPart is not initialized.");
+
+            List<Tuple<string, string>> returnVal = new List<Tuple<string, string>>();
+
+            // Retrieves all sheets in the workbook.
+            // Reference: DocumentFormat.OpenXml.Spreadsheet.Sheet
+            var sheets = workbookpart.Workbook.Descendants<Sheet>();
+
+            // Look for sheets where there is a State attribute defined,
+            // where the State has a value,
+            // and where the value is either Hidden or VeryHidden.
+            // Reference: DocumentFormat.OpenXml.Spreadsheet.SheetStateValues
+            var hiddenSheets = sheets.Where(item => item.State is not null &&
+                                                    item.State.HasValue &&
+                                                    (item.State.Value == SheetStateValues.Hidden ||
+                                                     item.State.Value == SheetStateValues.VeryHidden));
+
+            // Populate the return list with the sheet ID and name as tuples.
+            foreach (var sheet in hiddenSheets)
+            {
+                // Check if sheet ID or Name is null
+                if (sheet.Id is null)
+                    throw new ArgumentNullException(nameof(sheet.Id), "Sheet ID cannot be null.");
+
+                if (sheet.Name is null)
+                    throw new ArgumentNullException(nameof(sheet.Name), "Sheet Name cannot be null.");
+
+                returnVal.Add(new Tuple<string, string>(
+                    sheet.Id,    // The ID of the sheet, typically used to reference the sheet in the workbook.
+                    sheet.Name   // The name of the sheet as displayed in the workbook.
+                ));
+            }
+
+            return returnVal;
+        }
 
         /// <summary>
         /// Synchronize the Worksheets property with the actual sheets present in the workbook.

FileFormat.Cells/Worksheet.cs

@@ -1535,6 +1535,114 @@ public void InsertColumns(string startColumn, int numberOfColumns)
             _worksheetPart.Worksheet.Save();
         }
 
+        /// <summary>
+        /// Gets the column heading for a specified cell in the worksheet.
+        /// </summary>
+        /// <param name="cellName">The name of the cell (e.g., "A1").</param>
+        /// <returns>The text of the column heading, or null if the column does not exist.</returns>
+        /// <exception cref="ArgumentException">Thrown when the cellName is null or empty.</exception>
+        /// <exception cref="InvalidOperationException">Thrown when the WorkbookPart is not found, the sheet is not found,
+        /// the column name is invalid, no header cell is found, or the SharedStringTablePart is missing.</exception>
+        /// <exception cref="IndexOutOfRangeException">Thrown when the shared string index is out of range.</exception>
+        public string? GetColumnHeading(string cellName)
+        {
+            if (string.IsNullOrEmpty(cellName))
+                throw new ArgumentException("Cell name cannot be null or empty.", nameof(cellName));
+
+            var workbookPart = _worksheetPart.GetParentParts().OfType<WorkbookPart>().FirstOrDefault();
+            if (workbookPart == null)
+                throw new InvalidOperationException("No WorkbookPart found.");
+
+            var sheets = workbookPart.Workbook.Descendants<DocumentFormat.OpenXml.Spreadsheet.Sheet>();
+            var sheet = sheets.FirstOrDefault(s => workbookPart.GetPartById(s.Id) == _worksheetPart);
+
+            if (sheet == null)
+                throw new InvalidOperationException("No matching sheet found for the provided WorksheetPart.");
+
+            WorksheetPart worksheetPart = _worksheetPart;
+
+            // Get the column name for the specified cell.
+            string columnName = GetColumnName(cellName);
+
+            if (string.IsNullOrEmpty(columnName))
+                throw new InvalidOperationException("Unable to determine the column name from the provided cell name.");
+
+            // Get the cells in the specified column and order them by row.
+            IEnumerable<DocumentFormat.OpenXml.Spreadsheet.Cell> cells = worksheetPart.Worksheet.Descendants<DocumentFormat.OpenXml.Spreadsheet.Cell>()
+                .Where(c => string.Compare(GetColumnName(c.CellReference?.Value), columnName, true) == 0)
+                .OrderBy(r => GetRowIndexN(r.CellReference) ?? 0);
+
+            if (!cells.Any())
+            {
+                // The specified column does not exist.
+                return null;
+            }
+
+            // Get the first cell in the column.
+            DocumentFormat.OpenXml.Spreadsheet.Cell headCell = cells.First();
+
+            if (headCell == null)
+                throw new InvalidOperationException("No header cell found in the specified column.");
+
+            // If the content of the first cell is stored as a shared string, get the text of the first cell
+            // from the SharedStringTablePart and return it. Otherwise, return the string value of the cell.
+            if (headCell.DataType != null && headCell.DataType.Value == CellValues.SharedString && int.TryParse(headCell.CellValue?.Text, out int index))
+            {
+                var sharedStringPart = workbookPart.GetPartsOfType<SharedStringTablePart>().FirstOrDefault();
+                if (sharedStringPart == null)
+                    throw new InvalidOperationException("No SharedStringTablePart found.");
+
+                var items = sharedStringPart.SharedStringTable.Elements<SharedStringItem>().ToArray();
+                if (index < 0 || index >= items.Length)
+                    throw new IndexOutOfRangeException("Shared string index is out of range.");
+
+                return items[index].InnerText;
+            }
+            else
+            {
+                return headCell.CellValue?.Text;
+            }
+        }
+
+
+        /// <summary>
+        /// Gets the row index from the specified cell name.
+        /// </summary>
+        /// <param name="cellName">The cell name in A1 notation (e.g., "A1").</param>
+        /// <returns>The row index as a nullable unsigned integer, or null if the cell name is invalid.</returns>
+        /// <exception cref="FormatException">Thrown when the row index portion of the cell name cannot be parsed.</exception>
+        private uint? GetRowIndexN(string? cellName)
+        {
+            if (cellName is null)
+            {
+                return null;
+            }
+
+            // Create a regular expression to match the row index portion the cell name.
+            Regex regex = new Regex(@"\d+");
+            Match match = regex.Match(cellName);
+
+            return uint.Parse(match.Value);
+        }
+
+        /// <summary>
+        /// Given a cell name, parses the specified cell to get the column name.
+        /// </summary>
+        /// <param name="cellName">The cell name in A1 notation (e.g., "A1").</param>
+        /// <returns>The column name as a string, or an empty string if the cell name is invalid.</returns>
+        private string GetColumnName(string? cellName)
+        {
+            if (cellName is null)
+            {
+                return string.Empty;
+            }
+
+            // Create a regular expression to match the column name portion of the cell name.
+            Regex regex = new Regex("[A-Za-z]+");
+            Match match = regex.Match(cellName);
+
+            return match.Value;
+        }
         private static string IncrementColumnReference(string reference, int columnCount)
         {
             var regex = new System.Text.RegularExpressions.Regex("([A-Za-z]+)(\\d+)");