Class StreamRow

A single row of StreamCell values read while forward-only streaming through an XLSX worksheet. Cells is sparse: only columns that actually had content in the source row are present, so gaps must be looked up via the indexer.

Inheritance

System.Object

StreamRow

Namespace: IronXL

Assembly: IronXL.dll

Syntax

public sealed class StreamRow : Object

Streaming through a large XLSX worksheet row by row without loading the whole workbook into memory is what StreamRow makes possible. Each StreamRow represents one worksheet row delivered during a forward-only streaming pass, carrying the row's position and a sparse collection of StreamCell values for every column that actually contained content in the source file.

RowNumber gives the zero-based or one-based index of the row within the sheet, so positional logic stays straightforward. Cells exposes the populated columns as an IReadOnlyList<StreamCell>, but because the list is sparse, columns with no content are absent rather than represented by empty entries. To reach a specific column safely, use the this[int columnIndex] indexer for a numeric column address or this[string columnName] for a header-based name such as "Price". When the column might be absent and a missing-key exception would be disruptive, TryGetCell(string columnName, out StreamCell cell) returns false cleanly instead of throwing, making it the right choice inside conditional branches.

Header pairs with the column-name indexer: it holds the header row values captured earlier in the stream, so row["Price"] resolves correctly even though the streaming reader never revisits earlier rows. This design keeps memory use flat across worksheets with hundreds of thousands of rows, because only the current StreamRow and its StreamCell objects need to be live at any moment.

The constructor StreamRow(int rowNumber, IReadOnlyList<StreamCell> cells) is public, which allows unit tests to build synthetic rows without touching a real file, a practical advantage when testing pipeline logic in isolation.

using IronXL;

WorkBook.StreamXlsx("large-report.xlsx", (StreamRow row) =>
{
    if (row.RowNumber == 0) return; // skip header row

    if (row.TryGetCell("Revenue", out StreamCell revenueCell))
        Console.WriteLine($"Row {row.RowNumber}: {revenueCell.Value}");
});

Explore related resources: the IronXL getting-started guide, the streaming large Excel files how-to, the read Excel data examples, and the IronXL API docs.

Constructors

StreamRow(Int32, IReadOnlyList<StreamCell>)

Creates a new forward-only stream row.

Declaration

public StreamRow(int rowNumber, IReadOnlyList<StreamCell> cells)

Parameters

Type	Name	Description
System.Int32	rowNumber	Zero-based row number (the worksheet's 1-based Excel row number minus one), matching what NPOI.XSSF.EventUserModel.XSSFSheetXMLHandler emits.
System.Collections.Generic.IReadOnlyList<StreamCell>	cells	The cells present in this row. They need not be sorted by column: the indexer scans them linearly for rows created through this public constructor, so out-of-order cells resolve correctly.

Properties

Cells

The cells present in this row. May be sparse (columns with no content are simply absent). Rows produced by StreamRows(String, Int32) and its overloads are in ascending column order, which the indexer exploits with a binary search; rows built through the public constructor may be unsorted and are looked up linearly instead.

Declaration

public IReadOnlyList<StreamCell> Cells { get; }

Property Value

Type	Description
System.Collections.Generic.IReadOnlyList<StreamCell>

Header

Column names from the configured header row, positional so that Header[i] is the header name at column i (or null where that column's header cell is blank or absent), or null if no header was configured for this stream.

Declaration

public IReadOnlyList<string> Header { get; }

Property Value

Type	Description
System.Collections.Generic.IReadOnlyList<System.String>

Item[Int32]

Gets the cell at the given zero-based column index, or null if the row has no cell at that column (a sparse gap). For rows whose cells are known to be in ascending column order (all StreamRows(String, Int32) output) this runs in O(log n) via a binary search; for rows built from arbitrary caller-supplied cells it falls back to an O(n) linear scan so out-of-order cells still resolve correctly.

Declaration

public StreamCell this[int columnIndex] { get; }

Parameters

Type	Name	Description
System.Int32	columnIndex	Zero-based column index to look up.

Property Value

Type	Description
StreamCell

Item[String]

Gets the cell under the named header column, or null if this row has no cell there (a sparse gap). Throws System.ArgumentException if the column name is not in the header, and System.InvalidOperationException if no header was configured.

Declaration

public StreamCell this[string columnName] { get; }

Parameters

Type	Name	Description
System.String	columnName	Header column name to look up (trimmed, case-insensitive).

Property Value

Type	Description
StreamCell

RowNumber

Zero-based row number (the worksheet's 1-based Excel row number minus one). For example, Excel row 1 has RowNumber == 0.

Declaration

public int RowNumber { get; }

Property Value

Type	Description
System.Int32

Methods

TryGetCell(String, out StreamCell)

Looks up a cell by header column name. Returns true if the column name exists in the header (cell is that cell, or null for a sparse gap); returns false if the column name is unknown (cell is null). Throws System.InvalidOperationException if no header was configured.

Declaration

public bool TryGetCell(string columnName, out StreamCell cell)

Parameters

Type	Name	Description
System.String	columnName	Header column name to look up (trimmed, case-insensitive).
StreamCell	cell	The matching cell, or null if unknown or a sparse gap.

Returns

Type	Description
System.Boolean