humanizecompact

README

humanizecompact

humanizecompact is a Go library that converts numeric strings into more human-friendly representations (e.g., 1.2K, 9,99 만, 1 bilhão) based on CLDR data and locale rules.

Features

• Locale-aware: Relies on per-locale data to determine how to abbreviate numbers (thousand, million,万,亿,만,억, etc.) and which plural forms to use.
• Long or Short: Offers long-form strings (1 thousand) or short-form strings (1K), configurable via OptionLong or OptionShort.
• Fallback mechanism: When a number cannot be humanized (e.g., it’s not an integer or out of range), the user-supplied fallback function is called.
• Easy integration: Simply implement the Locale interface and provide CldrData for custom languages or variants.

Documentation

Overview

Package humanize provides functionality for converting numeric strings into more human-friendly representations according to CLDR data and locale rules.

Index

• type CldrData
• type FallbackFunc
• type Humanizer
  • func New(locales map[language.Tag]Locale, opt Option, fb FallbackFunc) *Humanizer
  • func (h *Humanizer) FormatDecimal(valueDec decimal.Decimal, locale language.Tag) (string, bool, error)
  • func (h *Humanizer) Formatter(value string, locale language.Tag) (string, bool, error)
• type InvalidNumberError
  • func (e InvalidNumberError) Error() string
• type Locale
• type Option

Types

type CldrData

type CldrData struct {
	Long struct {
		DecimalFormat map[string]string
	}
	Short struct {
		DecimalFormat map[string]string
	}
}

CldrData contains the relevant decimal formats for short and long forms according to the CLDR specification.

type FallbackFunc

type FallbackFunc func(original string) string

FallbackFunc is a user-supplied function invoked when the input string cannot be humanized (for instance, if the input is not an integer).

type Humanizer

type Humanizer struct {
	// contains filtered or unexported fields
}

Humanizer is responsible for converting a numeric string into a more human-friendly representation (e.g., "1K") according to its configured Locale, Option, and fallback strategy.

func New

func New(locales map[language.Tag]Locale, opt Option, fb FallbackFunc) *Humanizer

New returns a pointer to a new Humanizer with the given locale, form option (long or short), and fallback function. The fallback function is called whenever the input string cannot be humanized (e.g., non-integer or missing CLDR data).

func (*Humanizer) FormatDecimal

func (h *Humanizer) FormatDecimal(valueDec decimal.Decimal, locale language.Tag) (string, bool, error)

func (*Humanizer) Formatter

func (h *Humanizer) Formatter(value string, locale language.Tag) (string, bool, error)

Humanize attempts to produce a locale-appropriate, human-friendly version of the given numeric string. If the string cannot be parsed as a decimal integer or the available data is insufficient, the configured fallback function is used instead.

type InvalidNumberError

type InvalidNumberError struct {
	Value string
	Err   error
}

InvalidNumberError is returned when the provided string cannot be parsed as a valid number by the decimal library.

func (InvalidNumberError) Error

func (e InvalidNumberError) Error() string

Error implements the error interface.

type Locale

type Locale interface {
	// Data returns locale-specific CLDR formatting data.
	Data() CldrData

	// PluralForm determines the appropriate plural category (e.g. "one",
	// "other") based on the decimal value and a string form of that value.
	PluralForm(r decimal.Decimal, v string) string

	// Code returns a BCP-47 locale tag like "en", "ja", etc.
	Code() language.Tag
}

Locale defines the methods needed by Humanizer to format numbers for a particular locale. Implementations must provide both the locale code (e.g., "en", "ja") and CLDR data.

type Option

type Option int

Option indicates whether Humanizer should use long or short CLDR patterns (e.g., "1 thousand" vs. "1K").

const (
	// Long indicates long-form patterns, e.g., "1 thousand".
	Long Option = iota

	// Short indicates short-form patterns, e.g., "1K".
	Short
)