SoftBank.Note (soft_bank v0.1.3) View Source

Defines a SoftBank.Note struct along with convenience methods for working with currencies.

Example:

iex> note = SoftBank.Note.new(500, :USD)
%SoftBank.Note{amount: 500, currency: :USD}
iex> note = SoftBank.Note.add(note, 550)
%SoftBank.Note{amount: 1050, currency: :USD}
iex> SoftBank.Note.to_string(note)
"$10.50"

Configuration options

You can set defaults in your Mix configuration to make working with SoftBank.Note a little easier.

Configuration:

config :note,
  default_currency: :EUR,  # this allows you to do SoftBank.Note.new(100)
  separator: ".",          # change the default thousands separator for SoftBank.Note.to_string
  delimiter: ",",          # change the default decimal delimeter for SoftBank.Note.to_string
  symbol: false            # don’t display the currency symbol in SoftBank.Note.to_string
  symbol_on_right: false,  # position the symbol
  symbol_space: false      # add a space between symbol and number
  fractional_unit: false   # don’t display the remainder or the delimeter

Link to this section Summary

Functions

abs(note)

Returns a SoftBank.Note with the arithmetical absolute of the amount.

add(m, addend)

Adds two SoftBank.Note together or an integer (cents) amount to a SoftBank.Note

compare(a, b)

Compares two SoftBank.Note structs with each other. They must each be of the same currency and then their amounts are compared

divide(note, denominator)

Divides up SoftBank.Note by an amount

equals?(a, b)

Returns true if two SoftBank.Note of the same currency have the same amount

multiply(note, multiplier)

Multiplies a SoftBank.Note by an amount

neg(note)

Returns a SoftBank.Note with the amount negated.

negative?(note)

Returns true if the amount of a SoftBank.Note is less than zero

new(amount)

Create a new SoftBank.Note struct using a default currency. The default currency can be set in the system Mix config.

new(int, currency)

Create a new SoftBank.Note struct from currency sub-units (cents)

parse(value, currency \\ nil, opts \\ [])

Parse a value into a SoftBank.Note type.

parse!(value, currency \\ nil, opts \\ [])

Parse a value into a SoftBank.Note type. Similar to parse/3 but returns a %SoftBank.Note{} or raises an error if parsing fails.

positive?(note)

Returns true if the amount of a SoftBank.Note is greater than zero

subtract(m, subtractend)

Subtracts one SoftBank.Note from another or an integer (cents) from a SoftBank.Note

to_string(note, opts \\ [])

Converts a SoftBank.Note struct to a string representation

zero?(note)

Returns true if the amount of a SoftBank.Note struct is zero

Link to this section Types

t()

Specs

t() :: %SoftBank.Note{amount: Money.Ecto.Composite.Type, currency: atom()}

Link to this section Functions

abs(note)

Specs

abs(t()) :: t()

Returns a SoftBank.Note with the arithmetical absolute of the amount.

Examples:

iex> SoftBank.Note.new(-100, :USD) |> SoftBank.Note.abs
%SoftBank.Note{amount: 100, currency: :USD}
iex> SoftBank.Note.new(100, :USD) |> SoftBank.Note.abs
%SoftBank.Note{amount: 100, currency: :USD}

add(m, addend)

Specs

add(t(), t() | integer() | float()) :: t()

Adds two SoftBank.Note together or an integer (cents) amount to a SoftBank.Note

Example:

iex> SoftBank.Note.add(SoftBank.Note.new(100, :USD), SoftBank.Note.new(50, :USD))
%SoftBank.Note{amount: 150, currency: :USD}
iex> SoftBank.Note.add(SoftBank.Note.new(100, :USD), 50)
%SoftBank.Note{amount: 150, currency: :USD}
iex> SoftBank.Note.add(SoftBank.Note.new(100, :USD), 5.55)
%SoftBank.Note{amount: 655, currency: :USD}

compare(a, b)

Specs

compare(t(), t()) :: t()

