Class TabularText

Represents formatted tabular text output with configurable columns, alignment, headers, footers, and sorting. Optimized for efficient string building using StringBuilder with no modifications to internal state during rendering.

Inheritance

object

TabularText

Implements

IEquatable<TabularText>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util

Assembly: ScyllaCore.dll

Syntax

public sealed class TabularText : IEquatable<TabularText>

Remarks

TabularText follows a mutable builder pattern for data addition but ensures that the rendering operation is side-effect free. Multiple ToString() calls produce identical results without modifying stored data.

For complex configuration use the fluent TabularText.Builder pattern via CreateBuilder(). For performance-sensitive scenarios where allocations must be minimized, prefer WriteTo(StringBuilder) over ToString() to write into a caller-owned StringBuilder.

When sorting is enabled, sort indices are computed lazily on the first render call after data changes and are cached until the next AddRow(params string[]) or Clear() call marks the table dirty.

Column alignment is controlled per-column via SetColumnAlignment(int, TextAlignment) using the TextAlignment enum. Padding uses a configurable fill character and is applied via StringUtil extension methods.

Constructors

TabularText(int, string[], bool, int, bool, int, string, char, string, TextAlignment)

Creates a new TabularText instance with the specified configuration.

Declaration

public TabularText(int columnCount = 1, string[] header = null, bool sort = false, int sortColumn = 0, bool hasFooter = false, int maxColumnLength = 0, string divider = null, char fill = ' ', string rowLeading = null, TextAlignment defaultAlignment = TextAlignment.Left)

Parameters

Type	Name	Description
int	columnCount	Number of columns. Must be at least 1. Ignored if header is provided.
string[]	header	Optional header row strings. If provided, determines column count.
bool	sort	Enable alphabetical sorting of data rows.
int	sortColumn	Zero-based column index to sort by. Default is 0.
bool	hasFooter	Whether the last row should be treated as a footer.
int	maxColumnLength	Maximum characters per column. Use 0 for unlimited.
string	divider	String separating columns. Default is single space.
char	fill	Character to fill padding space. Default is space.
string	rowLeading	String prefix for each row. Default is empty.
TextAlignment	defaultAlignment	Default alignment for columns. Default is Left.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if columnCount is less than 1.
ArgumentNullException	Thrown if divider or rowLeading is null.

TabularText(string[], bool, int, bool, int, string, char, string, TextAlignment)

Creates a new TabularText instance with a header row.

Declaration

public TabularText(string[] header, bool sort = false, int sortColumn = 0, bool hasFooter = false, int maxColumnLength = 0, string divider = null, char fill = ' ', string rowLeading = null, TextAlignment defaultAlignment = TextAlignment.Left)

Parameters

Type	Name	Description
string[]	header	Header row strings. Determines column count.
bool	sort	Enable alphabetical sorting of data rows.
int	sortColumn	Zero-based column index to sort by. Default is 0.
bool	hasFooter	Whether the last row should be treated as a footer.
int	maxColumnLength	Maximum characters per column. Use 0 for unlimited.
string	divider	String separating columns. Default is single space.
char	fill	Character to fill padding space. Default is space.
string	rowLeading	String prefix for each row. Default is empty.
TextAlignment	defaultAlignment	Default alignment for columns. Default is Left.

Exceptions

Type	Condition
ArgumentNullException	Thrown if header is null.
ArgumentException	Thrown if header is empty.

Properties

ColumnCount

Gets the number of columns in the table.

Declaration

public int ColumnCount { get; }

Property Value

Type	Description
int

HasFooter

Gets a value indicating whether the table has a footer row.

Declaration

public bool HasFooter { get; }

Property Value

Type	Description
bool

HasHeader

Gets a value indicating whether the table has a header row.

Declaration

public bool HasHeader { get; }

Property Value

Type	Description
bool

IsEmpty

Gets a value indicating whether the table has no data rows. A table with only a header row is considered empty.

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
bool

RowCount

