DOCSEARCHbyAlgolia
Submit Docs

CoreXLSX Documentation

repository·main·Indexed 21 days ago

https://github.com/coreoffice/corexlsx

A pure Swift library for read-only parsing of the low-level XML structure of XLSX (Office Open XML) spreadsheets. It maps internal spreadsheet structures directly into Swift model types and supports sparse spreadsheets, shared strings, cell styles, and formatting.

Tokens
1.3K
Snippets
5
Records
7
Agent score
25%

What's inside CoreXLSX

  1. How to address cells correctly using CellReference

    main
    Do not attempt to address cells by their index in the cells array, as the library supports sparse spreadsheets (where cells might be missing). Instead, use the reference property on a Cell to find its location, or use the CellReference struct to work with specific coordinates.

  2. Install CoreXLSX via Swift Package Manager

    main

    To add CoreXLSX to your Swift project using Swift Package Manager, add it to the dependencies array in your Package.swift file.

    dependencies: [
  .package(url: "https://github.com/CoreOffice/CoreXLSX.git",
           .upToNextMinor(from: "0.14.1"))
]

  3. Install CoreXLSX via CocoaPods

    main

    For Apple platforms, you can install CoreXLSX using CocoaPods by adding the following to your Podfile:

    target '<Your Target Name>' do
  pod 'CoreXLSX', '~> 0.14.1'
end
    source 'https://github.com/CocoaPods/Specs.git'
# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'
use_frameworks!
target '<Your Target Name>' do
  pod 'CoreXLSX', '~> 0.14.1'
end

  4. Troubleshooting XLSX parsing errors

    main

    CoreXLSX uses Swift's Codable protocol to generate detailed error messages. If a file fails to parse, the error message often specifies the missing attribute.

    If you need to report an issue and cannot attach the full file, you can increase the amount of context included in the error message by passing a value to the errorContextLength argument in the XLSXFile initializer:

    // Example: increasing error context length to see more of the failing XML
let file = XLSXFile(filepath: path, errorContextLength: 20)

  5. Parse an XLSX file and iterate through cells

    main

    CoreXLSX provides a read-only parser for .xlsx files. You can open a file using XLSXFile(filepath:), parse workbooks, and then iterate through worksheets and their rows/cells.

    Note: The library maps the internal XML structure directly to Swift models. If a cell or row is missing during iteration, it means it is absent in the document (sparse spreadsheet support).

    import CoreXLSX

let filepath = "./categories.xlsx"
guard let file = XLSXFile(filepath: filepath) else {
  fatalError("XLSX file at \(filepath) is corrupted or does not exist")
}

for wbk in try file.parseWorkbooks() {
  for (name, path) in try file.parseWorksheetPathsAndNames(workbook: wbk) {
    if let worksheetName = name {
      print("This worksheet has a name: \(worksheetName)")
    }

    let worksheet = try file.parseWorksheet(at: path)
    for row in worksheet.data?.rows ?? [] {
      for c in row.cells {
        print(c)
      }
    }
  }
}

  6. Access cell styles, fonts, and formatting

    main

    To access styling information, first parse the styles from the archive using parseStyles(). You can then use format(in:) and font(in:) on a Cell instance, passing the parsed Styles object.

    Note: Not all XLSX files contain style information; be prepared to handle errors from parseStyles().

    // Fetch fonts
let styles = try file.parseStyles()
let fonts = styles.fonts?.items.compactMap { $0.name?.value }

// Get formatting for a specific cell
let cell = worksheet.data?.rows.first?.cells.first
let format = cell?.format(in: styles)
let font = cell?.font(in: styles)
    let styles = try file.parseStyles()
let fonts = styles.fonts?.items.compactMap { $0.name?.value }

let format = worksheet.data?.rows.first?.cells.first?.format(in: styles)
let font = worksheet.data?.rows.first?.cells.first?.font(in: styles)

  7. Read string, date, and rich string values from cells

    main

    Because XLSX files often use shared strings for efficiency, you must use the parseSharedStrings() method on XLSXFile and pass the resulting SharedStrings object to the cell's value methods.

    • Standard Strings: Use stringValue(_: SharedStrings).
    • Rich Strings: Use richStringValue(sharedStrings).
    • Dates: Use the dateValue property directly on the Cell.

    Example of getting strings from a specific column:

    if let sharedStrings = try file.parseSharedStrings() {
  let columnCStrings = worksheet.cells(atColumns: [ColumnReference("C")!])
    .compactMap { $0.stringValue(sharedStrings) }
}