NumberF (NumberF v0.1.8)

View Source

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.2.0"}
]
end

Key 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.0

Internationalization & 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:

While specific functions can be accessed through their respective modules, most common functionality is available directly from the main NumberF module for convenience.

For more information, see the full documentation on HexDocs.

Summary

Functions

Formats large numbers as K, M, B (e.g., 1.2K, 3.4M).

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.

Calculates the number of business days between two dates.

Calculates age based on birth date.

Calculates Equated Monthly Installment (EMI) for loans.

Calculates sales tax for a given amount and rate.

Calculates Value Added Tax (VAT) for a given amount and rate.

Converts Celsius to Fahrenheit.

Converts centimeters to inches.

Calculates combinations (n choose k).

Formats a number into comma-separated format with the specified precision.

Calculates compound interest with optional compounding frequency.

Converts an amount between currencies based on exchange rates.

Formats a number into currency with the specified unit and precision.

Returns a map of currency information with ISO codes, symbols, and formatting details.

Calculates the number of days between two dates.

Generates a default password with pre-defined complexity. The pattern is: capitalized 3-letter string + @ + 4 random digits.

Returns a markdown documentation of all NumberF modules and functions.

Calculates the factorial of a non-negative integer.

Converts Fahrenheit to Celsius.

Formats a number as currency according to locale-specific settings.

Formats a number according to locale-specific settings.

Formats phone numbers based on country code.

Formats a currency with the specified currency code's rules.

Converts Roman numerals to Arabic numbers.

Returns all function categories available in NumberF.

Calculates the Greatest Common Divisor (GCD) of two integers.

Gets currency details for a specific currency code.

Checks if a number is within a specified range (inclusive).

Converts inches to centimeters.

Performs a linear interpolation between two points.

Determines if a date is a business day.

Checks if a number is prime.

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.

Converts kilometers to miles.

Calculates the Least Common Multiple (LCM) of two integers.

Calculates the arithmetic mean of a list of numbers.

Finds the median value from a list of numbers.

Converts a memory size in bytes to a human-readable format. Automatically selects the appropriate unit (B, KB, MB, GB) based on size.

Converts miles to kilometers.

Finds the most frequently occurring value(s) in a list.

Returns information about all NumberF modules.

Returns information about NumberF modules of a specific type.

Formats a number into a delimited format with options for customization.

Converts numbers to ordinals (1st, 2nd, 3rd, etc.).

Calculates payment due date based on invoice date and terms.

Calculates a percentage with specified precision.

Generates a random string of the specified length.

Calculates the range (difference between max and min values) of a dataset.

Returns all modules and their functions as a reference.

Rounds a number to the nearest specified value.

Rounds a number to a specified number of decimal places.

Calculates simple interest based on principal, rate and time.

Spells out a number in the specified language.

Calculates standard deviation of a dataset.

Sums a list of decimal numbers.

Converts a string to a boolean value.

Converts a value to a decimal.

Converts radians to degrees.

Converts a value to a float.

Converts a string to an integer.

Converts degrees to radians.

Converts Arabic numbers to Roman numerals.

Converts a number into words with customizable currency terms.

Calculates the variance of a dataset.

Returns common VAT rates for different countries.

Functions

abbreviate_number(number, precision \\ 1)

Formats large numbers as K, M, B (e.g., 1.2K, 3.4M).

Parameters

  • number: The number to abbreviate
  • precision: 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"

approximately_equal(a, b, epsilon \\ 1.0e-10)

Checks if two floating point numbers are approximately equal.

Parameters

  • a: First number
  • b: Second number
  • epsilon: 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)
false

bankers_round(number, precision \\ 2)

Rounds a number using banker's rounding (round to even). This is more statistically unbiased than standard rounding.

Parameters

  • number: The number to round
  • precision: Number of decimal places (default: 2)

Examples

iex> NumberF.bankers_round(2.5, 0)
2.0

iex> NumberF.bankers_round(3.5, 0)
4.0

business_days_between(date1, date2)

Calculates the number of business days between two dates.

Parameters

  • date1: The first date
  • date2: The second date

Examples

iex> NumberF.business_days_between(~D[2023-01-02], ~D[2023-01-08])
5

calculate_age(birth_date)

Calculates 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)
# Returns the current age based on today's date

calculate_emi(principal, rate, term_months)

Calculates Equated Monthly Installment (EMI) for loans.

Parameters

  • principal: The loan amount
  • rate: 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.59

calculate_sales_tax(amount, rate, options \\ [])

Calculates sales tax for a given amount and rate.

Parameters

  • amount: The amount before tax
  • rate: 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}

calculate_vat(amount, rate, included \\ false)

Calculates Value Added Tax (VAT) for a given amount and rate.

Parameters

  • amount: The amount before tax
  • rate: 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}

celsius_to_fahrenheit(celsius)

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.0

cm_to_inches(cm)

Converts centimeters to inches.

Parameters

  • cm: The length in centimeters