Gets the total number of rows including header and footer.

Declaration

public int RowCount { get; }

Property Value

Type	Description
int

Width

Gets the total character width of the rendered output. This value is calculated based on the maximum lengths of all columns, dividers, and row leading string.

Declaration

public int Width { get; }

Property Value

Type	Description
int

Methods

AddRow(IReadOnlyList<string>)

Adds a row of data to the table from a read-only list of strings.

Declaration

public TabularText AddRow(IReadOnlyList<string> row)

Parameters

Type	Name	Description
IReadOnlyList<string>	row	One string per column. Elements beyond the column count are silently ignored. If row has fewer elements than there are columns, the remaining columns are filled with empty strings. Any null element is stored as the literal string "Null".

Returns

Type	Description
TabularText	This TabularText instance for method chaining.

Remarks

Internally copies the list into an array before delegating to the shared row insertion path. This overload is provided for callers that already hold an IReadOnlyList<T> without the overhead of converting to an array at the call site.

The same truncation and dirty-flag rules as AddRow(params string[]) apply.

Exceptions

Type	Condition
ArgumentNullException	Thrown if row is null.

AddRow(params string[])

Adds a row of data to the table from an array of strings.

Declaration

public TabularText AddRow(params string[] row)

Parameters

Type	Name	Description
string[]	row	One string per column. Elements beyond the column count are silently ignored. If row has fewer elements than there are columns, the remaining columns are filled with empty strings. Any null element is stored as the literal string "Null".

Returns

Type	Description
TabularText	This TabularText instance for method chaining.

Remarks

If a maximum column length was configured (either in the constructor or via WithMaxColumnLength(int)), any cell value that exceeds this limit is truncated with an ellipsis using Truncate(string, int, string).

Adding a row marks the table dirty, so if sorting is enabled the sort indices will be recomputed on the next call to WriteTo(StringBuilder).

Exceptions

Type	Condition
ArgumentNullException	Thrown if row is null.

Clear()

Removes all data rows from the table, retaining the header row if one is present.

Declaration

public TabularText Clear()

Returns

Type	Description
TabularText	This TabularText instance for method chaining.

Remarks

After clearing, column max-lengths are recalculated from the remaining rows (the header only, if present, or zero otherwise), so the cached Width is immediately updated to reflect the reduced content.

The cached sort indices are discarded and the dirty flag is set, so the next call to WriteTo(StringBuilder) will recompute them if sorting is enabled. Column alignments and all other configuration settings are unaffected.

CreateBuilder()

Creates a fluent TabularText.Builder for constructing a TabularText instance with complex configuration using method chaining.

Declaration

public static TabularText.Builder CreateBuilder()

Returns

Type	Description
TabularText.Builder	A new TabularText.Builder instance with all settings at their defaults: one column, no header, no sorting, no footer, unlimited column length, a single-space divider, space fill, empty row-leading, and left alignment.

See Also

TabularText.Builder

Equals(TabularText)

Determines whether the specified TabularText is equal to this instance. Two TabularText instances are considered equal if they produce the same output.

Declaration

public bool Equals(TabularText other)

Parameters

Type	Name	Description
TabularText	other	The TabularText to compare.

Returns

Type	Description
bool	True if the instances are equal; otherwise, false.

Equals(object)

Determines whether the specified object is equal to this TabularText instance.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj	The object to compare.

Returns

Type	Description
bool	True if the objects are equal; otherwise, false.

Overrides

object.Equals(object)

GetHashCode()

Returns a hash code for this TabularText instance.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	A hash code based on the table configuration.

Overrides

object.GetHashCode()

Remarks

Note: TabularText is mutable, so this hash code may change as rows are added. Avoid using TabularText as a dictionary key if rows will be modified.

SetColumnAlignment(int, TextAlignment)

Sets the TextAlignment for a specific column, overriding the default alignment configured at construction time.

Declaration

public TabularText SetColumnAlignment(int columnIndex, TextAlignment alignment)

