README
¶
plural - Simple Go API for Pluralisation.
Package plural provides simple support for localising plurals in a flexible range of different styles.
There are considerable differences around the world in the way plurals are handled. This is a simple but competent API for catering with these differences when presenting to people formatted text with numbers.
This package is able to format countable things and continuous values. It can handle integers and floating point numbers equally and this allows you to decide to what extent each is appropriate.
For example, 2 cars might weigh 1.6 tonnes; both categories are covered.
This API is deliberately simple; it doesn't address the full gamut of internationalisation. If that's what you need, you should consider products such as https://github.com/nicksnyder/go-i18n instead.
Installation
go get -u github.com/rickb777/plural
Status
This library has been in reliable production use for some time. Versioning follows the well-known semantic version pattern.
Documentation
¶
Overview ¶
Package plural provides simple support for localising plurals in a flexible range of different styles.
There are considerable differences around the world in the way plurals are handled. This is a simple but competent API for catering with these differences when presenting to people formatted text with numbers.
This package is able to format countable things and continuous values. It can handle integers and floating point numbers equally and this allows you to decide to what extent each is appropriate.
For example, "2 cars" might weigh "1.6 tonnes"; both categories are covered.
This API is deliberately simple; it doesn't address the full gamut of internationalisation. If that's what you need, you should consider products such as https://github.com/nicksnyder/go-i18n instead.
Please see the examples and associated api documentation.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Case ¶
Case is the inner element of this API and describes one case. When the number to be described matches the number here, the corresponding format string will be used. If the format string includes '%', then fmt.Sprintf will be used. Otherwise the format string will be returned verbatim.
func (Case) FormatFloat ¶ added in v1.1.1
FormatFloat renders a specific case with a given value.
type Plurals ¶
type Plurals []Case
Plurals provides a list of plural cases in the order they will be searched. For plurals of continuous ranges (e.g. weight), the cases must be in ascending number order. For plurals of discrete ranges (i.e. integers), the cases can be in any order you require, but will conventionally be in ascending number order. If no match is found, the last case will be used.
Example ¶
// Plurals{} holds a sequence of cardinal cases where the first match is used, otherwise the last one is used.
// The last case will typically include a "%v" placeholder for the number.
// carPlurals and weightPlurals provide English formatted cases for some number of cars and their weight.
var carPlurals = Plurals{
Case{0, "no cars weigh"},
Case{1, "%v car weighs"},
Case{2, "%v cars weigh"},
}
var weightPlurals = Plurals{
Case{0, "nothing"},
Case{1, "%1.1f tonne"},
Case{2, "%1.1f tonnes"},
}
for d := 0; d < 4; d++ {
s, _ := carPlurals.Format(d)
w, _ := weightPlurals.Format(float32(d) * 0.6)
fmt.Printf("%s %s\n", s, w)
}
Output: no cars weigh nothing 1 car weighs 0.6 tonne 2 cars weigh 1.2 tonnes 3 cars weigh 1.8 tonnes
func ByOrdinal ¶ added in v1.1.0
ByOrdinal constructs a simple set of cases using small ordinals (0, 1, 2, 3 etc), which is a common requirement. It is an alias for FromZero.
Example ¶
// ByOrdinal(...) builds simple common kinds of plurals using small ordinals (0, 1, 2, 3 etc).
// Notice that the counting starts from zero.
var carPlurals = ByOrdinal("no cars weigh", "%v car weighs", "%v cars weigh")
// Note %g, %f etc should be chosen appropriately; both are used here for illustration
var weightPlurals = ByOrdinal("nothing", "%g tonne", "%1.1f tonnes")
for d := 0; d < 5; d++ {
s, _ := carPlurals.Format(d)
w, _ := weightPlurals.Format(float32(d) * 0.5)
fmt.Printf("%s %s\n", s, w)
}
Output: no cars weigh nothing 1 car weighs 0.5 tonne 2 cars weigh 1 tonne 3 cars weigh 1.5 tonnes 4 cars weigh 2.0 tonnes
func FromOne ¶ added in v1.2.0
FromOne constructs a simple set of cases using small positive numbers (1, 2, 3 etc), which is a common requirement. It prevents creation of a Plurals list that is empty, which would be invalid.
The 'first' string becomes Case{1, first}. The rest are appended similarly. Notice that the counting starts from one.
So
FromOne("%v thing", "%v things")
is simply a shorthand for
Plurals{Case{1, "%v thing"}, Case{2, "%v things"}}
which would also be valid but a little more verbose.
Note the behaviour of formatting when the count is zero. As a consequence of Format evaluating the cases in order, FromOne(...).FormatInt(0) will pick the last case you provide, not the first.
This helper function is less flexible than constructing Plurals directly, but covers many common situations.
func FromZero ¶ added in v1.2.0
FromZero constructs a simple set of cases using small ordinals (0, 1, 2, 3 etc), which is a common requirement. It prevents creation of a Plurals list that is empty, which would be invalid.
The 'zeroth' string becomes Case{0, first}. The rest are appended similarly. Notice that the counting starts from zero.
So
FromZero("nothing", "%v thing", "%v things")
is simply a shorthand for
Plurals{Case{0, "nothing"}, Case{1, "%v thing"}, Case{2, "%v things"}}
which would also be valid but a little more verbose.
This helper function is less flexible than constructing Plurals directly, but covers many common situations.
func (Plurals) Format ¶
Format searches through the plural cases for the first match. If none is found, the last case is used. The value passed in can be any number type, or pointer to a number type, except complex numbers are not supported. The value will be converted to an int in order to find the first case that matches. The only possible error arises if value has a type that is not numeric. It panics if 'plurals' is empty.
func (Plurals) FormatFloat ¶
FormatFloat expresses a float32 in plural form. It panics if 'plurals' is empty.
Source Files