plural

Documentation

Overview

Package plural provides utilities for handling linguistic plurals in text.

The definitions in this package are based on the plural rule handling defined in CLDR. See https://unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules for details.

Index

• Constants
• func Selectf(arg int, format string, cases ...interface{}) catalog.Message
• type Form
• type Interface
• type Rules
  • func (p *Rules) MatchDigits(t language.Tag, digits []byte, exp, scale int) Form
  • func (p *Rules) MatchPlural(lang language.Tag, i, v, w, f, t int) Form

Examples

• Selectf

Constants

const CLDRVersion = "32"

CLDRVersion is the CLDR version from which the tables in this package are derived.

Functions

func Selectf

func Selectf(arg int, format string, cases ...interface{}) catalog.Message

Selectf returns the first case for which its selector is a match for the arg-th substitution argument to a formatting call, formatting it as indicated by format.

The cases argument are pairs of selectors and messages. Selectors are of type string or Form. Messages are of type string or catalog.Message. A selector matches an argument if:

• it is "other" or Other
• it matches the plural form of the argument: "zero", "one", "two", "few", or "many", or the equivalent Form
• it is of the form "=x" where x is an integer that matches the value of the argument.
• it is of the form "<x" where x is an integer that is larger than the argument.

The format argument determines the formatting parameters for which to determine the plural form. This is especially relevant for non-integer values.

The format string may be "", in which case a best-effort attempt is made to find a reasonable representation on which to base the plural form. Examples of format strings are:

• %.2f decimal with scale 2
• %.2e scientific notation with precision 3 (scale + 1)
• %d integer

Example

package main

import (
	"golang.org/x/text/feature/plural"
	"golang.org/x/text/language"
	"golang.org/x/text/message"
)

func main() {
	// Manually set some translations. This is typically done programmatically.
	message.Set(language.English, "%d files remaining",
		plural.Selectf(1, "%d",
			"=0", "done!",
			plural.One, "one file remaining",
			plural.Other, "%[1]d files remaining",
		))
	message.Set(language.Dutch, "%d files remaining",
		plural.Selectf(1, "%d",
			"=0", "klaar!",
			// One can also use a string instead of a Kind
			"one", "nog één bestand te gaan",
			"other", "nog %[1]d bestanden te gaan",
		))

	p := message.NewPrinter(language.English)
	p.Printf("%d files remaining", 5)
	p.Println()
	p.Printf("%d files remaining", 1)
	p.Println()

	p = message.NewPrinter(language.Dutch)
	p.Printf("%d files remaining", 1)
	p.Println()
	p.Printf("%d files remaining", 0)
	p.Println()

}

Output:

5 files remaining
one file remaining
nog één bestand te gaan
klaar!

Types

type Form

type Form byte

Form defines a plural form.

Not all languages support all forms. Also, the meaning of each form varies per language. It is important to note that the name of a form does not necessarily correspond one-to-one with the set of numbers. For instance, for Croation, One matches not only 1, but also 11, 21, etc.

Each language must at least support the form "other".

const (
	Other Form = iota
	Zero
	One
	Two
	Few
	Many
)

type Interface

type Interface interface {
	// PluralForm reports the plural form for the given language of the
	// underlying value. It also returns the integer value. If the integer value
	// is larger than fits in n, PluralForm may return a value modulo
	// 10,000,000.
	PluralForm(t language.Tag, scale int) (f Form, n int)
}

Interface is used for types that can determine their own plural form.

type Rules

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

Rules defines the plural rules for all languages for a certain plural type.

This package is UNDER CONSTRUCTION and its API may change.

var (
	// Cardinal defines the plural rules for numbers indicating quantities.
	Cardinal *Rules = cardinal

	// Ordinal defines the plural rules for numbers indicating position
	// (first, second, etc.).
	Ordinal *Rules = ordinal
)

func (*Rules) MatchDigits

func (p *Rules) MatchDigits(t language.Tag, digits []byte, exp, scale int) Form

MatchDigits computes the plural form for the given language and the given decimal floating point digits. The digits are stored in big-endian order and are of value byte(0) - byte(9). The floating point position is indicated by exp and the number of visible decimals is scale. All leading and trailing zeros may be omitted from digits.

The following table contains examples of possible arguments to represent the given numbers.

decimal    digits              exp    scale
123        []byte{1, 2, 3}     3      0
123.4      []byte{1, 2, 3, 4}  3      1
123.40     []byte{1, 2, 3, 4}  3      2
100000     []byte{1}           6      0
100000.00  []byte{1}           6      3

func (*Rules) MatchPlural

func (p *Rules) MatchPlural(lang language.Tag, i, v, w, f, t int) Form

MatchPlural returns the plural form for the given language and plural operands (as defined in https://unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules):

where
	n  absolute value of the source number (integer and decimals)
input
	i  integer digits of n.
	v  number of visible fraction digits in n, with trailing zeros.
	w  number of visible fraction digits in n, without trailing zeros.
	f  visible fractional digits in n, with trailing zeros (f = t * 10^(v-w))
	t  visible fractional digits in n, without trailing zeros.

If any of the operand values is too large to fit in an int, it is okay to pass the value modulo 10,000,000.