Plural notation

(mechanic from Cryptlib)

Spectrallib adds plural notation for localization, which allows for text to change word affixes based on a given quantity. Plural notation generally takes the form #<contents>%d#, where %d is an integer and index of vars (like #%d#). Example use cases include:

• "The ant#<s>1# went home"
• "The #2# stor#<ies,y>2# captivated the author"

Subforms of plural notation

There are three primary ways to use plural notation:

Plural appending

If the plural notation is of the form #<plural>%d#, plural will only appear if the variable of key %d is not equal to 1. For example:

• vars = {1}, "consumable#<s>1#" -> "consumable"
• vars = {2}, "consumable#<s>1#" -> "consumables"
• vars = {0}, "consumable#<s>1#" -> "consumables"

Plural-singular switch

If the plural notation is of the form #<plural,singular>%d#, singular will appear if the variable of key %d is equal to 1, otherwise plural will appear. For example:

• vars = {1}, "cop#<ies,s>1#" -> "copy"
• vars = {2}, "cop#<ies,s>1#" -> "copies"
• vars = {0}, "cop#<ies,s>1#" -> "copies"

Grammatical numbers

This refers to plural notation of the form #<plural,%d,multi,%d,multi,...>%d#. Within the angle brackets, all affixes multi correspond to the number %d directly to its left. The numbers %d are representations of grammatical numbers; where English has singular and plural, several other languages may use more specific grammatical numbers such as a dual and trial, hence the implementation of this extension. Here, only grammatical numbers corresponding to a definite quantity are recognized:

• %d == 1 is singular
• %d == 2 is dual
• %d == 3 is trial
• %d == 4 is quadral ...and so on.

For example, given foo#<plural,3,quick,2,brown,1,fox>1#:

• the singular affix is "fox",
• the dual affix is "brown",
• the trial affix is "quick",
• the plural affix is "plural".

Then in localization, if vars[%d] is equal to a grammatical number, the affix of that grammatical number will be chosen:

• vars = {1}, "foo#<plural,3,quick,2,brown,1,fox>1#" -> "foofox"
• vars = {2}, "foo#<plural,3,quick,2,brown,1,fox>1#" -> "foobrown"
• vars = {3}, "foo#<plural,3,quick,2,brown,1,fox>1#" -> "fooquick"
• vars = {4}, "foo#<plural,3,quick,2,brown,1,fox>1#" -> "fooplural"

...To be specific, if vars[%d] is less than or equal to a grammatical number, the affix of that grammatical number will be chosen. This is evaluated from the smallest to highest number; the first number where the condition is true will have its affix chosen. If none of the numbers meet the condition, the plural affix will be chosen.

• vars = {0}, "foo#<plural,3,quick,2,brown,1,fox>1#" -> "foofox"
• vars = {1.1}, "foo#<plural,3,quick,2,brown,1,fox>1#" -> "foobrown"
• vars = {3.1}, "foo#<plural,3,quick,2,brown,1,fox>1#" -> "fooplural"

Note that not all integers within some range needs to be used; some numbers can be skipped, especially for languages using conflated numbers.

When grammatical numbers are involved, the singular form must be manually defined.

Some weird cases:

• If an affix multi does not have a number %d to its left, it is completely ignored.
• If a number %d has a number %d to its right, that right number is considered an affix.
• If a number %d is the last item within the angle brackets, the empty string "" will be its corresponding affix.

The pluralize function

Spectrallib.pluralize(str, vars) -> string

Given str, a string of the form <contents>%d; and vars, a table with integer indices, the returned affix will be determined per the previously described forms.