Examples

iex> NumberF.cm_to_inches(25.4)
10.0

combinations(n, k)

Calculates combinations (n choose k).

Parameters

  • n: The total number of items
  • k: The number of items to choose

Examples

iex> NumberF.combinations(5, 2)
10.0

iex> NumberF.combinations(10, 3)
120.0

comma_separated(number, precision \\ 2)

Formats a number into comma-separated format with the specified precision.

Parameters

  • number: The number to format
  • precision: 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)
nil

compound_interest(principal, rate, time, frequency \\ 1)

Calculates 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 amount
  • rate: The annual interest rate as a decimal (e.g., 0.05 for 5%)
  • time: The time period in years
  • frequency: 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)
4693.28  # Quarterly compounding (4 times per year)

Formula

The compound interest is calculated using the formula:

A = P(1 + r/n)^(nt) - P

Where:

  • 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

See also: NumberF.Financial for more financial calculations.

convert_currency(amount, from_rate, to_rate)

Converts an amount between currencies based on exchange rates.

Parameters

  • amount: The amount to convert
  • from_rate: The exchange rate of the source currency
  • to_rate: The exchange rate of the target currency

Examples

iex> NumberF.convert_currency(100, 1, 1.1)
110.0

currency(number, unit \\ "ZMW", precision \\ 2)

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 format
  • unit: 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)
nil

Common Use Cases

  • Financial reporting and analysis
  • E-commerce price displays
  • Invoice and receipt generation
  • Banking and financial applications

See also: NumberF.Currencies for currency-specific information.

currency_data()

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: "."
}

days_between(date1, date2)

Calculates the number of days between two dates.

Parameters

  • date1: The first date
  • date2: The second date

Examples

iex> NumberF.days_between(~D[2023-01-01], ~D[2023-01-10])
9

default_password()

Generates a default password with pre-defined complexity. The pattern is: capitalized 3-letter string + @ + 4 random digits.

Examples

iex> NumberF.default_password()
"Dev@2308" # Example output, actual value will vary

documentation()

Returns a markdown documentation of all NumberF modules and functions.

Examples

iex> markdown = NumberF.documentation()
iex> String.starts_with?(markdown, "# NumberF Library")
true

factorial(n)

Calculates the factorial of a non-negative integer.

Parameters

  • n: The non-negative integer

Examples

iex> NumberF.factorial(5)
120

iex> NumberF.factorial(0)
1

fahrenheit_to_celsius(fahrenheit)

Converts 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.0

format_currency(number, locale, options \\ [])

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 format
  • locale: 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

See also: NumberF.I18n for more internationalization functions.

format_number(number, locale, options \\ [])

Formats a number according to locale-specific settings.

Parameters

  • number: The number to format
  • locale: 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"

format_phone(number, country_code \\ "ZM")

Formats phone numbers based on country code.

Parameters

  • number: The phone number as a string
  • country_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"

format_with_currency(number, currency_code, options \\ [])

Formats a currency with the specified currency code's rules.

Parameters

  • number: The number to format
  • currency_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 €"

from_roman(roman)

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")
1999

function_categories()

Returns all function categories available in NumberF.

Examples

iex> NumberF.function_categories() |> Enum.map(& &1.name) |> Enum.take(3)
["Formatting", "Conversion", "Generation"]

gcd(a, b)

Calculates the Greatest Common Divisor (GCD) of two integers.

Parameters

  • a: First integer
  • b: Second integer

Examples

iex> NumberF.gcd(48, 18)
6

iex> NumberF.gcd(7, 13)
1

get_currency(currency_code)

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: "."
}

in_range?(value, min, max)

Checks if a number is within a specified range (inclusive).

Parameters

  • value: The number to check
  • min: The minimum value of the range
  • max: The maximum value of the range

Examples

iex> NumberF.in_range?(5, 1, 10)
true

iex> NumberF.in_range?(15, 1, 10)
false

inches_to_cm(inches)

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.89

interpolate(x, x0, y0, x1, y1)

Performs a linear interpolation between two points.

Parameters

  • x: The x value to interpolate at
  • x0: The x coordinate of the first point
  • y0: The y coordinate of the first point
  • x1: The x coordinate of the second point
  • y1: The y coordinate of the second point

Examples

iex> NumberF.interpolate(2.5, 2, 10, 3, 20)
15.0

is_business_day?(date)

Determines 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])
false

is_prime?(n)

Checks if a number is prime.

Parameters

  • n: The number to check

Examples

iex> NumberF.is_prime?(7)
true

iex> NumberF.is_prime?(6)
false

is_valid_credit_card?(number, type \\ :any)

Validates credit card numbers using the Luhn algorithm.

Parameters

  • number: The credit card number as a string
  • type: 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")
false

is_valid_integer?(str)

Checks 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")
false

is_valid_number?(str)

Checks 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")
false

km_to_miles(km)

Converts kilometers to miles.

