Module format
Provides string formatting and interpolation facilities.
The benefits of using it are easy internationalization and consistency with the rest of Naev. The number formatters handle plural forms in the user's language, digit separators, and abbreviations. String interpolation (format.f) allows for named parameters ("Fly to {planet} in the {system} system"), whereas string.format is positional ("Fly to %s in the %s system") and locks translators into the English word order.
Functions
| number (number) | Converts a nonnegative integer into a human readable string, delimiting every third digit with a comma. |
| credits (credits) | Converts a number of credits to a string. |
| reward (reward) | Converts an item object or number of credits to reward string ("You have received _"). |
| tonnes (tonnes) | Converts a number of tonnes to a string, using ngettext. |
| tonnes_short (tonnes) | Like fmt.tonnes, but for abbreviations. |
| jumps (jumps) | Converts a number of jumps to a string, utilizing ngettext. |
| list (words) | A version of string.gsub returning just the string. |
| humanize (num) | Converts a number to a human readable string. |
| f (str, tab) | String interpolation, inspired by f-strings but closer to Python's str.format(). |
Functions
- number (number)
-
Converts a nonnegative integer into a human readable string, delimiting every third digit with a comma.
If you pass a more exotic "number" value, you'll get a string back, but you won't attain happiness.
Parameters:
- number The number to format. Will be rounded to the nearest integer.
- credits (credits)
-
Converts a number of credits to a string.
Should be used everywhere a number of credits is displayed.
Parameters:
- credits Number of credits.
Returns:
-
A string taking the form of "X ¤".
Usage:
vn.na(fmt.f(_("You have been paid {credits}."), {credits=fmt.credits(credits)})) - reward (reward)
-
Converts an item object or number of credits to reward string ("You have received _").
Parameters:
- reward Thing or number of credits the player is receiving. Avoid passing strings (English or translated) for clarity's sake.
Returns:
-
A string taking the form of "You have received X." -- translated and colourized.
Usage:
vn.na(fmt.reward(money_reward))
- tonnes (tonnes)
-
Converts a number of tonnes to a string, using ngettext.
This adds "tonnes" to the output of fmt.number in a translatable way. Caution: Usage within sentences can backfire, if the correct grammar to use depends on the number of tonnes. Using ngettext (n_) on full sentences is safer where practical.
Parameters:
- tonnes Number of tonnes.
Returns:
-
A string taking the form of "X tonne" or "X tonnes".
Usage:
vn.na(fmt.f(_("You are carrying {tonnes}"), {tonnes=fmt.tonnes(tonnes)})) - tonnes_short (tonnes)
-
Like fmt.tonnes, but for abbreviations.
Parameters:
- tonnes Number of tonnes.
Returns:
-
A short string like "22 t" describing the given mass.
- jumps (jumps)
-
Converts a number of jumps to a string, utilizing ngettext.
This adds "jumps" to the output of fmt.number in a translatable way. Caution: Usage within sentences can backfire, if the correct grammar to use depends on the number of jumps. Using ngettext (n_) on full sentences is safer where practical.
Parameters:
- jumps Number of jumps.
Returns:
-
A string taking the form of "X jump" or "X jumps".
Usage:
vn.na(fmt.f(_("The system is {jumps} away."), {jumps=fmt.jumps(jumps)})) - list (words)
-
A version of string.gsub returning just the string. --]]local function _replace(template, index, text)
local str = string.gsub(template, index, tostring(text))
return str
end
--[[-- Creates a translatable list of words.
Taken from this post.
Parameters:
- words table List of words to translate such as {"one","two","three"}.
Returns:
-
string
String of the list of words such as "one, two, and three"
- humanize (num)
-
Converts a number to a human readable string.
Has to be implemented on a per-language basis.
Parameters:
- num number Number to convert to a human readable string.
Returns:
-
string
Human readable string.
- f (str, tab)
-
String interpolation, inspired by f-strings but closer to Python's str.format().
Prefer this over string.format because it allows translations to change the word order. It also lets you use objects in the formatting (if they support tostring()), whereas string.format can only do this under LuaJIT.
Parameters:
- str string Format string which may include placeholders of the form "{var}" "{var:6.3f}" (where the expression after the colon is any directive string.format understands).
- tab table Argument table.
Usage:
fmt.f(_("Deliver the loot to {pnt} in the {sys} system"),{pnt=returnpnt, sys=returnsys})fmt.f(_("As easy as {1}, {2}, {3}"), {"one", "two", "three"})fmt.f(_("A few digits of pi: {1:.2f}"), {math.pi})