module Money::Formatting

Direct including types

Defined in:

money/money/formatting.cr

Instance Method Summary

Instance Method Detail

def format(options : NamedTuple) : String #

Creates a formatted price string according to several rules.

display_free (Bool | String) — default: false

Whether a zero amount of money should be formatted as the supplied string.

Money.us_dollar(0).format(display_free: "gratis") # => "gratis"
Money.us_dollar(0).format                         # => "$0.00"

sign_positive (Bool) — default: false

Whether positive numbers should be signed, too.

# You can specify to display the sign with positive numbers
Money.new(100, "GBP").format(sign_positive: true) # => "+£1.00"
Money.new(100, "GBP").format                      # => "£1.00"

with_currency (Bool) — default: false

Whether the currency name should be appended to the result string.

Money.us_dollar(100).format                      # => "$1.00"
Money.us_dollar(100).format(with_currency: true) # => "$1.00 USD"
Money.us_dollar(85).format(with_currency: true)  # => "$0.85 USD"

no_cents (Bool) — default: false

Whether cents should be omitted.

Money.us_dollar(100).format(no_cents: true) # => "$1"
Money.us_dollar(599).format(no_cents: true) # => "$5"

no_cents_if_whole (Bool) — default: false

Whether cents should be omitted if the cent value is zero.

Money.us_dollar(10000).format(no_cents_if_whole: true) # => "$100"
Money.us_dollar(10034).format(no_cents_if_whole: true) # => "$100.34"

drop_trailing_zeros (Bool) — default: false

Money.new(89000, :btc).format(drop_trailing_zeros: true) # => ฿0.00089
Money.new(110, :usd).format(drop_trailing_zeros: true)   # => $1.1

symbol_first (Bool) — default: false

Whether a money symbol should go before the amount.

Money.new(10000, "USD").format(symbol_first: true)  # => "$100.00"
Money.new(10000, "USD").format(symbol_first: false) # => "100.00 $"

symbol (Bool | String) — default: true

Whether a money symbol should be prepended to the result string. This method attempts to pick a symbol that's suitable for the given currency.

Money.new(100, "USD") # => "$1.00"
Money.new(100, "GBP") # => "£1.00"
Money.new(100, "EUR") # => "€1.00"

# Same thing.
Money.new(100, "USD").format(symbol: true) # => "$1.00"
Money.new(100, "GBP").format(symbol: true) # => "£1.00"
Money.new(100, "EUR").format(symbol: true) # => "€1.00"

# You can pass `false` or an empty string to disable
# prepending a money symbol.
Money.new(100, "USD").format(symbol: false) # => "1.00"
Money.new(100, "GBP").format(symbol: nil)   # => "1.00"
Money.new(100, "EUR").format(symbol: "")    # => "1.00"

# If the symbol for the given currency isn't known, then it will default
# to "¤" as symbol.
Money.new(100, "XBC").format(symbol: true) # => "1.00 ¤"

# You can specify a string as value to enforce using a particular symbol.
Money.new(100, "XBC").format(symbol: "ƒ") # => "1.00 ƒ"

disambiguate (Bool) — default: false

Prevents the result from being ambiguous due to equal symbols for different currencies. Uses the disambiguate_symbol.

Money.new(100, "USD").format(disambiguate: false) # => "$100.00"
Money.new(100, "CAD").format(disambiguate: false) # => "$100.00"
Money.new(100, "USD").format(disambiguate: true)  # => "US$100.00"
Money.new(100, "CAD").format(disambiguate: true)  # => "C$100.00"

symbol_before_without_space (Bool) — default: true

Whether a space between the money symbol and the amount should be inserted when :symbol_first is true. The default is true (meaning no space). Ignored if :symbol is false or :symbol_first is false.

# Default is to not insert a space.
Money.new(100, "USD").format # => "$1.00"

# Same thing.
Money.new(100, "USD").format(symbol_before_without_space: true) # => "$1.00"

# If set to false, will insert a space.
Money.new(100, "USD").format(symbol_before_without_space: false) # => "$ 1.00"

symbol_after_without_space (Bool) — default: false

Whether a space between the amount and the money symbol should be inserted when :symbol_first is false. The default is false (meaning space). Ignored if :symbol is false or :symbol_first is true.

# Default is to insert a space.
Money.new(100, "USD").format(symbol_first: false) # => "1.00 $"

# If set to true, will not insert a space.
Money.new(100, "USD").format(symbol_first: false, symbol_after_without_space: true) # => "1.00$"

separator (Bool | String) — default: true

Whether the currency should be separated by the specified character or ".".

# If a string is specified, it's value is used.
Money.new(100, "USD").format(separator: ",") # => "$1,00"

# If the separator for a given currency isn't known, then it will default
# to "." as separator.
Money.new(100, "FOO").format # => "$1.00"

delimiter (Bool | String) — default: true

Whether the currency should be delimited by the specified character or ",".

# If falsy value is specified, no delimiter is used.
Money.new(100000, "USD").format(delimiter: false) # => "1000.00"
Money.new(100000, "USD").format(delimiter: nil)   # => "1000.00"
Money.new(100000, "USD").format(delimiter: "")    # => "1000.00"

# If a string is specified, it's value is used.
Money.new(100000, "USD").format(delimiter: ".") # => "$1.000.00"

# If the delimiter for a given currency isn't known, then it will
# default to "," as delimiter.
Money.new(100000, "FOO").format # => "$1,000.00"

html (Bool) — default: false

Whether the currency should be HTML-formatted.

Money.new(1999, "RUB").format(html: true, no_cents: true) # => "19 ₽"