Parameters

  • km: The distance in kilometers

Examples

iex> NumberF.km_to_miles(16.09)
10.0

lcm(a, b)

Calculates the Least Common Multiple (LCM) of two integers.

Parameters

  • a: First integer
  • b: Second integer

Examples

iex> NumberF.lcm(4, 6)
12

iex> NumberF.lcm(21, 6)
42

mean(numbers)

Calculates 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([])
nil

Mathematical 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

See also: NumberF.Statistics for more statistical functions.

median(numbers)

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.0

memory_size_cal(size)

Converts 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"

miles_to_km(miles)

Converts miles to kilometers.

Parameters

  • miles: The distance in miles

Examples

iex> NumberF.miles_to_km(10)
16.09

mode(numbers)

Finds 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]

modules()

Returns information about all NumberF modules.

Examples

iex> NumberF.modules() |> Enum.map(& &1.name) |> Enum.take(3)
["NumberF", "NumberF.Registry", "NumberF.Currency"]

modules_by_type(type)

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"]

number_to_delimited(number, options \\ [])

Formats a number into a delimited format with options for customization.

Parameters

  • number: The number to format
  • options: 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"

ordinal(number)

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"

payment_due_date(invoice_date, terms_days \\ 30)

Calculates payment due date based on invoice date and terms.

Parameters

  • invoice_date: The invoice date as Date struct
  • terms_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]

percentage(value, total, precision \\ 2)

Calculates a percentage with specified precision.

Parameters

  • value: The value to calculate percentage for
  • total: 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.33

randomizer(length, type \\ :all)

Generates a random string of the specified length.

Parameters

  • length: The length of the string
  • type: Type of string, with options:
    • :all (alphanumeric) - default
    • :alpha (alphabetical)
    • :numeric (numbers)
    • :upcase (uppercase)
    • :downcase (lowercase)

Examples

iex> NumberF.randomizer(10)
"a1B2c3D4e5" # Example output, actual value will vary

iex> NumberF.randomizer(5, :numeric)
"23579" # Example output, actual value will vary

iex> NumberF.randomizer(6, :upcase)
"ABCDEF" # Example output, actual value will vary

range(numbers)

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.0

reference()

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

round_to_nearest(value, nearest \\ 1.0)

Rounds a number to the nearest specified value.

Parameters

  • value: The number to round
  • nearest: 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.5

round_with_precision(number, precision \\ 2)

Rounds a number to a specified number of decimal places.

Parameters

  • number: The number to round
  • precision: 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.1416

simple_interest(principal, rate, time)

Calculates simple interest based on principal, rate and time.

Parameters

  • principal: The principal amount
  • rate: 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.0

spell_number(number, language, options \\ [])

Spells out a number in the specified language.

Parameters

  • number: The number to spell out
  • language: 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"

standard_deviation(numbers)

Calculates 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.0

sum_decimal(list)

Sums a list of decimal numbers.

Parameters

  • list: A list of decimal values, potentially nested

Examples

iex> sum_decimal([Decimal.new("1.2"), Decimal.new("3.4"), [Decimal.new("5.6")]])
#Decimal<10.2>

iex> sum_decimal([])
#Decimal<0>

This function flattens any nested lists, then uses Enum.reduce/3 to sum all the decimal values.

to_boolean(value)

Converts a string to a boolean value.

Parameters

  • value: The string value to convert. Accepts the following:
    • true, yes, on convert to true
    • false, no, off convert to false
    • 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")
false

to_decimal(value)

Converts a value to a decimal.

Parameters

  • value: The value to convert (string or number)

Examples

iex> NumberF.to_decimal("123.45")
#Decimal<123.45>

iex> NumberF.to_decimal(123)
#Decimal<123>

to_degrees(radians)

Converts radians to degrees.

Parameters

  • radians: The angle in radians

Examples

iex> NumberF.to_degrees(3.14159)
180.0

to_float(value)

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.0

to_int(value)

Converts 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")
123

to_radians(degrees)

Converts degrees to radians.

Parameters

  • degrees: The angle in degrees

Examples

iex> NumberF.to_radians(180)
3.141592653589793

to_roman(number)

Converts 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"

to_words(amount, main_currence \\ "Kwacha", sec_current \\ "Ngwee")

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 convert
  • main_currency: The main currency name (default: "Kwacha")
  • sec_currency: The secondary currency name (default: "Ngwee")

Examples

iex> NumberF.to_words(20.0)
"Twenty Kwacha and zero Ngwee"

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

See also: NumberF.NumbersToWords for more advanced word conversion options.

variance(numbers)

Calculates the variance of a dataset.

Parameters

  • numbers: A list of numbers

Examples

iex> NumberF.variance([2, 4, 4, 4, 5, 5, 7, 9])
4.0

vat_rates()

Returns common VAT rates for different countries.

Examples

iex> NumberF.vat_rates()["UK"]
0.2

iex> NumberF.vat_rates()["Germany"]
0.19