NumberF (NumberF v0.1.4)

View Source

NumberF

A comprehensive utility module for performing various number-related operations in Elixir.

Features

Installation

Add number_f to your list of dependencies in mix.exs:

def deps do
[
  {:number_f, "~> 0.1.3"}
]
end

Formatting

  • Format numbers as currency values with custom units
  • Create comma-separated number formats
  • Custom number delimiter formatting

Conversion

  • Convert numbers to words representation
  • Convert between various numeric types (int, float, decimal)
  • Convert strings to boolean values

Generation

  • Generate random strings with customizable properties
  • Create default passwords with predefined patterns

Utilities

  • Convert memory sizes to human-readable formats
  • Sum decimal values, including in nested lists

Examples

# Currency formatting
NumberF.currency(1234.567)                    # => "ZMW 1,234.57"
NumberF.currency(1234.567, "USD", 2)          # => "USD 1,234.57"
NumberF.comma_separated(1234567.89)           # => "1,234,567.89"

# Numbers to words
NumberF.to_words(20.0)                        # => "Twenty Kwacha and zero Ngwee"
NumberF.to_words(42.75, "Dollars", "Cents")   # => "Forty Two Dollars And Seventy Five Cents"

# Random generation
NumberF.randomizer(10)                        # => "a1B2c3D4e5"
NumberF.default_password()                    # => "Dev@2308"

# Memory size humanization
NumberF.memory_size_cal(1048576)              # => "1.0 MB"

# Type conversions
NumberF.to_int("123")                         # => 123
NumberF.to_float("123.45")                    # => 123.45
NumberF.to_decimal("123.45")                  # => #Decimal<123.45>
NumberF.to_boolean("yes")                     # => true

# Custom formatting
NumberF.number_to_delimited(1234567.89, delimiter: ".", separator: ",") # => "1.234.567,89"

Summary

Functions

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

Calculates age based on birth date.

Calculates Equated Monthly Installment (EMI) for loans.

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.

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

Formats phone numbers based on country code.

Converts Roman numerals to Arabic numbers.

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

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.

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.

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

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.

Rounds a number to the nearest specified value.

Calculates simple interest based on principal, rate and time.

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 a value to a float.

Converts a string to an integer.

Converts Arabic numbers to Roman numerals.

Converts a number into words with customizable currency terms.

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"

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

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.

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

iex> NumberF.compound_interest(1000, 0.05, 2, 12)
104.94

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.

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(nil, "USD", 2)
nil

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

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"

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

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

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

mean(numbers)

Calculates the arithmetic mean of a list of numbers.

Parameters

  • numbers: A list of numbers

Examples

iex> NumberF.mean([1, 2, 3, 4, 5])
3.0

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"

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]

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

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

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

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

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(0, "Euros", "Cents")
"zero Euros"