Wikiup:Lua/Modul/FormatNum/en

aus Wikipedia, der freien Enzyklopädie
Vorlagenprogrammierung Diskussionen Lua Test Unterseiten
Modul Deutsch English

Modul: Dokumentation

FormatNum – Module containing methods for rounding and formatting of numbers. Various variants are offered.

Functions for templates

format

Format a number according to requested specification. Any number using a dot as decimal separator, no separation for thousands, and no exponential represention, consisting of ASCII characters only. See #Formatting options.

Parameter

1
Yet unformatted (but eventually rounded) floating point or integer number.
mandatory.
2
One of the available formatting options. Currently these are at, ch, ch_currency, comma, de, dewiki, de_currency, en, iso31_0, iso31_0_point and pc.
optional; default (here): dewiki

Result

Formatted number. If an invalid value for 2 has been provided or 1 is not a valid number 1 will be returned unchanged.

minus

A heading Unicode minus sign U+2212 = 872210 will be replaced by ASCII hyphen U+002D; or vice versa.

Parameter

1
Number.
mandatory.
2
Conversion in U+002D.
optional; default: 0 = →ASCII (boolean)

Result

Number with ASCII hyphen instead of Unicode minus sign; or other way around if suggested by 2=1.

padding

Padding to the left or right with whitespace which will not be transferred by copy&paste. The number will be filled left or right until decimal separator in a way that all figures show the decimal separator below each other, if extension has been chosen appropriately.

Parameter

1
Number.
mandatory.
2
Extension of whitespace.
Figures greater zero tell expected number of digits following decimal separator. If less significant digits are present, it will be padded to the right with appropriate whitespace.
If extension is less than zero, those numbers with less digits heading decimal separator (or integer) will be padded to the left with appropriate whitespace. The figure needs to match the largest expected number (consider minus sign).
mandatory.
3
Decimal separator.
mandatory.

Result

Eventually adjusted number, otherwise identical to input.

roman2number

Turn roman number into numerical integer.

Parameter

1
Roman number.
mandatory.
2
Lua-pattern for permitted suffix.
optional.
Typically something like %.$ – request a period following the roman number as common in some languages, or %.?$.

Result

Positive integer number, if succeeded.
empty, if not interpretable.

round

Round a number. Results in a string with the requested number of significant digits. Any number that can be parsed by Lua method tonumber() may be used.

Parameter

1
Floating point or integer number to be rounded.
The number is to be given in computer readable encoding (ASCII, minus as hyphen U+002D, dot as decimal separator, no separation for thousands).
mandatory.
2
Integer number specifying the number of significant digits.
If non-negative, these are the digits following decimal separator.
If negative, the result is an integer number and will be rounded to full ten (for -1), full hundreds (for -2) etc.
mandatory.
method
Code specifying rounding method.
  • 0 – Round according to IEEE 754 (round half to even).
  • 1 – Commercial rounding, inkluding elimination of -0 results.
optional; default: 0
format
Trigger formatting by format subsequently.
The value is the formatting method.
Omitting or assignment of an empty value uses standard method (here: dewiki).
padding
Trigger formatting by padding and format subsequently.
The value is the whitespace extension. The formatting method is standard method, if not specified by format=. The decimal separator results from formatting method.
optional

Result

String with requested number of significant digits according to rounding method. First computer readable encoding, but may be formatted later by format or immediately applied by format= or padding=.
If any of the parameter values cannot be parsed the parameter value 1 is returned unchanged.
If the input value is a floating point number (with dot as decimal separator) the result is a floating point number. If the input value is an integer number the result is supposed to be an integer number. If the number of requested significant digits is headed by a minus sign (hyphen) including  -0, the result is always an integer number.

failsafe

Version ID: 2020-08-06

  • optional parameter 1 – required version, or keyword wikidata

Returns:

  • (empty), if minimal version condition not matched
  • local version otherwise, or registered on Wikidata (2020-08-06) when wikidata

Formatierungsoptionen

Format Decimal
separator
Thousands
separator
(Tsep)
Tsep from
length
Tsep just
integer
part
Examples
de , Thin whitespace 5* no 123,456
1 234,567
12 345,678
1 234,567 8
12 345,567 8
-123,456
-1 234,567
-12 345,678
-1 234,567 8
-12 345,567 8
de_currency
dewiki
, . 5 yes 123,456
1.234,567
12.345,678
1.234,5678
12.345,5678
-123,456
-1.234,567
-12.345,678
-1.234,5678
-12.345,5678
ch , ' 5 yes 123,456
1234,567
12'345,678
1234,5678
12'345,5678
-123,456
-1234,567
-12'345,678
-1234,5678
-12'345,5678
ch_currency . ' 5 yes 123.456
1234.567
12'345.678
1234.5678
12'345.5678
-123.456
-1234.567
-12'345.678
-1234.5678
-12'345.5678
en . , 4 yes 123.456
1,234.567
12,345.678
1,234.5678
12,345.5678
-123.456
-1,234.567
-12,345.678
-1,234.5678
-12,345.5678
iso31_0
at
, Thin whitespace 4 no 123,456
1 234,567
12 345,678
1 234,567 8
12 345,567 8
-123,456
-1 234,567
-12 345,678
-1 234,567 8
-12 345,567 8
iso31_0_point . Thin whitespace 4 no 123.456
1 234.567
12 345.678
1 234.567 8
12 345.567 8
-123.456
-1 234.567
-12 345.678
-1 234.567 8
-12 345.567 8
pc . 123.456
1234.567
12345.678
1234.5678
12345.5678
-123.456
-1234.567
-12345.678
-1234.5678
-12345.5678
comma , 123,456
1234,567
12345,678
1234,5678
12345,5678
-123,456
-1234,567
-12345,678
-1234,5678
-12345,5678

* Since the thousands separator is applied to the part after decimal separator, a length of 5 is relevant only if there is a part after decimal separator with maximal 3 digits. On 4 or more digits after decimal separator the integer part will be divided also on 4 digits.

Examples and test page

There are tests available to illustrate this in practice.

Use in another Lua module

All of the above functions can be called from other Lua modules, if not Lua library function anyway. Use require(); the below code checks for errors loading it:

local lucky, FormatNum = pcall( require, "Module:FormatNum" )
if type( FormatNum ) == "table" then
    FormatNum = FormatNum.FormatNum()
else
    -- In the event of errors, FormatNum is an error message.
    return "<span class=\"error\">" .. FormatNum .. "</span>"
end
FormatNum.format(source, spec, meet)
  • source: string
  • spec: optional string
  • meet: optional number (extension for internal padding)
FormatNum.minus(source, larger)
  • source: string
  • larger: optional boolean (conversion into Unicode)
FormatNum.padding(source, meet, stop)
  • source: string
  • meet: number
  • stop: string
FormatNum.roman2number(source, suffix)
  • source: string
  • suffix: optional string
FormatNum.round(source, precision, method)
  • source: string
  • precision: number
  • method: optional number
FormatNum.format(assert)
  • assert: optional string
FormatNum.failsafe(atleast)
  • atleast: optional string with minimum version or wikidata
Returns string or false.
FormatNum()
Yields table with access to functions (see above).

Internals

Usage

This is a general library; use it anywhere. Dedicated to be wrapped into relevant templates.

Dependencies

None.