The highest tagged major version is
Documentation
¶
Overview ¶
Package display provides human-readable formatting for CalcMark types.
This package separates display concerns from the core type system:
- spec/types: Model layer - stores exact values, String() returns precise representation
- format/display: View layer - formats values for human consumption (100K instead of 100000)
The Formatter type holds locale-specific configuration. Package-level functions (Format, FormatNumber, etc.) delegate to a default en-US formatter singleton.
Usage:
import "github.com/CalcMark/go-calcmark/format/display" // Package-level (en-US default): fmt.Println(display.Format(result)) // "100K users" // Locale-aware: f := display.NewFormatter(display.DefaultConfig()) fmt.Println(f.Format(result))
Index ¶
- func Format(t types.Type) string
- func FormatCurrency(c *types.Currency) string
- func FormatDuration(d *types.Duration) string
- func FormatNumber(value decimal.Decimal) string
- func FormatQuantity(q *types.Quantity) string
- func FormatRate(r *types.Rate) string
- func NormalizeForDisplay(value decimal.Decimal, unit string) (decimal.Decimal, string)
- type DisplayConfig
- type Formatter
- func (f Formatter) Config() DisplayConfig
- func (f Formatter) Format(t types.Type) string
- func (f Formatter) FormatCurrency(c *types.Currency) string
- func (f Formatter) FormatDuration(d *types.Duration) string
- func (f Formatter) FormatNumber(value decimal.Decimal) string
- func (f Formatter) FormatQuantity(q *types.Quantity) string
- func (f Formatter) FormatRate(r *types.Rate) string
- type UnitFamily
- type UnitScale
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Format ¶
Format returns a human-readable string representation of any CalcMark type. This is the main entry point for display formatting using en-US defaults.
func FormatCurrency ¶
FormatCurrency formats a currency value in human-readable form. Preserves 2 decimal places for small values, uses suffixes for large values. Normalizes currency codes to symbols (USD -> $) and handles sign positioning.
Examples:
FormatCurrency($1500000) → "$1.5M" FormatCurrency($42.50) → "$42.50" FormatCurrency($1500) → "$1,500.00" FormatCurrency(USD100) → "$100.00" FormatCurrency(CNY1000) → "CNY 1,000.00"
func FormatDuration ¶
FormatDuration formats a duration in human-readable form.
Examples:
FormatDuration(1 month) → "1 month" FormatDuration(365 days) → "365 days"
func FormatNumber ¶
FormatNumber formats a decimal number in human-readable form. Uses K/M/B/T suffixes for large numbers, preserves small numbers as-is.
Examples:
FormatNumber(100000) → "100K" FormatNumber(1500000) → "1.5M" FormatNumber(42) → "42" FormatNumber(0.5) → "0.5"
func FormatQuantity ¶
FormatQuantity formats a quantity (value + unit) in human-readable form. For known units (length, mass, volume, data, etc.), it normalizes to the most appropriate unit scale (e.g., 1000000 GB → 976.56 TB). For unknown/arbitrary units, it uses K/M/B/T number suffixes. Napkin estimates (IsNapkin=true) are prefixed with tilde (~).
Examples:
FormatQuantity(1000 m) → "1 km" FormatQuantity(23400000 GB) → "22.31 PB" FormatQuantity(100000 users) → "100K users" FormatQuantity(400 GB, isNapkin=true) → "~400 GB"
func FormatRate ¶
FormatRate formats a rate (quantity per time) in human-readable form. For known units, normalizes to appropriate scale (e.g., 1000000 bytes/s → 976.56 KB/s).
Examples:
FormatRate(1000000 bytes/s) → "976.56 KB/s" FormatRate(100000 users/day) → "100K users/day"
func NormalizeForDisplay ¶
NormalizeForDisplay converts a value+unit to the most human-readable form. It finds the largest unit in the same family where the value is >= 1. Unknown units are returned unchanged.
Examples:
NormalizeForDisplay(1000, "m") → (1, "km") NormalizeForDisplay(23400000, "GB") → (22.89, "PB") NormalizeForDisplay(100000, "users") → (100000, "users") // unknown unit
Types ¶
type DisplayConfig ¶
type DisplayConfig struct {
// Tag is the parsed BCP 47 language tag.
Tag language.Tag
// DecimalSep is the decimal point character (e.g., "." for en-US, "," for de-DE).
DecimalSep string
// ThousandSep is the thousands grouping separator (e.g., "," for en-US, "." for de-DE).
ThousandSep string
}
DisplayConfig holds locale-specific formatting preferences. It is a value type (~56 bytes) designed to be stack-allocatable.
func DefaultConfig ¶
func DefaultConfig() DisplayConfig
DefaultConfig returns the en-US display configuration.
func NewConfig ¶
func NewConfig(locale string) (DisplayConfig, error)
NewConfig creates a DisplayConfig from a locale string (e.g., "en-US", "de-DE"). Returns an error if the locale is invalid. Use DefaultConfig() for en-US defaults.
func (DisplayConfig) Validate ¶
func (c DisplayConfig) Validate() error
Validate checks that the DisplayConfig has valid, non-empty separators.
type Formatter ¶
type Formatter struct {
// contains filtered or unexported fields
}
Formatter formats CalcMark types for human-readable display. It is a value type wrapping a DisplayConfig. Use NewFormatter to create one, or DefaultFormatter() for en-US defaults.
func DefaultFormatter ¶
func DefaultFormatter() Formatter
DefaultFormatter returns a Formatter with en-US defaults.
func NewFormatter ¶
func NewFormatter(cfg DisplayConfig) Formatter
NewFormatter creates a Formatter from a DisplayConfig.
func (Formatter) Config ¶
func (f Formatter) Config() DisplayConfig
Config returns the underlying DisplayConfig.
func (Formatter) Format ¶
Format returns a human-readable string representation of any CalcMark type.
func (Formatter) FormatCurrency ¶
FormatCurrency formats a currency value in human-readable form.
func (Formatter) FormatDuration ¶
FormatDuration formats a duration in human-readable form.
func (Formatter) FormatNumber ¶
FormatNumber formats a decimal number in human-readable form.
func (Formatter) FormatQuantity ¶
FormatQuantity formats a quantity (value + unit) in human-readable form.
type UnitFamily ¶
type UnitFamily struct {
BaseUnit string // The reference unit (ToBase = 1)
Units []UnitScale // Ordered smallest to largest
}
UnitFamily represents a group of related units that can be normalized. Units are ordered from smallest to largest (by magnitude of what they measure).
type UnitScale ¶
type UnitScale struct {
Unit string // Display symbol (e.g., "km", "MB")
ToBase decimal.Decimal // Multiplier to convert TO base unit (e.g., mm->m: 0.001)
}
UnitScale represents a unit with its conversion factor. ToBase converts a value in this unit to the base unit. Example: For millimeters in a meter-based family, ToBase = 0.001 (1mm = 0.001m)
Source Files