Brief

Functions for generating a brief description of arbitrary data. Yes, this is what the builtin summary is expected to do. However, summary doesn't summarize arrays that well. As we don't want to override it for types we don't own, we default brief to call summary and can then override it for whatever types we feel is necessary. For your own types, provide an implementation for summary as that is the "right thing to do".

brief(value::Any)::AbstractString

Provide a brief description of a value . This is basically summary but modified for specific types (in particular, vectors and matrices) to give "better" results.

@assert brief(1.0) == "1.0"
@assert brief(true) == "true"
@assert brief(:foo) == ":foo"
@assert brief(nothing) == "nothing"
@assert brief(missing) == "missing"
@assert brief(undef) == "undef"
@assert brief(("foo", :bar)) == "(\"foo\", :bar)"
@assert brief("foo" => :bar) == "\"foo\" => :bar"
@assert brief("foo") == "\"foo\""
@assert brief("foo "^10) == "\"foo foo foo foo ...\" (40)"
@assert brief([true, false]) == "2 x Bool (Dense; 1 (50%) true)"
@assert brief(Int64) == "Int64"
@assert brief(String) == "Str"
@assert brief(AbstractString) == "Str"

@enum Foo Bar Baz
@assert brief(Bar) == "Foo::Bar"

struct Vaz end
@assert brief(Vaz()) == summary(Vaz())

@assert brief(Set([1])) == "1 x Int64 (Set)"

@assert brief(rand(5)) == "5 x Float64 (Dense)"
@assert brief(rand(3, 4)) == "3 x 4 x Float64 in Columns (Dense)"

@assert brief(read_only_array(rand(5))) == "5 x Float64 (ReadOnly, Dense)"
@assert brief(PermutedDimsArray(rand(3, 4), (2, 1))) == "4 x 3 x Float64 in Rows (Permute, Dense)"
@assert brief(PermutedDimsArray(rand(3, 4), (1, 2))) == "3 x 4 x Float64 in Columns (!Permute, Dense)"

using SparseArrays

@assert brief(SparseVector([0.0, 1.0])) == "2 x Float64 (Sparse 1 (50%) [Int64])"
@assert brief(SparseMatrixCSC([0.0 1.0 2.0; 3.0 4.0 0.0])) == "2 x 3 x Float64 in Columns (Sparse 4 (67%) [Int64])"

using NamedArrays

@assert brief(NamedArray(rand(2))) == "2 x Float64 (Named, Dense)"
@assert brief(NamedArray(SparseVector([0.0, 1.0]))) == "2 x Float64 (Named, Sparse 1 (50%) [Int64])"

using LinearAlgebra

@assert brief(transpose(rand(2))) == "2 x Float64 (Transpose, Dense)"
@assert brief(adjoint(rand(2))) == "2 x Float64 (Adjoint, Dense)"

@assert brief(Dict(["a" => 1])) == "1 x Str => Int64 (Dict)"

# output

The maximal length of strings we show as-is in brief . We only show a prefix of longer strings (followed by their length).

percent(used::Real, out_of::Real)::AbstractString

Format a fraction of used amount out_of some total, as an integer percent value. Very small fractions are denoted as <1% and very large fractions are denoted as >99% . We use this to show the percent of true values in masks, and the percent of non-zero entries in sparse arrays.

percent(0, 0)

# output

"NA%"

percent(0, 1000)

# output

"0%"

percent(9, 1000)

# output

"<1%"

percent(10, 1000)

# output

"1%"

percent(11, 1000)

# output

"1%"

percent(990, 1000)

# output

"99%"

percent(991, 1000)

# output

">99%"

percent(1000, 1000)

# output

"100%"

delimited_number(number::Number; decimal=".", delim=",")::AbstractString

Convert a number to a string using a delimiter for every 3 digits. No, Format doesn't do that - it doesn't add delimiters to the decimal fraction.

println(delimited_number(123))
println(delimited_number(1.0))
println(delimited_number(1234567))
println(delimited_number(1.2345678))
println(delimited_number(1.234567e9))

# output

123
1.0
1,234,567
1.234,567,8
1.234,567e9