Formatting

Formatters convert raw cell values into display strings before styling is applied. They leave the underlying DataFrame unchanged — they only affect the rendered output.

format!

The entry point for all formatting. Pass the table and one or more formatters; each formatter carries its own target column(s).

StyledTables.format! Function

format!(tbl, formatters...)
format!(f, tbl, cols...)
format!(f, tbl, cols::AbstractVector)

Append one or more formatters to the format stack for their target columns.

The first form takes any number of AbstractFormatter instances; each carries its own target column(s) via its syms field. Formatters targeting different columns can be mixed in a single call.

Tip: stack MissingFormatter last to intercept any missing values that remain after earlier formatters.

Examples

tbl = StyledTable(df)
format!(tbl, NumberFormatter(:x; digits = 3), MissingFormatter(:x, "—"))
render(tbl)

tbl = StyledTable(df)
format!(tbl, :x) do val
    val < 0 ? "neg" : "pos"
end
render(tbl)

source

Built-in formatters

AbstractFormatter

StyledTables.AbstractFormatter Type

AbstractFormatter

Supertype for all formatters used with format!.

Every subtype must carry a syms::Vector{Symbol} field naming the columns it targets, and implement (f::MyFormatter)(x) to define the formatting behavior:

struct PrefixFormatter <: AbstractFormatter
    syms::Vector{Symbol}
    prefix::String
end
(f::PrefixFormatter)(x) = ismissing(x) ? x : f.prefix * string(x)

source

NumberFormatter

using StyledTables, DataFrames

df = DataFrame(x = [1.2345, 6.789], y = [100.0, 0.001])

tbl = StyledTable(df)
format!(tbl, NumberFormatter(:x; digits = 3), NumberFormatter(:y; digits = 2))
render(tbl)

x	y
1.234	100.00
6.789	0.00

StyledTables.NumberFormatter Type

NumberFormatter(cols; digits = 2, trailing_zeros = true)

Format numeric values in cols to a fixed number of decimal places.

• cols: a Symbol/AbstractString, or a Vector/varargs of either, naming the target column(s).

• digits: number of decimal places.

• trailing_zeros: when false, strip trailing zeros after the decimal point.

source

PercentFormatter

df = DataFrame(rate = [0.123, 0.456, 0.789])

tbl = StyledTable(df)
format!(tbl, PercentFormatter(:rate; digits = 1))
render(tbl)

rate

12.3%

45.6%

78.9%

For already-scaled values (e.g., 12.3 stored as 12.3%):

df2 = DataFrame(rate = [12.3, 45.6, 78.9])

tbl = StyledTable(df2)
format!(tbl, PercentFormatter(:rate; digits = 1, scale = 1))
render(tbl)

rate

12.3%

45.6%

78.9%

StyledTables.PercentFormatter Type

PercentFormatter(cols; digits = 1, scale = 100, suffix = "%")

Multiply values in cols by scale, format to digits decimal places, and append suffix.

• cols: a Symbol/AbstractString, or a Vector/varargs of either, naming the target column(s).

source

IntegerFormatter

df = DataFrame(count = [12.6, 7.2, 100.9])

tbl = StyledTable(df)
format!(tbl, IntegerFormatter(:count))
render(tbl)

count

13

7

101

StyledTables.IntegerFormatter Type

IntegerFormatter(cols)

Round numeric values in cols to the nearest integer and format without a decimal point.

• cols: a Symbol/AbstractString, or a Vector/varargs of either, naming the target column(s).

source

MissingFormatter

Stack MissingFormatter last so that earlier numeric formatters run first on non-missing values.

StyledTables.MissingFormatter Type

MissingFormatter(cols, replacement)

Return replacement when a value in cols ismissing; otherwise pass it through unchanged. Stack this last so earlier numeric formatters run first.

• cols: a Symbol/AbstractString, or a Vector of either, naming the target column(s).

source

Bare callables and do-blocks

Pass a bare Function to format! — it is wrapped internally and applied like any other formatter. Useful for one-off logic that doesn't need a reusable formatter type:

df = DataFrame(p_value = [0.032, 0.001, 0.245])

tbl = StyledTable(df)
format!(tbl, :p_value) do pval
    pval < 0.05 ? "< 0.05" : "n.s."
end
render(tbl)

p_value

< 0.05

< 0.05

n.s.

Stacking formatters

Each format! call appends to the formatter stack for a column. Formatters run in call order at render time. Each formatter in the stack receives the output of the previous one, not the original raw value. Formatters targeting different columns can be combined in a single call — use this to combine a numeric formatter with a fallback for missing values:

df = DataFrame(x = [1.5, missing, 3.0])

tbl = StyledTable(df)
format!(tbl, NumberFormatter(:x; digits = 1), MissingFormatter(:x, "—"))
render(tbl)

x

1.5

—

3.0

Custom formatters

Implement AbstractFormatter to define reusable custom formatters. Every subtype needs a syms::Vector{Symbol} field naming its target column(s):

struct PrefixFormatter <: AbstractFormatter
    syms::Vector{Symbol}
    prefix::String
end
(f::PrefixFormatter)(x) = ismissing(x) ? x : f.prefix * string(x)

Then use it like any built-in formatter:

format!(tbl, PrefixFormatter([:price], "€"))