Parameters

Type	Name	Description
int	columnIndex	Zero-based index of the column whose alignment should change. Must be in the range [0, ColumnCount - 1].
TextAlignment	alignment	The TextAlignment to apply. Left pads on the right, Right pads on the left, and Center distributes padding evenly on both sides.

Returns

Type	Description
TabularText	This TabularText instance for method chaining.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if columnIndex is less than zero or greater than or equal to ColumnCount.

See Also

TextAlignment

ToString()

Renders the entire table to a newly allocated string.

Declaration

public override string ToString()

Returns

Type	Description
string	The formatted table as a string, with rows separated by line-feed characters. Returns an empty string if no rows have been added.

Overrides

object.ToString()

Remarks

This override allocates a new StringBuilder internally, sized with an estimate based on Width and the current row count. For performance-sensitive scenarios where an existing StringBuilder is available, prefer WriteTo(StringBuilder) to avoid the extra allocation.

The rendering order is: optional header row followed by a divider line, sorted or unsorted data rows, then an optional divider line and footer row. Sort indices are computed lazily on the first call after data changes.

See Also

WriteTo(StringBuilder)

ToString(StringBuilder)

ToString(StringBuilder)

Renders the table into the provided StringBuilder, clears it first, then returns the result as a string.

Declaration

public string ToString(StringBuilder builder)

Parameters

Type	Name	Description
StringBuilder	builder	The StringBuilder to use for rendering. It is cleared before writing begins, so any existing content is discarded.

Returns

Type	Description
string	The formatted table as a string. Returns an empty string if no rows exist.

Remarks

Use this overload when a caller-owned StringBuilder is already available for reuse, avoiding the internal allocation made by ToString(). To append table output into an existing builder without clearing it, call WriteTo(StringBuilder) directly instead.

Exceptions

Type	Condition
ArgumentNullException	Thrown if builder is null.

See Also

WriteTo(StringBuilder)

WriteTo(StringBuilder)

Writes the rendered table into the provided StringBuilder without clearing it first, allowing table output to be appended to existing content.

Declaration

public void WriteTo(StringBuilder builder)

Parameters

Type	Name	Description
StringBuilder	builder	The StringBuilder to append the rendered table to. Existing content in builder is preserved.

Remarks

Rendering order:

1. Header row (if present), followed by a full-width dash divider line.
2. Data rows in sorted order (if sorting is enabled) or insertion order.
3. A full-width dash divider line followed by the footer row (if present).

If sorting is enabled and data has changed since the last render, sort indices are computed lazily via Scylla.Core.Util.TabularText.ComputeSortIndices() before writing data rows. The dirty flag is cleared after this computation so subsequent calls skip the sort step unless new rows are added or Clear() is called.

This is the zero-allocation rendering path when a caller-owned StringBuilder is reused across frames or log writes.

Exceptions

Type	Condition
ArgumentNullException	Thrown if builder is null.

See Also

ToString()

ToString(StringBuilder)

Operators

operator ==(TabularText, TabularText)

Determines whether two TabularText instances are equal.

Declaration

public static bool operator ==(TabularText left, TabularText right)

Parameters

Type	Name	Description
TabularText	left
TabularText	right

Returns

Type	Description
bool

operator !=(TabularText, TabularText)

Determines whether two TabularText instances are not equal.

Declaration

public static bool operator !=(TabularText left, TabularText right)

Parameters

Type	Name	Description
TabularText	left
TabularText	right

Returns

Type	Description
bool

Implements

IEquatable<T>

Extension Methods

FileExtensions.SaveSecureToFileAsync<T>(T, string, string, CancellationToken)

FileExtensions.SaveSecureToFile<T>(T, string, string)

FileExtensions.SaveToFileAsync<T>(T, string, CancellationToken)

FileExtensions.SaveToFile<T>(T, string)

FileExtensions.SaveToFile<T>(T, string, SerializationSettings)

See Also

TabularText.Builder

TextAlignment