[View source]
def format(**options) : String #

Creates a formatted price string according to several rules.

display_free (Bool | String) — default: false

Whether a zero amount of money should be formatted as the supplied string.

Money.us_dollar(0).format(display_free: "gratis") # => "gratis"
Money.us_dollar(0).format                         # => "$0.00"

sign_positive (Bool) — default: false

Whether positive numbers should be signed, too.

# You can specify to display the sign with positive numbers
Money.new(100, "GBP").format(sign_positive: true) # => "+£1.00"
Money.new(100, "GBP").format                      # => "£1.00"

with_currency (Bool) — default: false

Whether the currency name should be appended to the result string.

Money.us_dollar(100).format                      # => "$1.00"
Money.us_dollar(100).format(with_currency: true) # => "$1.00 USD"
Money.us_dollar(85).format(with_currency: true)  # => "$0.85 USD"

no_cents (Bool) — default: false

Whether cents should be omitted.

Money.us_dollar(100).format(no_cents: true) # => "$1"
Money.us_dollar(599).format(no_cents: true) # => "$5"

no_cents_if_whole (Bool) — default: false

Whether cents should be omitted if the cent value is zero.

Money.us_dollar(10000).format(no_cents_if_whole: true) # => "$100"
Money.us_dollar(10034).format(no_cents_if_whole: true) # => "$100.34"

drop_trailing_zeros (Bool) — default: false

Money.new(89000, :btc).format(drop_trailing_zeros: true) # => ฿0.00089
Money.new(110, :usd).format(drop_trailing_zeros: true)   # => $1.1

symbol_first (Bool) — default: false

Whether a money symbol should go before the amount.

Money.new(10000, "USD").format(symbol_first: true)  # => "$100.00"
Money.new(10000, "USD").format(symbol_first: false) # => "100.00 $"

symbol (Bool | String) — default: true

Whether a money symbol should be prepended to the result string. This method attempts to pick a symbol that's suitable for the given currency.

Money.new(100, "USD") # => "$1.00"
Money.new(100, "GBP") # => "£1.00"
Money.new(100, "EUR") # => "€1.00"

# Same thing.
Money.new(100, "USD").format(symbol: true) # => "$1.00"
Money.new(100, "GBP").format(symbol: true) # => "£1.00"
Money.new(100, "EUR").format(symbol: true) # => "€1.00"

# You can pass `false` or an empty string to disable
# prepending a money symbol.
Money.new(100, "USD").format(symbol: false) # => "1.00"
Money.new(100, "GBP").format(symbol: nil)   # => "1.00"
Money.new(100, "EUR").format(symbol: "")    # => "1.00"

# If the symbol for the given currency isn't known, then it will default
# to "¤" as symbol.
Money.new(100, "XBC").format(symbol: true) # => "1.00 ¤"

# You can specify a string as value to enforce using a particular symbol.
Money.new(100, "XBC").format(symbol: "ƒ") # => "1.00 ƒ"

disambiguate (Bool) — default: false

Prevents the result from being ambiguous due to equal symbols for different currencies. Uses the disambiguate_symbol.

Money.new(100, "USD").format(disambiguate: false) # => "$100.00"
Money.new(100, "CAD").format(disambiguate: false) # => "$100.00"
Money.new(100, "USD").format(disambiguate: true)  # => "US$100.00"
Money.new(100, "CAD").format(disambiguate: true)  # => "C$100.00"

symbol_before_without_space (Bool) — default: true

Whether a space between the money symbol and the amount should be inserted when :symbol_first is true. The default is true (meaning no space). Ignored if :symbol is false or :symbol_first is false.

# Default is to not insert a space.
Money.new(100, "USD").format # => "$1.00"

# Same thing.
Money.new(100, "USD").format(symbol_before_without_space: true) # => "$1.00"

# If set to false, will insert a space.
Money.new(100, "USD").format(symbol_before_without_space: false) # => "$ 1.00"

symbol_after_without_space (Bool) — default: false

Whether a space between the amount and the money symbol should be inserted when :symbol_first is false. The default is false (meaning space). Ignored if :symbol is false or :symbol_first is true.

# Default is to insert a space.
Money.new(100, "USD").format(symbol_first: false) # => "1.00 $"

# If set to true, will not insert a space.
Money.new(100, "USD").format(symbol_first: false, symbol_after_without_space: true) # => "1.00$"

separator (Bool | String) — default: true

Whether the currency should be separated by the specified character or ".".

# If a string is specified, it's value is used.
Money.new(100, "USD").format(separator: ",") # => "$1,00"

# If the separator for a given currency isn't known, then it will default
# to "." as separator.
Money.new(100, "FOO").format # => "$1.00"

delimiter (Bool | String) — default: true

Whether the currency should be delimited by the specified character or ",".

# If falsy value is specified, no delimiter is used.
Money.new(100000, "USD").format(delimiter: false) # => "1000.00"
Money.new(100000, "USD").format(delimiter: nil)   # => "1000.00"
Money.new(100000, "USD").format(delimiter: "")    # => "1000.00"

# If a string is specified, it's value is used.
Money.new(100000, "USD").format(delimiter: ".") # => "$1.000.00"

# If the delimiter for a given currency isn't known, then it will
# default to "," as delimiter.
Money.new(100000, "FOO").format # => "$1,000.00"

html (Bool) — default: false

Whether the currency should be HTML-formatted.

Money.new(1999, "RUB").format(html: true, no_cents: true) # => "19 ₽"

[View source]
def to_s(io : IO) : Nil #

See #format.


[View source]