Working with Cells and the Data Model

The Cell class is the primary interface for reading and writing individual spreadsheet cell values, formulas, and styles. Access a cell through the worksheet’s Cells collection using an address string.

Writing Values to Cells

Use Cell::PutValue to write text, numbers, booleans, or dates to a cell:

#include "aspose/cells_foss/Workbook.h"
#include "aspose/cells_foss/Worksheet.h"
#include "aspose/cells_foss/Cell.h"

using namespace Aspose::Cells_FOSS;

int main() {
    Workbook workbook;
    Worksheet& sheet = workbook.GetWorksheets()[0];

    sheet.GetCells()["A1"].PutValue("Product");
    sheet.GetCells()["B1"].PutValue("Price");
    sheet.GetCells()["A2"].PutValue("Widget");
    sheet.GetCells()["B2"].PutValue(9.99);
    sheet.GetCells()["C2"].PutValue(true);

    workbook.Save("data.xlsx");
    return 0;
}

Setting Formulas

Use Cell::SetFormula(formula) to write an Excel-compatible formula. Formulas are evaluated by Excel or compatible readers when the file is opened.

sheet.GetCells()["B4"].SetFormula("=SUM(B2:B3)");
sheet.GetCells()["C4"].SetFormula("=AVERAGE(B2:B3)");

Reading Cell Values

Read the current value of a cell with Cell::GetValue(), which returns a CellValue object. Convert to a specific type using the appropriate accessor:

CellValue val = sheet.GetCells()["B2"].GetValue();
double price = val.AsDouble();
std::string text = sheet.GetCells()["A2"].GetStringValue();

The CellValue class provides typed accessors:

Method	Return type
`AsDouble()`	`double`
`AsInteger()`	`int`
`AsBool()`	`bool`
`AsString()`	`std::string`
`AsDateTime()`	`DateTime`

Accessing Cells by Row and Column

In addition to address strings, access cells by zero-based row and column indices:

// Address string
Cell& cellA1 = sheet.GetCells()["A1"];

// Row/column index (0-based)
int row = cellA1.GetRow();
int col = cellA1.GetColumn();

Merging Cells

Use Cells::Merge to merge a rectangular range of cells into one:

CellArea area = CellArea::CreateCellArea("A1", "C1");
sheet.GetCells().Merge(area.StartRow, area.StartColumn,
                       area.EndRow - area.StartRow + 1,
                       area.EndColumn - area.StartColumn + 1);

Getting Display Text

To retrieve the cell value as formatted display text (applying number formats), use Cell::GetDisplayStringValue():

std::string display = sheet.GetCells()["B2"].GetDisplayStringValue();

Tips and Best Practices

Prefer PutValue over SetValue for direct literal assignments — PutValue has overloads for all primitive types.
Use GetStringValue() to retrieve text without type conversion; use GetValue().AsDouble() when you need numeric precision.
Always call SetFormula for formula cells, not PutValue("=SUM(...)") — the latter stores a string literal, not a formula.
Use CellArea::CreateCellArea(start, end) to build range objects for merge and formatting operations.

Common Issues

Issue	Cause	Fix
`GetValue()` returns empty	Cell has not been written	Write a value with `PutValue` before reading
Formula not evaluated	Formula saved as string	Use `SetFormula(expr)` instead of `PutValue(expr)`
Merge fails	Invalid range dimensions	Ensure `endRow >= startRow` and `endColumn >= startColumn`
Type mismatch on read	Calling wrong `As*()` method	Match the accessor to the original `PutValue` type

API Reference Summary

Class/Method	Description
`Cell::PutValue(value)`	Write a literal value to the cell
`Cell::SetFormula(formula)`	Set an Excel formula string
`Cell::GetValue()`	Retrieve the cell value as a `CellValue`
`Cell::GetStringValue()`	Retrieve the cell value as a string
`Cell::GetDisplayStringValue()`	Retrieve the formatted display string
`Cell::GetRow()`	Get the zero-based row index
`Cell::GetColumn()`	Get the zero-based column index
`Cell::GetStyle()`	Get the current cell style
`Cell::SetStyle(style)`	Apply a modified style to the cell
`CellValue::AsDouble()`	Convert cell value to double
`CellValue::AsString()`	Convert cell value to string
`Cells::Merge(row, col, rows, cols)`	Merge a rectangular range

Working with Cells and the Data Model