README
¶
numfmt
numfmt is a number formatting package for Go.
Features
- Rounding to N decimal places
- Always display minimum of N decimal places
- Configurable thousands separators
- Scaling for percentage formatting
- Format negative values differently for correct currency output like
-$12.34or(12.34) - Easy to use with
text/templateandhtml/template
Examples
Use directly from Go:
f := &numfmt.Formatter{
NegativeTemplate: "(n)",
MinDecimalPlaces: 2,
}
f.Format("-1234") // => "(1,234.00)"
Or in use in text/template:
{{numfmt "1234.5"}} => "1,234.5"
{{numfmt "GroupSeparator" " " "DecimalSeparator" "," "1234.5"}} => "1 234,5"
See the documentation for more examples.
Documentation
¶
Overview ¶
Package numfmt is a number formatting system.
Number formatting is provided by the Formatter type. The zero value of Formatter will format numbers with commas every 3 digits and a period between the integer and fractional parts of a number.
f := &numfmt.Formatter{}
f.Format("1234.56789") => 1,234.56789
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func TemplateFunc ¶
func TemplateFunc(args ...interface{}) (interface{}, error)
TemplateFunc is a helper method for use with text/template and html/template. args is a sequence of key-value pairs configuring the formatting. If len(args) is even a formatting function is returned. If len(args) is odd the final value is formatted and returned.
Keys are generally named the same as matching the Formatter fields:
GroupSeparator GroupSize DecimalSeparator RoundPlaces Shift MinDecimalPlaces Template NegativeTemplate
Example ¶
package main
import (
"fmt"
"os"
"text/template"
"github.com/jackc/numfmt"
)
func main() {
t := template.New("root").Funcs(template.FuncMap{
"numfmt": numfmt.TemplateFunc,
})
t = template.Must(t.Parse(`
numfmt can be called directly:
{{numfmt "GroupSeparator" " " "DecimalSeparator" "," "1234.56789"}}
or it can return a function for later use:
{{- $formatUSD := numfmt "Template" "$n" "RoundPlaces" 2 "MinDecimalPlaces" 2}}
{{call $formatUSD "1234.56789"}}
`))
err := t.Execute(os.Stdout, nil)
if err != nil {
fmt.Println(err)
}
}
Output: numfmt can be called directly: 1 234,56789 or it can return a function for later use: $1,234.57
Types ¶
type Formatter ¶
type Formatter struct {
GroupSeparator string // Separator to place between groups of digits. Default: ","
GroupSize int // Number of digits in a group. Default: 3
DecimalSeparator string // Default: "."
Rounder *Rounder
// Number of places to shift decimal places to the left. Negative numbers are shifted to the right. If set to 2 this
// will convert a fraction to a percentage.
Shift int32
MinDecimalPlaces int32 // Minimum number of decimal places to display.
// Template is a simple format string. All text other than format verbs is passed through unmodified. Backslash '\'
// escaping can be used to include a character otherwise used as a verb. You must include '-' or '+' to have show
// the sign.
//
// Verbs:
// n the number
// - optional negative sign
// + always include sign
//
// Examples:
// "n" => 9.45
// "- n" => - 9.45
// "+n" => +9.45
// "n +" => 9.45 +
// "-$n" => -$9.45
// "n%" => 9.45%
//
// Default: "n"
Template string
// NegativeTemplate will be used if present instead of Template for negative values. The primary expected use is for
// negative values surrounded by parentheses. It uses the same verbs as Template.
//
// Examples:
// "(n)" => (9.45)
// Default: ""
NegativeTemplate string
// contains filtered or unexported fields
}
Formatter is a formatter of numbers. The zero value is usable. Do not change or copy a Formatter after it has been used. The methods on Format are concurrency safe.
Example (Negative_currency) ¶
package main
import (
"fmt"
"github.com/jackc/numfmt"
)
func main() {
f := &numfmt.Formatter{
NegativeTemplate: "(n)",
MinDecimalPlaces: 2,
}
fmt.Println(f.Format("-1234"))
}
Output: (1,234.00)
Example (Rounding) ¶
package main
import (
"fmt"
"github.com/jackc/numfmt"
)
func main() {
f := &numfmt.Formatter{
Rounder: &numfmt.Rounder{Places: 2},
}
fmt.Println(f.Format("1234.56789"))
}
Output: 1,234.57
Example (Zero) ¶
package main
import (
"fmt"
"github.com/jackc/numfmt"
)
func main() {
f := &numfmt.Formatter{}
fmt.Println(f.Format("1234.56789"))
}
Output: 1,234.56789
func NewPercentFormatter ¶
func NewPercentFormatter() *Formatter
NewPercentFormatter returns a formatter that formats a number such as 0.75 to 75%.
Example ¶
package main
import (
"fmt"
"github.com/jackc/numfmt"
)
func main() {
f := numfmt.NewPercentFormatter()
fmt.Println(f.Format("0.781"))
}
Output: 78.1%
func NewUSDFormatter ¶
func NewUSDFormatter() *Formatter
NewUSDFormatter returns a Formatter for US dollars.
Source Files