Struct Cell

Namespace

ExcelReader.Core.Reader

Assembly

ExcelReader.Core.dll

A single worksheet cell's value, exposed as a zero-allocation view over the reader's underlying buffers. Only valid for the lifetime of the row it was read from — do not store it past that point.

public readonly ref struct Cell

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Constructors

Cell(CellType, ReadOnlySpan<byte>, int)

Creates a cell with the given type, text bytes, and optional style index.

public Cell(CellType type, ReadOnlySpan<byte> value, int styleIndex = 0)

Parameters

type CellType

value ReadOnlySpan<byte>

styleIndex int

Properties

StyleIndex

The worksheet's s style index for this cell (0 when absent). Callers can map this to a number format to detect dates themselves, since date cells arrive with Type of Number.

public int StyleIndex { get; }

Property Value

int

Type

The kind of value this cell holds.

public CellType Type { get; }

Property Value

CellType

Value

The cell's raw UTF-8 text bytes. Empty for binary-numeric cells (XLS Number/RK/Date/Formula); use TryGetDouble(out double), TryParse<T>(IFormatProvider?, out T), TryFormat(Span<byte>, out int), or GetString() to read those instead.

public ReadOnlySpan<byte> Value { get; }

Property Value

ReadOnlySpan<byte>

Methods

GetString()

Returns the cell's value as a string, allocating a new instance unless it is a repeated shared string served from the reader's dedup cache. Only call this when a string is required.

public string GetString()

Returns

string

Remarks

A repeated value — the common case for categorical columns — returns the same cached instance instead of decoding UTF-8 and allocating again. See the constructor for how the dedup cache is supplied.

ToString()

Returns the cell's value as a string. Equivalent to GetString().

public override string ToString()

Returns

string

TryFormat(Span<byte>, out int)

Writes the cell's text into destination as UTF-8, without allocating; returns false if the buffer is too small.

public bool TryFormat(Span<byte> destination, out int bytesWritten)

Parameters

destination Span<byte>

bytesWritten int

Returns

bool

TryGetDateTime(bool, out DateTime)

Interprets the cell's numeric value as an Excel serial date, falling back to an ISO-8601 text date (yyyy-MM-dd, optionally followed by T or a space, a time, and up to seven fractional-second digits) when the value is not numeric. A trailing zone designator is not accepted.

public bool TryGetDateTime(bool isDate1904, out DateTime result)

Parameters

isDate1904 bool

Pass true for workbooks using the 1904 date system (e.g. when the reader's IsDate1904 is true) so the epoch offset is applied correctly. Ignored for a text date, which carries its own calendar.

result DateTime

The parsed date, when this method returns true.

Returns

bool

TryGetDouble(out double)

Reads the cell's value as a double; returns false if it isn't numeric.

public bool TryGetDouble(out double value)

Parameters

value double

Returns

bool

Remarks

Numeric cells from binary formats (XLS) carry the raw double, so this avoids the format-then-parse round trip. Text-backed cells (XLSX, strings) parse Value as a fallback.

TryParse<T>(IFormatProvider?, out T)

Parses the cell's value as T, using the stored binary double directly when available instead of round-tripping through text.

public bool TryParse<T>(IFormatProvider? provider, out T result) where T : IUtf8SpanParsable<T>

Parameters

provider IFormatProvider

The format provider used for text parsing and for deciding whether '.' is the decimal separator; null means InvariantCulture, the culture XLSX and XLSB store numbers in.

result T

The parsed value, when this method returns true.

Returns

bool

Type Parameters

T