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.

using Test

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

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

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

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

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

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

using SparseArrays

@test brief(SparseVector([0.0, 1.0])) == "2 x Float64 (Sparse 1 (50%) [Int64])"
@test 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

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

using LinearAlgebra

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

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

println("OK")

# output

OK

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%"