Compares two SoftBank.Note structs with each other. They must each be of the same currency and then their amounts are compared

Example:

iex> SoftBank.Note.compare(SoftBank.Note.new(100, :USD), SoftBank.Note.new(100, :USD))
0
iex> SoftBank.Note.compare(SoftBank.Note.new(100, :USD), SoftBank.Note.new(101, :USD))
-1
iex> SoftBank.Note.compare(SoftBank.Note.new(101, :USD), SoftBank.Note.new(100, :USD))
1

divide(note, denominator)

Specs

divide(t(), integer()) :: [t()]

Divides up SoftBank.Note by an amount

Example:

iex> SoftBank.Note.divide(SoftBank.Note.new(100, :USD), 2)
[%SoftBank.Note{amount: 50, currency: :USD}, %SoftBank.Note{amount: 50, currency: :USD}]
iex> SoftBank.Note.divide(SoftBank.Note.new(101, :USD), 2)
[%SoftBank.Note{amount: 51, currency: :USD}, %SoftBank.Note{amount: 50, currency: :USD}]

equals?(a, b)

Specs

equals?(t(), t()) :: boolean()

Returns true if two SoftBank.Note of the same currency have the same amount

Example:

iex> SoftBank.Note.equals?(SoftBank.Note.new(100, :USD), SoftBank.Note.new(100, :USD))
true
iex> SoftBank.Note.equals?(SoftBank.Note.new(101, :USD), SoftBank.Note.new(100, :USD))
false

multiply(note, multiplier)

Specs

multiply(t(), integer() | float()) :: t()

Multiplies a SoftBank.Note by an amount

Example:

iex> SoftBank.Note.multiply(SoftBank.Note.new(100, :USD), 10)
%SoftBank.Note{amount: 1000, currency: :USD}
iex> SoftBank.Note.multiply(SoftBank.Note.new(100, :USD), 1.5)
%SoftBank.Note{amount: 150, currency: :USD}

neg(note)

Specs

neg(t()) :: t()

Returns a SoftBank.Note with the amount negated.

Examples:

iex> SoftBank.Note.new(100, :USD) |> SoftBank.Note.neg
%SoftBank.Note{amount: -100, currency: :USD}
iex> SoftBank.Note.new(-100, :USD) |> SoftBank.Note.neg
%SoftBank.Note{amount: 100, currency: :USD}

negative?(note)

Specs

negative?(t()) :: boolean()

Returns true if the amount of a SoftBank.Note is less than zero

Example:

iex> SoftBank.Note.negative?(SoftBank.Note.new(0, :USD))
false
iex> SoftBank.Note.negative?(SoftBank.Note.new(1, :USD))
false
iex> SoftBank.Note.negative?(SoftBank.Note.new(-1, :USD))
true

new(amount)

Specs

new(integer()) :: t()

Create a new SoftBank.Note struct using a default currency. The default currency can be set in the system Mix config.

Example Config:

config :note,
  default_currency: :USD

Example:

SoftBank.Note.new(123)
%SoftBank.Note{amount: 123, currency: :USD}

new(int, currency)

Specs

new(integer(), atom() | String.t()) :: t()

Create a new SoftBank.Note struct from currency sub-units (cents)

Example:

iex> SoftBank.Note.new(1_000_00, :USD)
%SoftBank.Note{amount: 1_000_00, currency: :USD}

parse(value, currency \\ nil, opts \\ [])

Specs

parse(String.t() | float(), atom() | String.t(), Keyword.t()) :: {:ok, t()}

parse(String.t() | float(), atom() | String.t(), Keyword.t()) :: t()

Parse a value into a SoftBank.Note type.

The following options are available:

separator - default ",", sets the separator for groups of thousands. "1,000"
delimeter - default ".", sets the decimal delimeter. "1.23"

Examples:

