NumberF
A comprehensive utility library for number formatting, calculation, and manipulation in Elixir.
Features
- Number Formatting: Format numbers as currency, with commas, custom delimiters, abbreviated forms (K, M, B)
- Text Representation: Convert numbers to words, ordinals, Roman numerals
- Financial Calculations: Simple/compound interest, EMI calculations, currency conversions, tax calculations
- Statistical Functions: Mean, median, mode, standard deviation, variance
- Date Calculations: Age calculation, business days, payment terms
- Validation: Credit card validation (Luhn algorithm), number format validation
- String Generation: Random string generation, password creation
- Type Conversions: Convert between numeric types and formats
- Memory Size: Convert byte counts to human-readable formats
- Phone Formatting: Format phone numbers based on country codes
- Unit Conversion: Convert between metric and imperial units
- Tax Calculations: VAT, sales tax, income tax calculations
- Precision Handling: Different rounding strategies and precision handling
- Internationalization: Format numbers according to locale conventions
Installation
Add number_f to your list of dependencies in mix.exs:
def deps do
[
{:number_f, "~> 0.3.0"}
]
endKey Functionality
Currency & Number Formatting
NumberF provides comprehensive formatting capabilities for currency and numbers:
# Format as currency with default (ZMW)
NumberF.currency(1234.567) # => "ZMW 1,234.57"
# Format as US Dollars with 2 decimal places
NumberF.currency(1234.567, "USD", 2) # => "USD 1,234.57"
# Format with French locale (space as thousands separator, comma as decimal)
NumberF.format_number(1234567.89, "fr-FR") # => "1 234 567,89"Number to Words Conversion
Convert numeric values to their word representations:
# Convert whole number with default currency (Kwacha)
NumberF.to_words(42) # => "Forty Two Kwacha"
# Convert decimal with custom currency
NumberF.to_words(42.75, "Dollars", "Cents") # => "Forty Two Dollars And Seventy Five Cents"
# Advanced internationalization
NumberF.spell_number(42, "fr") # => "Quarante-deux"Financial Calculations
Perform complex financial operations with ease:
# Calculate simple interest (principal, rate, time)
NumberF.simple_interest(1000, 0.05, 2) # => 100.0
# Calculate compound interest with monthly compounding
NumberF.compound_interest(1000, 0.05, 2, 12) # => 104.94
# Calculate loan EMI (principal, rate, term in months)
NumberF.calculate_emi(100000, 0.10, 12) # => 8791.59
# Calculate VAT
NumberF.calculate_vat(100, 0.2) # => %{net: 100.0, vat: 20.0, gross: 120.0}Statistical Functions
Analyze numerical data with statistical functions:
NumberF.mean([1, 2, 3, 4, 5]) # => 3.0
NumberF.median([1, 3, 5, 7, 9]) # => 5
NumberF.mode([1, 2, 2, 3, 3, 3, 4]) # => [3]
NumberF.standard_deviation([2, 4, 4, 4, 5, 5, 7, 9]) # => 2.0Internationalization & Localization
Format numbers according to locale-specific conventions:
# Format with US locale
NumberF.format_currency(1234.56, "en-US") # => "$1,234.56"
# Format with French locale
NumberF.format_currency(1234.56, "fr-FR") # => "1 234,56 €"
# Format with German locale but using USD
NumberF.format_currency(1234.56, "de-DE", currency_code: "USD") # => "1.234,56 $"Module Organization
NumberF is organized into specialized modules for different functionality areas:
- Core:
NumberF,NumberF.Registry - Calculation:
NumberF.Calculations,NumberF.Financial,NumberF.Statistics,NumberF.Precision,NumberF.Tax - Formatting:
NumberF.Formatter,NumberF.CustomFormatter,NumberF.Currencies - Conversion:
NumberF.Metrics - Validation:
NumberF.Validation - Date:
NumberF.DateCalculations - I18n:
NumberF.I18n
Every function documented on those modules is also available directly from
NumberF, which is the recommended entry point. Modules not listed above
(NumberF.Currency, NumberF.Memory, NumberF.Randomizer, NumberF.Helper,
NumberF.NumbersToWords, NumberF.NumberToWord) are internal implementation
details and are not part of the public API.
For more information, see the full documentation on HexDocs.
Summary
Formatting
Formats large numbers as K, M, B (e.g., 1.2K, 3.4M).
Accounting format: negatives in parentheses.
Approximates a decimal as a fraction.
Formats a number in engineering notation (exponents are multiples of three).
Human-readable byte size. base: :binary for KiB/MiB.
Human-readable duration. format: :short, :long or :clock.
Formats a numerator and denominator as a fraction.
Formats a value as a percentage string.
Formats phone numbers based on country code.
Formats to significant figures, keeping trailing zeros.
Formats a number with a custom prefix and suffix.
Converts Roman numerals to Arabic numbers.
Formats a number as currency using the low-level formatter.
Formats a number into a delimited format with options for customization.
Converts numbers to ordinals (1st, 2nd, 3rd, etc.).
Pads a number to a fixed width.
Pairs a count with a correctly pluralised noun.
Formats a number in scientific notation.
Rounds to a number of significant figures.
Sums a list of decimal numbers.
Converts a string to a boolean value.
Converts a value to a decimal.
Converts a value to a float.
Converts a string to an integer.
Converts Arabic numbers to Roman numerals.
Prefixes a number with an explicit sign.
Currency
Formats a number into comma-separated format with the specified precision.
Converts between two currencies using a rate table.
Formats a number into currency with the specified unit and precision.
Returns a map of currency information with ISO codes, symbols, and formatting details.
Formats a currency with the specified currency code's rules.
Gets currency details for a specific currency code.
Parses a currency string into a number.
Text
Converts a number into words with customizable currency terms.
Financial
Full amortization schedule for a loan, one entry per period.
Future value of a stream of equal payments.
Payment required to amortise a present value over n periods.
Present value of a stream of equal payments.
Units that must be sold to cover fixed costs.
Compound annual growth rate, as a percentage.
Calculates Equated Monthly Installment (EMI) for loans.
Calculates compound interest with optional compounding frequency.
Converts an amount between currencies based on exchange rates.
Declining-balance depreciation schedule. factor defaults to 2.
Straight-line depreciation per year.
Effective annual rate for a nominal rate compounded n times per year.
Future value of a present sum.
Internal rate of return. Returns {:ok, rate} or an error tuple.
Level loan payment. Unlike calculate_emi/3's history, safe at a zero rate.
Net present value of a series of cash flows, the first at t=0.
Years until cumulative cash flows repay an initial investment.
Present value of a future sum.
Return on investment, as a percentage.
Calculates simple interest based on principal, rate and time.
Tax
Calculates capital gains tax on a gain.
Calculates corporate tax on a profit.
Calculates progressive income tax against a bracket table.
Calculates employee and employer payroll contributions.
Calculates sales tax for a given amount and rate.
Calculates Value Added Tax (VAT) for a given amount and rate.
Calculates withholding tax on a gross amount.
Reference income tax brackets by country.
Returns common VAT rates for different countries.
Statistics
Standard deviation as a proportion of the mean — a unitless measure of spread.
Pearson correlation coefficient between two equal-length lists, in -1..1.
Population covariance of two equal-length lists.
Running total of a list.
Counts how often each value occurs.
Geometric mean — the correct average for growth rates and ratios.
Harmonic mean — the correct average for rates over a fixed distance.
Interquartile range — the spread of the middle half of the data.
Least-squares linear regression, returning slope, intercept and r-squared.
Calculates the arithmetic mean of a list of numbers.
Finds the median value from a list of numbers.
Finds the most frequently occurring value(s) in a list.
Simple moving average over a sliding window.
Rescales a list to the 0..1 range (min-max normalisation).
Values falling outside the expected spread. method: :iqr (default) or :zscore.
Returns the value at the given percentile (0..100), by linear interpolation.
Returns the first, second and third quartiles.
Calculates the range (difference between max and min values) of a dataset.
The list with its outliers removed.
Calculates the sample standard deviation of a dataset (divides by N-1).
Calculates the sample variance of a dataset (divides by N-1).
Calculates standard deviation of a dataset.
A one-call description of a dataset: count, min, quartiles, max, mean, stddev.
Mean after discarding a proportion from each end — robust to unreliable extremes.
Calculates the variance of a dataset.
Mean weighted by a matching list of weights.
How many standard deviations a value sits from the mean.
Standardises a list to zero mean and unit variance.
Precision
Checks if two floating point numbers are approximately equal.
Rounds a number using banker's rounding (round to even). This is more statistically unbiased than standard rounding.
Rounds a number up to a specified precision (ceiling).
Constrains a value to a range.
Rounds to a precision using an explicit mode.
Rounds a number down to a specified precision (floor).
Formats a number to a fixed number of decimal places, padding with zeros.
Rounds half away from zero — "round half up" as most people mean it.
Rounds half to even. A discoverable alias for bankers_round/2.
Rounds a number to a specific increment.
Rounds a number to a specified number of decimal places.
Divides, returning default instead of raising when the denominator is zero.
Replaces non-finite float values with a safe default.
Returns -1, 0 or 1 according to the sign of the number.
Truncates a number to a precision, cutting digits rather than rounding.
Validation
Identifies a card network from its number.
Validates credit card numbers using the Luhn algorithm.
Checks if a string is a valid integer.
Checks if a string is a valid number format.
Computes the Luhn check digit for a number.
Whether the code is a currency this library knows.
Validates an EAN-8 or EAN-13 barcode.
Validates an IBAN by its mod-97 checksum.
Validates a 15-digit IMEI.
Validates an ISBN-10 or ISBN-13.
Validates any Luhn-checksummed number.
Whether a value is a number in 0..100.
Validates a US ABA routing number.
Validates a UPC-A barcode.
Math
Calculates combinations (n choose k).
Sum of the decimal digits.
Repeatedly sums the digits until one remains.
The decimal digits of an integer.
All positive divisors of n, ascending.
Calculates the factorial of a non-negative integer.
The nth Fibonacci number, exact for any n.
The first n Fibonacci numbers.
Parses an integer written in a base from 2 to 36.
Parses a binary integer.
Parses a hexadecimal integer.
Parses an octal integer.
Calculates the Greatest Common Divisor (GCD) of two integers.
Checks if a number is within a specified range (inclusive).
Performs a linear interpolation between two points.
Checks if a number is prime.
Calculates the Least Common Multiple (LCM) of two integers.
Logarithm in an arbitrary base.
The real nth root of a number.
Whether the digits read the same both ways.
Calculates a percentage with specified precision.
Whether n is a perfect square, without float error.
Ordered arrangements of k items from n (nPk).
Prime factorisation, ascending and with repeats.
The integer with its digits reversed.
Rounds a number to the nearest specified value.
Renders an integer in a base from 2 to 36.
Renders an integer in binary.
Converts radians to degrees.
Renders an integer in hexadecimal.
Renders an integer in octal.
Converts degrees to radians.
Units
Converts acres to hectares.
Area conversion factors, relative to square metres.
Converts Celsius to Fahrenheit.
Converts centimeters to inches.
Converts between arbitrary units from one of the unit tables.
Converts Fahrenheit to Celsius.
Converts hectares to acres.
Converts inches to centimeters.
Converts kilograms to pounds.
Converts kilometers to miles.
Length conversion factors, relative to metres.
Converts miles to kilometers.
Converts millilitres to fluid ounces.
Converts fluid ounces to millilitres.
Converts pounds to kilograms.
Volume conversion factors, relative to litres.
Weight conversion factors, relative to kilograms.
Dates
Adds business days to a date. A negative count subtracts them.
Age in whole months.
Calculates the number of business days between two dates.
Calculates age based on birth date.
Calculates the number of days between two dates.
Number of days in a month.
Fiscal year containing the date, named for the year it ends in.
Determines if a date is a business day.
Whether a year is a leap year.
Last day of the date's month.
First day of the date's month.
Returns the next business day after the given date.
Calculates payment due date based on invoice date and terms.
Calendar quarter of a date, 1 to 4.
Last day of the date's quarter.
First day of the date's quarter.
ISO-8601 week number.
Humanize
Generates a default password with pre-defined complexity. The pattern is: capitalized 3-letter string + @ + 4 random digits.
Converts a memory size in bytes to a human-readable format. Automatically selects the appropriate unit (B, KB, MB, GB) based on size.
Generates a random string of the specified length.
Internationalization
Formats a number as currency according to locale-specific settings.
Formats a number according to locale-specific settings.
Returns the main and sub unit names for a currency in a given language.
Returns the formatting settings for a locale.
Parses a locale-formatted number string back into a number.
Spells out a number in the specified language.
Lists the languages NumberF.spell_number/3 can spell numbers in.
Introspection
Returns metadata for a single function category.
Returns a markdown documentation of all NumberF modules and functions.
Returns all function categories available in NumberF.
Returns metadata for a single NumberF module.
Returns information about all NumberF modules.
Returns information about NumberF modules of a specific type.
Returns all modules and their functions as a reference.
Formatting
Formats large numbers as K, M, B (e.g., 1.2K, 3.4M).
Parameters
number: The number to abbreviateprecision: Number of decimal places (default: 1)
Examples
iex> NumberF.abbreviate_number(1234)
"1.2K"
iex> NumberF.abbreviate_number(1234567)
"1.2M"
iex> NumberF.abbreviate_number(1234567890)
"1.2B"Accounting format: negatives in parentheses.
Examples
iex> NumberF.accounting_format(-1234.56, unit: "$")
"($1,234.56)"Approximates a decimal as a fraction.
Formats a number in engineering notation (exponents are multiples of three).
Examples
iex> NumberF.engineering_notation(0.000123)
"123.0e-6"Human-readable byte size. base: :binary for KiB/MiB.
Examples
iex> NumberF.format_bytes(1_500_000)
"1.5 MB"Human-readable duration. format: :short, :long or :clock.
Examples
iex> NumberF.format_duration(3725)
"1h 2m 5s"Formats a numerator and denominator as a fraction.
Formats a value as a percentage string.
Formats phone numbers based on country code.
Parameters
number: The phone number as a stringcountry_code: The country code (default: "ZM" for Zambia)
Examples
iex> NumberF.format_phone("260977123456", "ZM")
"+260 97 712 3456"
iex> NumberF.format_phone("14155552671", "US")
"+1 (415) 555-2671"Formats to significant figures, keeping trailing zeros.
Examples
iex> NumberF.format_significant(1.5, 4)
"1.500"Formats a number with a custom prefix and suffix.
Converts Roman numerals to Arabic numbers.
Parameters
roman: The Roman numeral string
Examples
iex> NumberF.from_roman("IV")
4
iex> NumberF.from_roman("XLII")
42
iex> NumberF.from_roman("MCMXCIX")
1999Formats a number as currency using the low-level formatter.
Formats a number into a delimited format with options for customization.
Parameters
number: The number to formatoptions: Keyword options for formatting:delimiter: Character used as thousand delimiter (default: ",")separator: Character used as decimal separator (default: ".")precision: Number of decimal places (default: 2)
Examples
iex> NumberF.number_to_delimited(1234567.89)
"1,234,567.89"
iex> NumberF.number_to_delimited(1234567.89, delimiter: ".", separator: ",")
"1.234.567,89"
iex> NumberF.number_to_delimited(1234567.89, precision: 0)
"1,234,568"Converts numbers to ordinals (1st, 2nd, 3rd, etc.).
Parameters
number: The number to convert
Examples
iex> NumberF.ordinal(1)
"1st"
iex> NumberF.ordinal(2)
"2nd"
iex> NumberF.ordinal(3)
"3rd"
iex> NumberF.ordinal(4)
"4th"Pads a number to a fixed width.
Examples
iex> NumberF.pad_number(42, 6, char: "0")
"000042"Pairs a count with a correctly pluralised noun.
Examples
iex> NumberF.pluralize(3, "person", "people")
"3 people"Formats a number in scientific notation.
Examples
iex> NumberF.scientific_notation(0.000123)
"1.23e-4"Rounds to a number of significant figures.
Examples
iex> NumberF.significant_figures(1234.5678, 3)
1230.0Sums a list of decimal numbers.
Parameters
list: A list of decimal values, potentially nested
Examples
iex> NumberF.sum_decimal([Decimal.new("1.2"), Decimal.new("3.4"), [Decimal.new("5.6")]])
Decimal.new("10.2")
iex> NumberF.sum_decimal([])
Decimal.new("0")This function flattens any nested lists, then uses Enum.reduce/3 to sum all the decimal values.
Converts a string to a boolean value.
Parameters
value: The string value to convert. Accepts the following:true,yes,onconvert totruefalse,no,offconvert tofalse- Any other value raises an ArgumentError
Examples
iex> NumberF.to_boolean("true")
true
iex> NumberF.to_boolean("yes")
true
iex> NumberF.to_boolean("false")
false
iex> NumberF.to_boolean("no")
falseConverts a value to a decimal.
Parameters
value: The value to convert (string or number)
Examples
iex> NumberF.to_decimal("123.45")
Decimal.new("123.45")
iex> NumberF.to_decimal(123)
Decimal.new("123")Converts a value to a float.
Parameters
value: The value to convert (string or number)
Examples
iex> NumberF.to_float("123.45")
123.45
iex> NumberF.to_float(123)
123.0Converts a string to an integer.
Parameters
value: The string value to convert
Examples
iex> NumberF.to_int("123")
123
iex> NumberF.to_int("123.45")
123Converts Arabic numbers to Roman numerals.
Parameters
number: The number to convert (1-3999)
Examples
iex> NumberF.to_roman(4)
"IV"
iex> NumberF.to_roman(42)
"XLII"
iex> NumberF.to_roman(1999)
"MCMXCIX"Prefixes a number with an explicit sign.
Examples
iex> NumberF.with_sign(42)
"+42"Currency
Formats a number into comma-separated format with the specified precision.
Parameters
number: The number to formatprecision: Decimal places (default: 2)
Examples
iex> NumberF.comma_separated(1234567.89)
"1,234,567.89"
iex> NumberF.comma_separated(1234567.89, 0)
"1,234,568"
iex> NumberF.comma_separated(nil, 2)
nilConverts between two currencies using a rate table.
Formats a number into currency with the specified unit and precision.
Features
- Automatic digit grouping with thousands separators
- Configurable decimal precision
- Support for custom currency symbols/codes
- Consistent formatting for financial applications
Parameters
number: The number to formatunit: The currency unit (default: "ZMW")precision: Decimal places (default: 2)
Examples
iex> NumberF.currency(1234.567)
"ZMW 1,234.57"
iex> NumberF.currency(1234.567, "USD", 2)
"USD 1,234.57"
iex> NumberF.currency(1234567.89, "€", 0)
"€ 1,234,568"
iex> NumberF.currency(nil, "USD", 2)
nilCommon Use Cases
- Financial reporting and analysis
- E-commerce price displays
- Invoice and receipt generation
- Banking and financial applications
Related Functions
NumberF.comma_separated/2: Format numbers with commas but no currencyNumberF.format_currency/3: Format with locale-specific currency settingsNumberF.number_to_delimited/2: Format with custom delimiters
See also: NumberF.Currencies for currency-specific information.
Returns a map of currency information with ISO codes, symbols, and formatting details.
Examples
iex> NumberF.currency_data()["USD"]
%{
name: "US Dollar",
symbol: "$",
symbol_first: true,
symbol_space: false,
decimal_places: 2,
thousands_separator: ",",
decimal_separator: "."
}Formats a currency with the specified currency code's rules.
Parameters
number: The number to formatcurrency_code: ISO currency code (e.g., "USD", "EUR")options: Additional options (override currency defaults)
Examples
iex> NumberF.format_with_currency(1234.56, "USD")
"$1,234.56"
iex> NumberF.format_with_currency(1234.56, "EUR")
"1.234,56 €"Gets currency details for a specific currency code.
Parameters
currency_code: ISO currency code (e.g., "USD", "EUR")
Examples
iex> NumberF.get_currency("USD")
%{
name: "US Dollar",
symbol: "$",
symbol_first: true,
symbol_space: false,
decimal_places: 2,
thousands_separator: ",",
decimal_separator: "."
}Parses a currency string into a number.
Text
Converts a number into words with customizable currency terms.
Features
- Convert integers and decimals to their word representations
- Support for custom currency terms for main and fractional units
- Handles numbers from zero to trillions
- Properly handles decimal values and zero cases
Parameters
amount: The number to convertmain_currency: The main currency name (default: "Kwacha")sec_currency: The secondary currency name (default: "Ngwee")
Examples
iex> NumberF.to_words(20.0)
"Twenty Kwacha"
iex> NumberF.to_words(42.75, "Dollars", "Cents")
"Forty Two Dollars And Seventy Five Cents"
iex> NumberF.to_words(1234567.89, "Euros", "Cents")
"One Million Two Hundred Thirty Four Thousand Five Hundred Sixty Seven Euros And Eighty Nine Cents"
iex> NumberF.to_words(0, "Euros", "Cents")
"zero Euros"Common Use Cases
- Check writing and financial documents
- Legal documents requiring numeric values in words
- Invoices and receipts
- Educational applications
Related Functions
NumberF.spell_number/3: Spell numbers in different languagesNumberF.to_roman/1: Convert to Roman numeralsNumberF.ordinal/1: Convert to ordinal forms (1st, 2nd, 3rd)
See also: NumberF.NumbersToWords for more advanced word conversion options.
Financial
Full amortization schedule for a loan, one entry per period.
Examples
iex> NumberF.amortization_schedule(100_000, 0.10, 12) |> List.last() |> Map.get(:balance)
0.0Future value of a stream of equal payments.
Examples
iex> NumberF.annuity_future_value(100, 0.05, 10)
1257.79Payment required to amortise a present value over n periods.
Examples
iex> NumberF.annuity_payment(10_000, 0.05, 10)
1295.05Present value of a stream of equal payments.
Examples
iex> NumberF.annuity_present_value(100, 0.05, 10)
772.17Units that must be sold to cover fixed costs.
Examples
iex> NumberF.break_even_point(10_000, 25, 15)
1000.0Compound annual growth rate, as a percentage.
Examples
iex> NumberF.cagr(1000, 2000, 5)
14.87Calculates Equated Monthly Installment (EMI) for loans.
Parameters
principal: The loan amountrate: The annual interest rate as a decimal (e.g., 0.05 for 5%)term_months: The loan term in months
Examples
iex> NumberF.calculate_emi(100000, 0.10, 12)
8791.59Calculates compound interest with optional compounding frequency.
Features
- Support for different compounding frequencies (annual, semi-annual, quarterly, monthly, etc.)
- Precise calculations using Elixir's floating-point operations
- Results rounded to 2 decimal places by default
- Guard clauses ensure valid inputs
Parameters
principal: The principal amountrate: The annual interest rate as a decimal (e.g., 0.05 for 5%)time: The time period in yearsfrequency: Number of times interest is compounded per year (default: 1)
Examples
iex> NumberF.compound_interest(1000, 0.05, 2)
102.5 # Annual compounding (1 time per year)
iex> NumberF.compound_interest(1000, 0.05, 2, 12)
104.94 # Monthly compounding (12 times per year)
iex> NumberF.compound_interest(10000, 0.08, 5, 4)
4859.47 # Quarterly compounding (4 times per year)Formula
The compound interest is calculated using the formula:
A = P(1 + r/n)^(nt) - PWhere:
- A = Interest amount
- P = Principal
- r = Annual interest rate (decimal)
- n = Compounding frequency
- t = Time in years
Common Use Cases
- Investment calculations
- Loan and mortgage analysis
- Retirement planning
- Financial education tools
Related Functions
NumberF.simple_interest/3: Calculate simple interestNumberF.calculate_emi/3: Calculate equated monthly installmentsNumberF.Tax.calculate_capital_gains_tax/3: Calculate capital gains tax
See also: NumberF.Financial for more financial calculations.
Converts an amount between currencies based on exchange rates.
Parameters
amount: The amount to convertfrom_rate: The exchange rate of the source currencyto_rate: The exchange rate of the target currency
Examples
iex> NumberF.convert_currency(100, 1, 1.1)
110.0Declining-balance depreciation schedule. factor defaults to 2.
Examples
iex> NumberF.depreciation_declining_balance(10_000, 1_000, 5) |> hd()
%{year: 1, depreciation: 4000.0, book_value: 6000.0}Straight-line depreciation per year.
Examples
iex> NumberF.depreciation_straight_line(10_000, 1_000, 5)
1800.0Effective annual rate for a nominal rate compounded n times per year.
Examples
iex> NumberF.effective_annual_rate(0.12, 12)
0.1268Future value of a present sum.
Examples
iex> NumberF.future_value(1000, 0.05, 10)
1628.89Internal rate of return. Returns {:ok, rate} or an error tuple.
Examples
iex> {:ok, rate} = NumberF.irr([-1000, 300, 400, 500, 600])
iex> Float.round(rate, 4)
0.2489Level loan payment. Unlike calculate_emi/3's history, safe at a zero rate.
Examples
iex> NumberF.loan_payment(100_000, 0.0, 12)
8333.33Net present value of a series of cash flows, the first at t=0.
Examples
iex> NumberF.npv(0.1, [-1000, 300, 400, 500, 600])
388.77Years until cumulative cash flows repay an initial investment.
Examples
iex> NumberF.payback_period(1000, [300, 400, 500])
{:ok, 2.6}Present value of a future sum.
Examples
iex> NumberF.present_value(1000, 0.05, 10)
613.91Return on investment, as a percentage.
Examples
iex> NumberF.roi(1500, 1000)
50.0Calculates simple interest based on principal, rate and time.
Parameters
principal: The principal amountrate: The annual interest rate as a decimal (e.g., 0.05 for 5%)time: The time period in years
Examples
iex> NumberF.simple_interest(1000, 0.05, 2)
100.0Tax
Calculates capital gains tax on a gain.
Calculates corporate tax on a profit.
Calculates progressive income tax against a bracket table.
Examples
iex> brackets = NumberF.income_tax_brackets()["US"]
iex> result = NumberF.calculate_income_tax(75_000, brackets)
iex> is_number(result.tax) and is_number(result.effective_rate)
trueCalculates employee and employer payroll contributions.
Calculates sales tax for a given amount and rate.
Parameters
amount: The amount before taxrate: The sales tax rate as a decimal (e.g., 0.06 for 6%)options: Additional options:round_to: Round the tax amount to the nearest value (default: 0.01)
Examples
iex> NumberF.calculate_sales_tax(100, 0.06)
%{subtotal: 100.0, tax: 6.0, total: 106.0}Calculates Value Added Tax (VAT) for a given amount and rate.
Parameters
amount: The amount before taxrate: The VAT rate as a decimal (e.g., 0.2 for 20%)included: Whether the amount already includes VAT (default: false)
Examples
iex> NumberF.calculate_vat(100, 0.2)
%{net: 100.0, vat: 20.0, gross: 120.0}
iex> NumberF.calculate_vat(120, 0.2, true)
%{net: 100.0, vat: 20.0, gross: 120.0}Calculates withholding tax on a gross amount.
Reference income tax brackets by country.
These are reference data, not legal advice: rates change and jurisdictions differ. Supply your own brackets for anything with financial consequence.
Examples
iex> NumberF.income_tax_brackets() |> Map.keys() |> Enum.sort()
["Germany", "UK", "US", "Zambia"]Returns common VAT rates for different countries.
Examples
iex> NumberF.vat_rates()["UK"]
0.2
iex> NumberF.vat_rates()["Germany"]
0.19Statistics
Standard deviation as a proportion of the mean — a unitless measure of spread.
Examples
iex> NumberF.coefficient_of_variation([2, 4, 4, 4, 5, 5, 7, 9])
0.4Pearson correlation coefficient between two equal-length lists, in -1..1.
Examples
iex> NumberF.correlation([1, 2, 3, 4, 5], [2, 4, 5, 4, 5])
0.7745966692414833Population covariance of two equal-length lists.
Examples
iex> NumberF.covariance([1, 2, 3, 4, 5], [2, 4, 5, 4, 5])
1.2Running total of a list.
Examples
iex> NumberF.cumulative_sum([1, 2, 3, 4])
[1, 3, 6, 10]Counts how often each value occurs.
Examples
iex> NumberF.frequency_distribution([1, 2, 2, 3, 3, 3])
%{1 => 1, 2 => 2, 3 => 3}Geometric mean — the correct average for growth rates and ratios.
Examples
iex> NumberF.geometric_mean([1, 4, 16]) |> Float.round(4)
4.0Harmonic mean — the correct average for rates over a fixed distance.
Examples
iex> NumberF.harmonic_mean([40, 60]) |> Float.round(6)
48.0Interquartile range — the spread of the middle half of the data.
Examples
iex> NumberF.iqr([1, 2, 3, 4, 5, 6, 7, 8])
3.5Least-squares linear regression, returning slope, intercept and r-squared.
Examples
iex> NumberF.linear_regression([1, 2, 3, 4, 5], [2, 4, 5, 4, 5]).slope
0.6Calculates the arithmetic mean of a list of numbers.
Features
- Handles lists of any size
- Returns nil for empty lists
- Works with integers and floating-point numbers
- Accurately calculates average using sum and count
Parameters
numbers: A list of numbers
Examples
iex> NumberF.mean([1, 2, 3, 4, 5])
3.0
iex> NumberF.mean([1.5, 2.5, 3.5])
2.5
iex> NumberF.mean([42])
42.0
iex> NumberF.mean([])
nilMathematical Definition
The arithmetic mean is the sum of all values divided by the number of values.
Common Use Cases
- Data analysis and statistics
- Financial analysis (average returns, costs, etc.)
- Scientific calculations
- Performance metrics
Related Functions
NumberF.median/1: Calculate the median valueNumberF.mode/1: Find the most frequent value(s)NumberF.standard_deviation/1: Calculate standard deviationNumberF.variance/1: Calculate variance
See also: NumberF.Statistics for more statistical functions.
Finds the median value from a list of numbers.
Parameters
numbers: A list of numbers
Examples
iex> NumberF.median([1, 3, 5, 7, 9])
5
iex> NumberF.median([1, 3, 5, 7])
4.0Finds the most frequently occurring value(s) in a list.
Parameters
numbers: A list of numbers
Examples
iex> NumberF.mode([1, 2, 2, 3, 3, 3, 4])
[3]
iex> NumberF.mode([1, 1, 2, 2, 3])
[1, 2]Simple moving average over a sliding window.
Examples
iex> NumberF.moving_average([1, 2, 3, 4, 5], 3)
[2.0, 3.0, 4.0]Rescales a list to the 0..1 range (min-max normalisation).
Not a fitted scaler
This computes its statistics from the list you pass in, so it has no fit/transform split. Scaling a test set with it does not apply the training set's scaler — it fits a new one from the test data, silently corrupting the features and leaking test-set statistics.
For a machine-learning pipeline use Scholar.Preprocessing.StandardScaler,
whose fit/2 and transform/2 are separate for exactly this reason. This
function is for exploratory work on a single dataset.
Examples
iex> NumberF.normalize([10, 20, 30])
[0.0, 0.5, 1.0]Values falling outside the expected spread. method: :iqr (default) or :zscore.
Examples
iex> NumberF.outliers([1, 2, 3, 4, 1000])
[1000]Returns the value at the given percentile (0..100), by linear interpolation.
Examples
iex> NumberF.percentile([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 25)
3.25Returns the first, second and third quartiles.
Examples
iex> NumberF.quartiles([1, 2, 3, 4, 5, 6, 7, 8])
%{q1: 2.75, q2: 4.5, q3: 6.25}Calculates the range (difference between max and min values) of a dataset.
Parameters
numbers: A list of numbers
Examples
iex> NumberF.range([2, 4, 4, 4, 5, 5, 7, 9])
7.0The list with its outliers removed.
Examples
iex> NumberF.remove_outliers([1, 2, 3, 4, 1000])
[1, 2, 3, 4]Calculates the sample standard deviation of a dataset (divides by N-1).
See sample_variance/1. NumberF.standard_deviation/1 is the population form.
Examples
iex> NumberF.sample_standard_deviation([2, 4, 4, 4, 5, 5, 7, 9])
2.138089935299395Calculates the sample variance of a dataset (divides by N-1).
Use this when the list is a sample rather than the whole population.
NumberF.variance/1 is the population form.
Precision
The two differ by a factor of N/(N-1), so they converge as the dataset grows
but diverge sharply for small lists. Most statistical software defaults to the
sample form; this library keeps variance/1 as the population form for
backwards compatibility, so pick one explicitly.
Examples
iex> NumberF.sample_variance([2, 4, 4, 4, 5, 5, 7, 9])
4.571428571428571Calculates standard deviation of a dataset.
Parameters
numbers: A list of numbers
Examples
iex> NumberF.standard_deviation([2, 4, 4, 4, 5, 5, 7, 9])
2.0A one-call description of a dataset: count, min, quartiles, max, mean, stddev.
Examples
iex> NumberF.summary([1, 2, 3, 4, 5]).median
3Mean after discarding a proportion from each end — robust to unreliable extremes.
Examples
iex> NumberF.trimmed_mean([1, 2, 3, 4, 100], 0.2)
3.0Calculates the variance of a dataset.
Parameters
numbers: A list of numbers
Examples
iex> NumberF.variance([2, 4, 4, 4, 5, 5, 7, 9])
4.0Mean weighted by a matching list of weights.
Examples
iex> NumberF.weighted_mean([90, 80, 70], [0.5, 0.3, 0.2])
83.0How many standard deviations a value sits from the mean.
Examples
iex> NumberF.z_score(6, 4, 2)
1.0Standardises a list to zero mean and unit variance.
Not a fitted scaler
This computes its statistics from the list you pass in, so it has no fit/transform split. Scaling a test set with it does not apply the training set's scaler — it fits a new one from the test data, silently corrupting the features and leaking test-set statistics.
For a machine-learning pipeline use Scholar.Preprocessing.StandardScaler,
whose fit/2 and transform/2 are separate for exactly this reason. This
function is for exploratory work on a single dataset.
Examples
iex> NumberF.z_scores([2, 4, 6])
[-1.224744871391589, 0.0, 1.224744871391589]Precision
Checks if two floating point numbers are approximately equal.
Parameters
a: First numberb: Second numberepsilon: Maximum allowed difference (default: 1.0e-10)
Examples
iex> NumberF.approximately_equal(0.1 + 0.2, 0.3)
true
iex> NumberF.approximately_equal(0.1, 0.2)
falseRounds a number using banker's rounding (round to even). This is more statistically unbiased than standard rounding.
Parameters
number: The number to roundprecision: Number of decimal places (default: 2)
Examples
iex> NumberF.bankers_round(2.5, 0)
2.0
iex> NumberF.bankers_round(3.5, 0)
4.0Rounds a number up to a specified precision (ceiling).
Parameters
number: The number to roundprecision: Number of decimal places (default: 2)
Examples
iex> NumberF.ceiling(3.14159, 2)
3.15
iex> NumberF.ceiling(3.14159, 1)
3.2Constrains a value to a range.
Examples
iex> NumberF.clamp(15, 0, 10)
10
iex> NumberF.clamp(-5, 0, 10)
0Rounds to a precision using an explicit mode.
Modes: :half_up (default), :half_down, :half_even, :ceiling, :floor,
:truncate.
Examples
iex> NumberF.custom_round(2.565, 2, :half_down)
2.56Rounds a number down to a specified precision (floor).
Parameters
number: The number to roundprecision: Number of decimal places (default: 2)
Examples
iex> NumberF.floor(3.14159, 2)
3.14
iex> NumberF.floor(3.14159, 1)
3.1Formats a number to a fixed number of decimal places, padding with zeros.
Unlike round_to/3, trailing zeros are preserved, so the width is stable.
Examples
iex> NumberF.precise_format(3.14159, 3)
"3.142"Rounds half away from zero — "round half up" as most people mean it.
Contrast bankers_round/2, which rounds half to even to avoid upward bias.
Examples
iex> NumberF.round_half_away_from_zero(-2.5, 0)
-3.0Rounds half to even. A discoverable alias for bankers_round/2.
Examples
iex> NumberF.round_half_even(2.5, 0)
2.0Rounds a number to a specific increment.
Parameters
number: The number to roundincrement: The increment to round to (default: 1.0)strategy: The rounding strategy (:nearest, :up, :down, or :bankers)
Examples
iex> NumberF.round_to(3.14159, 0.05, :nearest)
3.15
iex> NumberF.round_to(3.14159, 0.1, :up)
3.2
iex> NumberF.round_to(3.14159, 0.1, :down)
3.1Rounds a number to a specified number of decimal places.
Parameters
number: The number to roundprecision: Number of decimal places (default: 2)
Examples
iex> NumberF.round_with_precision(3.14159, 2)
3.14
iex> NumberF.round_with_precision(3.14159, 4)
3.1416Divides, returning default instead of raising when the denominator is zero.
Examples
iex> NumberF.safe_divide(10, 0)
0.0
iex> NumberF.safe_divide(10, 4)
2.5Replaces non-finite float values with a safe default.
Examples
iex> NumberF.sanitize_float(:nan)
0.0Returns -1, 0 or 1 according to the sign of the number.
Examples
iex> NumberF.sign(-4.2)
-1Truncates a number to a precision, cutting digits rather than rounding.
Examples
iex> NumberF.truncate(3.999, 2)
3.99Validation
Identifies a card network from its number.
Examples
iex> NumberF.card_brand("4111111111111111")
:visaValidates credit card numbers using the Luhn algorithm.
Parameters
number: The credit card number as a stringtype: Card type to validate against (default: :any)- Options: :any, :visa, :mastercard, :amex, :discover
Examples
iex> NumberF.is_valid_credit_card?("4111111111111111")
true
iex> NumberF.is_valid_credit_card?("4111111111111112")
falseChecks if a string is a valid integer.
Parameters
str: The string to check
Examples
iex> NumberF.is_valid_integer?("123")
true
iex> NumberF.is_valid_integer?("123.45")
falseChecks if a string is a valid number format.
Parameters
str: The string to check
Examples
iex> NumberF.is_valid_number?("123")
true
iex> NumberF.is_valid_number?("123.45")
true
iex> NumberF.is_valid_number?("abc")
falseComputes the Luhn check digit for a number.
Examples
iex> NumberF.luhn_check_digit("411111111111111")
1Whether the code is a currency this library knows.
Examples
iex> NumberF.valid_currency_code?("USD")
trueValidates an EAN-8 or EAN-13 barcode.
Examples
iex> NumberF.valid_ean?("4006381333931")
trueValidates an IBAN by its mod-97 checksum.
Examples
iex> NumberF.valid_iban?("GB82 WEST 1234 5698 7654 32")
trueValidates a 15-digit IMEI.
Examples
iex> NumberF.valid_imei?("490154203237518")
trueValidates an ISBN-10 or ISBN-13.
Examples
iex> NumberF.valid_isbn?("978-3-16-148410-0")
trueValidates any Luhn-checksummed number.
Examples
iex> NumberF.valid_luhn?("4111111111111111")
trueWhether a value is a number in 0..100.
Examples
iex> NumberF.valid_percentage?(42.5)
trueValidates a US ABA routing number.
Examples
iex> NumberF.valid_routing_number?("021000021")
trueValidates a UPC-A barcode.
Examples
iex> NumberF.valid_upc?("036000291452")
trueMath
Calculates combinations (n choose k).
Parameters
n: The total number of itemsk: The number of items to choose
Examples
iex> NumberF.combinations(5, 2)
10
iex> NumberF.combinations(10, 3)
120Sum of the decimal digits.
Examples
iex> NumberF.digit_sum(12345)
15Repeatedly sums the digits until one remains.
Examples
iex> NumberF.digital_root(12345)
6The decimal digits of an integer.
Examples
iex> NumberF.digits(12345)
[1, 2, 3, 4, 5]All positive divisors of n, ascending.
Examples
iex> NumberF.divisors(28)
[1, 2, 4, 7, 14, 28]Calculates the factorial of a non-negative integer.
Parameters
n: The non-negative integer
Examples
iex> NumberF.factorial(5)
120
iex> NumberF.factorial(0)
1The nth Fibonacci number, exact for any n.
Examples
iex> NumberF.fibonacci(10)
55The first n Fibonacci numbers.
Examples
iex> NumberF.fibonacci_sequence(8)
[0, 1, 1, 2, 3, 5, 8, 13]Parses an integer written in a base from 2 to 36.
Examples
iex> NumberF.from_base("FF", 16)
255Parses a binary integer.
Examples
iex> NumberF.from_binary("101")
5Parses a hexadecimal integer.
Examples
iex> NumberF.from_hex("FF")
255Parses an octal integer.
Examples
iex> NumberF.from_octal("10")
8Calculates the Greatest Common Divisor (GCD) of two integers.
Parameters
a: First integerb: Second integer
Examples
iex> NumberF.gcd(48, 18)
6
iex> NumberF.gcd(7, 13)
1Checks if a number is within a specified range (inclusive).
Parameters
value: The number to checkmin: The minimum value of the rangemax: The maximum value of the range
Examples
iex> NumberF.in_range?(5, 1, 10)
true
iex> NumberF.in_range?(15, 1, 10)
falsePerforms a linear interpolation between two points.
Parameters
x: The x value to interpolate atx0: The x coordinate of the first pointy0: The y coordinate of the first pointx1: The x coordinate of the second pointy1: The y coordinate of the second point
Examples
iex> NumberF.interpolate(2.5, 2, 10, 3, 20)
15.0Checks if a number is prime.
Parameters
n: The number to check
Examples
iex> NumberF.is_prime?(7)
true
iex> NumberF.is_prime?(6)
falseCalculates the Least Common Multiple (LCM) of two integers.
Parameters
a: First integerb: Second integer
Examples
iex> NumberF.lcm(4, 6)
12
iex> NumberF.lcm(21, 6)
42Logarithm in an arbitrary base.
Examples
iex> NumberF.log_base(1024, 2)
10.0The real nth root of a number.
Examples
iex> NumberF.nth_root(27, 3)
3.0Whether the digits read the same both ways.
Examples
iex> NumberF.palindrome?(12321)
trueCalculates a percentage with specified precision.
Parameters
value: The value to calculate percentage fortotal: The total value (100%)precision: Number of decimal places (default: 2)
Examples
iex> NumberF.percentage(25, 100)
25.0
iex> NumberF.percentage(1, 3, 2)
33.33Whether n is a perfect square, without float error.
Examples
iex> NumberF.perfect_square?(144)
trueOrdered arrangements of k items from n (nPk).
Examples
iex> NumberF.permutations(5, 2)
20Prime factorisation, ascending and with repeats.
Examples
iex> NumberF.prime_factors(360)
[2, 2, 2, 3, 3, 5]The integer with its digits reversed.
Examples
iex> NumberF.reverse_number(12345)
54321Rounds a number to the nearest specified value.
Parameters
value: The number to roundnearest: The nearest value to round to (default: 1.0)
Examples
iex> NumberF.round_to_nearest(12.3)
12.0
iex> NumberF.round_to_nearest(12.3, 5)
10.0
iex> NumberF.round_to_nearest(12.3, 0.5)
12.5Renders an integer in a base from 2 to 36.
Examples
iex> NumberF.to_base(255, 16)
"FF"Renders an integer in binary.
Examples
iex> NumberF.to_binary(5)
"101"Converts radians to degrees.
Parameters
radians: The angle in radians
Examples
iex> NumberF.to_degrees(3.14159)
179.99984796050427Renders an integer in hexadecimal.
Examples
iex> NumberF.to_hex(255)
"FF"Renders an integer in octal.
Examples
iex> NumberF.to_octal(8)
"10"Converts degrees to radians.
Parameters
degrees: The angle in degrees
Examples
iex> NumberF.to_radians(180)
3.141592653589793Units
Converts acres to hectares.
Area conversion factors, relative to square metres.
Converts Celsius to Fahrenheit.
Parameters
celsius: The temperature in Celsius
Examples
iex> NumberF.celsius_to_fahrenheit(0)
32.0
iex> NumberF.celsius_to_fahrenheit(100)
212.0Converts centimeters to inches.
Parameters
cm: The length in centimeters
Examples
iex> NumberF.cm_to_inches(25.4)
10.0Converts between arbitrary units from one of the unit tables.
Unit keys are strings, not atoms.
Examples
iex> NumberF.convert_units(100, "km", "mi", NumberF.length_units()) |> Float.round(2)
62.14Converts Fahrenheit to Celsius.
Parameters
fahrenheit: The temperature in Fahrenheit
Examples
iex> NumberF.fahrenheit_to_celsius(32)
0.0
iex> NumberF.fahrenheit_to_celsius(212)
100.0Converts hectares to acres.
Converts inches to centimeters.
Parameters
inches: The length in inches
Examples
iex> NumberF.inches_to_cm(10)
25.4
iex> NumberF.inches_to_cm(3.5)
8.89Converts kilograms to pounds.
Parameters
kg: The weight in kilograms
Examples
iex> NumberF.kg_to_pounds(4.54)
10.01Converts kilometers to miles.
Parameters
km: The distance in kilometers
Examples
iex> NumberF.km_to_miles(16.09)
10.0Length conversion factors, relative to metres.
Converts miles to kilometers.
Parameters
miles: The distance in miles
Examples
iex> NumberF.miles_to_km(10)
16.09Converts millilitres to fluid ounces.
Converts fluid ounces to millilitres.
Converts pounds to kilograms.
Volume conversion factors, relative to litres.
Weight conversion factors, relative to kilograms.
Dates
Adds business days to a date. A negative count subtracts them.
Examples
iex> NumberF.add_business_days(~D[2024-01-15], -3)
~D[2024-01-10]Age in whole months.
Examples
iex> NumberF.age_in_months(~D[2020-01-15], ~D[2024-08-22])
55Calculates the number of business days between two dates.
Parameters
date1: The first datedate2: The second date
Examples
iex> NumberF.business_days_between(~D[2023-01-02], ~D[2023-01-08])
5Calculates age based on birth date.
Parameters
birth_date: Birth date as Date struct
Examples
iex> birth_date = ~D[1990-01-15]
iex> age = NumberF.calculate_age(birth_date)
iex> is_integer(age) and age >= 0
trueCalculates the number of days between two dates.
Parameters
date1: The first datedate2: The second date
Examples
iex> NumberF.days_between(~D[2023-01-01], ~D[2023-01-10])
9Number of days in a month.
Examples
iex> NumberF.days_in_month(2024, 2)
29Fiscal year containing the date, named for the year it ends in.
Examples
iex> NumberF.fiscal_year(~D[2024-08-22], 4)
2025Determines if a date is a business day.
Parameters
date: The date to check
Examples
iex> NumberF.is_business_day?(~D[2023-01-02])
true
iex> NumberF.is_business_day?(~D[2023-01-01])
falseWhether a year is a leap year.
Examples
iex> NumberF.leap_year?(2024)
trueLast day of the date's month.
Examples
iex> NumberF.month_end(~D[2024-02-10])
~D[2024-02-29]First day of the date's month.
Examples
iex> NumberF.month_start(~D[2024-08-22])
~D[2024-08-01]Returns the next business day after the given date.
Examples
iex> NumberF.next_business_day(~D[2024-01-12])
~D[2024-01-15]Calculates payment due date based on invoice date and terms.
Parameters
invoice_date: The invoice date as Date structterms_days: Payment terms in days (default: 30)
Examples
iex> invoice_date = ~D[2023-01-15]
iex> NumberF.payment_due_date(invoice_date)
~D[2023-02-14]
iex> invoice_date = ~D[2023-01-15]
iex> NumberF.payment_due_date(invoice_date, 45)
~D[2023-03-01]Calendar quarter of a date, 1 to 4.
Examples
iex> NumberF.quarter(~D[2024-08-22])
3Last day of the date's quarter.
Examples
iex> NumberF.quarter_end(~D[2024-08-22])
~D[2024-09-30]First day of the date's quarter.
Examples
iex> NumberF.quarter_start(~D[2024-08-22])
~D[2024-07-01]ISO-8601 week number.
Examples
iex> NumberF.week_number(~D[2024-08-22])
34Humanize
Generates a default password with pre-defined complexity. The pattern is: capitalized 3-letter string + @ + 4 random digits.
Examples
iex> result = NumberF.default_password()
iex> String.length(result) == 8 and String.contains?(result, "@")
trueConverts a memory size in bytes to a human-readable format. Automatically selects the appropriate unit (B, KB, MB, GB) based on size.
Parameters
size: The size in bytes
Examples
iex> NumberF.memory_size_cal(500)
"500 B"
iex> NumberF.memory_size_cal(1024)
"1.0 KB"
iex> NumberF.memory_size_cal(1048576)
"1.0 MB"
iex> NumberF.memory_size_cal(1073741824)
"1.0 GB"Generates a random string of the specified length.
Parameters
length: The length of the stringtype: Type of string, with options::all(alphanumeric) - default:alpha(alphabetical):numeric(numbers):upcase(uppercase):downcase(lowercase)
Examples
iex> result = NumberF.randomizer(10)
iex> String.length(result)
10
iex> result = NumberF.randomizer(5, :numeric)
iex> String.length(result) == 5 and String.match?(result, ~r/^[0-9]+$/)
true
iex> result = NumberF.randomizer(6, :upcase)
iex> String.length(result) == 6 and Regex.match?(~r/^[A-Z]+$/, result)
trueInternationalization
Formats a number as currency according to locale-specific settings.
Features
- Supports 100+ international locale formats
- Proper positioning of currency symbols
- Correct thousands and decimal separators for each locale
- Configurable precision and currency code
Parameters
number: The number to formatlocale: The locale code (e.g., "en-US", "fr-FR")options: Additional formatting options:precision: Number of decimal places (default: 2):currency_code: ISO currency code to override the locale default:symbol: Whether to include the currency symbol (default: true)
Examples
iex> NumberF.format_currency(1234.56, "en-US")
"$1,234.56"
iex> NumberF.format_currency(1234.56, "fr-FR")
"1 234,56 €"
iex> NumberF.format_currency(1234.56, "de-DE", currency_code: "USD")
"1.234,56 $"
iex> NumberF.format_currency(1234.56, "en-US", symbol: false)
"1,234.56"Supported Locales
This function supports all major world locales including but not limited to: en-US, en-GB, fr-FR, de-DE, es-ES, it-IT, ja-JP, zh-CN, ru-RU, pt-BR, and many more.
Common Use Cases
- Multi-language applications
- Financial applications with international users
- E-commerce with global customers
- Travel and currency conversion applications
Related Functions
NumberF.format_number/3: Format without currency symbolsNumberF.I18n.get_locale_settings/1: Get formatting rules for a localeNumberF.spell_number/3: Spell out numbers in different languages
See also: NumberF.I18n for more internationalization functions.
Formats a number according to locale-specific settings.
Parameters
number: The number to formatlocale: The locale code (e.g., "en-US", "fr-FR")options: Additional formatting options:precision: Number of decimal places (default: 2)
Examples
iex> NumberF.format_number(1234567.89, "en-US")
"1,234,567.89"
iex> NumberF.format_number(1234567.89, "fr-FR")
"1 234 567,89"Returns the main and sub unit names for a currency in a given language.
Returns the formatting settings for a locale.
Examples
iex> NumberF.get_locale_settings("en-US").currency_symbol
"$"Parses a locale-formatted number string back into a number.
Examples
iex> NumberF.parse_number("1.234,56", "de-DE")
1234.56Spells out a number in the specified language.
Parameters
number: The number to spell outlanguage: The language code (e.g., "en", "fr")options: Additional options:capitalize: Whether to capitalize the first letter (default: true):currency: Whether to add currency names (default: false):currency_code: ISO currency code (default: nil)
Examples
iex> NumberF.spell_number(42, "en")
"Forty-two"
iex> NumberF.spell_number(42, "fr")
"Quarante-deux"Lists the languages NumberF.spell_number/3 can spell numbers in.
Deliberately distinct from the 22 locales NumberF.format_number/2 supports:
formatting a locale and spelling its language are different capabilities, and
conflating them is how an unsupported language used to return English silently.
Examples
iex> NumberF.spelling_languages()
["de", "en", "es", "fr"]Introspection
Returns metadata for a single function category.
Returns a markdown documentation of all NumberF modules and functions.
Examples
iex> markdown = NumberF.documentation()
iex> String.starts_with?(markdown, "# NumberF Library")
trueReturns all function categories available in NumberF.
Examples
iex> NumberF.function_categories() |> Enum.map(& &1.name) |> Enum.take(3)
["Formatting", "Conversion", "Generation"]Returns metadata for a single NumberF module.
Returns information about all NumberF modules.
Examples
iex> NumberF.modules() |> Enum.map(& &1.name) |> Enum.take(3)
["NumberF", "NumberF.Currency", "NumberF.CustomFormatter"]Returns information about NumberF modules of a specific type.
Parameters
type: The module type (e.g., :formatting, :calculation)
Examples
iex> NumberF.modules_by_type(:formatting) |> Enum.map(& &1.name)
["NumberF.Currency", "NumberF.CustomFormatter", "NumberF.Formatter", "NumberF.Currencies"]Returns all modules and their functions as a reference.
This function provides a comprehensive overview of all available functionality in the NumberF library, organized by module.
Examples
iex> ref = NumberF.reference()
iex> is_map(ref)
true