iex> SoftBank.Note.parse("$1,234.56", :USD)
{:ok, %SoftBank.Note{amount: 123456, currency: :USD}}
iex> SoftBank.Note.parse("1.234,56", :EUR, separator: ".", delimeter: ",")
{:ok, %SoftBank.Note{amount: 123456, currency: :EUR}}
iex> SoftBank.Note.parse("1.234,56", :WRONG)
:error
iex> SoftBank.Note.parse(1_234.56, :USD)
{:ok, %SoftBank.Note{amount: 123456, currency: :USD}}
iex> SoftBank.Note.parse(-1_234.56, :USD)
{:ok, %SoftBank.Note{amount: -123456, currency: :USD}}

parse!(value, currency \\ nil, opts \\ [])

Parse a value into a SoftBank.Note type. Similar to parse/3 but returns a %SoftBank.Note{} or raises an error if parsing fails.

Example:

iex> SoftBank.Note.parse!("1,234.56", :USD)
%SoftBank.Note{amount: 123456, currency: :USD}
iex> SoftBank.Note.parse!("wrong", :USD)
** (ArgumentError) unable to parse "wrong"

positive?(note)

Specs

positive?(t()) :: boolean()

Returns true if the amount of a SoftBank.Note is greater than zero

Example:

iex> SoftBank.Note.positive?(SoftBank.Note.new(0, :USD))
false
iex> SoftBank.Note.positive?(SoftBank.Note.new(1, :USD))
true
iex> SoftBank.Note.positive?(SoftBank.Note.new(-1, :USD))
false

subtract(m, subtractend)

Specs

subtract(t(), t() | integer() | float()) :: t()

Subtracts one SoftBank.Note from another or an integer (cents) from a SoftBank.Note

Example:

iex> SoftBank.Note.subtract(SoftBank.Note.new(150, :USD), SoftBank.Note.new(50, :USD))
%SoftBank.Note{amount: 100, currency: :USD}
iex> SoftBank.Note.subtract(SoftBank.Note.new(150, :USD), 50)
%SoftBank.Note{amount: 100, currency: :USD}
iex> SoftBank.Note.subtract(SoftBank.Note.new(150, :USD), 1.25)
%SoftBank.Note{amount: 25, currency: :USD}

to_string(note, opts \\ [])

Specs

to_string(t(), Keyword.t()) :: String.t()

Converts a SoftBank.Note struct to a string representation

The following options are available:

separator - default ",", sets the separator for groups of thousands. "1,000"
delimeter - default ".", sets the decimal delimeter. "1.23"
symbol - default true, sets whether to display the currency symbol or not.
symbol_on_right - default false, display the currency symbol on the right of the number, eg: 123.45€
symbol_space - default false, add a space between currency symbol and number, eg: € 123,45 or 123.45 €
fractional_unit - default true, show the remaining units after the delimeter

Example:

iex> SoftBank.Note.to_string(SoftBank.Note.new(123456, :GBP))
"£1,234.56"
iex> SoftBank.Note.to_string(SoftBank.Note.new(123456, :EUR), separator: ".", delimeter: ",")
"€1.234,56"
iex> SoftBank.Note.to_string(SoftBank.Note.new(123456, :EUR), symbol: false)
"1,234.56"
iex> SoftBank.Note.to_string(SoftBank.Note.new(123456, :EUR), symbol: false, separator: "")
"1234.56"
iex> SoftBank.Note.to_string(SoftBank.Note.new(123456, :EUR), fractional_unit: false)
"€1,234"

It can also be interpolated (It implements the String.Chars protocol) To control the formatting, you can use the above options in your config, more information is in the introduction to SoftBank.Note

Example:

iex> "Total: #{SoftBank.Note.new(100_00, :USD)}"
"Total: $100.00"

zero?(note)

Specs

zero?(t()) :: boolean()

Returns true if the amount of a SoftBank.Note struct is zero

Example:

iex> SoftBank.Note.zero?(SoftBank.Note.new(0, :USD))
true
iex> SoftBank.Note.zero?(SoftBank.Note.new(1, :USD))
false