https://github.com/marchdev-tk/mdmoney

march.dev money library. Provides a new way to work with a money. From highly flexible creation to rich data manipulation and stringification options.
https://github.com/marchdev-tk/mdmoney

android dart dart-package dart3 dartlang flutter flutter-desktop flutter-mobile flutter-package flutter-plugin flutter-web ios linux macos money package plugin web windows

Last synced: 11 months ago
JSON representation

march.dev money library. Provides a new way to work with a money. From highly flexible creation to rich data manipulation and stringification options.

• Host: GitHub
• URL: https://github.com/marchdev-tk/mdmoney
• Owner: marchdev-tk
• License: bsd-3-clause
• Created: 2023-05-13T19:58:37.000Z (almost 3 years ago)
• Default Branch: master
• Last Pushed: 2025-03-11T14:47:42.000Z (12 months ago)
• Last Synced: 2025-03-11T15:48:13.159Z (12 months ago)
• Topics: android, dart, dart-package, dart3, dartlang, flutter, flutter-desktop, flutter-mobile, flutter-package, flutter-plugin, flutter-web, ios, linux, macos, money, package, plugin, web, windows
• Language: Dart
• Homepage:
• Size: 125 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Authors: AUTHORS

Awesome Lists containing this project

README

          
# mdmoney

![Build](https://github.com/marchdev-tk/mdmoney/workflows/build/badge.svg)

[![codecov](https://codecov.io/gh/marchdev-tk/mdmoney/branch/master/graph/badge.svg)](https://codecov.io/gh/marchdev-tk/mdmoney)

[![Pub](https://img.shields.io/pub/v/mdmoney.svg)](https://pub.dartlang.org/packages/mdmoney)

![GitHub](https://img.shields.io/github/license/marchdev-tk/mdmoney)

![GitHub stars](https://img.shields.io/github/stars/marchdev-tk/mdmoney?style=social)

march.dev money library. Provides a new way to work with a money. From highly flexible creation to rich data manipulation and stringification options.

## Getting Started

To begin your work with a money object you need to create it, there are several ways to do it:

  * `Money.fromCents` with following args:

    * `cents`

    * `currency`

    * custom `precision`, if not provided - `currency.precision` will be used instead

  * `Money.fromBigInt` with following args:

    * `BigInt` amount

    * `currency`

    * custom `precision`, if not provided - `currency.precision` will be used instead

  * `Money.fromInt` with following args:

    * `int` amount

    * `currency`

    * custom `precision`, if not provided - `currency.precision` will be used instead

  * `Money.fromDecimal` with following args:

    * `Decimal` amount (from `decimal` package)

    * `currency`

    * custom `precision`, if not provided - `currency.precision` will be used instead

  * `Money.fromDouble` with following args:

    * `double` amount

    * `currency`

    * custom `precision`, if not provided - `currency.precision` will be used instead

  * `Money.fromString` with following args:

    * `String`

    * `currency`, if not specified in a `String`

    * custom `precision`, if not provided - `currency.precision` will be used instead

  * `Money.fromAmount` with following args:

    * `Amount` amount

    * `currency`

    * custom `precision`, if not provided - `amount.precision` will be used instead

    * `preferCurrencyPrecision`, if set to `true` field `precision` is omitted, otherwise either `precision` or `amount.precision` will be used.

Also there are some convenient ways to create an object:

  * `Money.zeroOf` to create the amount with `0` as numerator with following args:

    * `currency`

    * custom `precision`, if not provided - `currency.precision` will be used instead

  * `Money.oneOf` to create the amount with `1` as numerator with following args:

    * `currency`

    * custom `precision`, if not provided - `currency.precision` will be used instead

  * `Money.oneIntOf` to create the amount with `1` as integer with following args:

    * `currency`

    * custom `precision`, if not provided - `currency.precision` will be used instead

  * `Money.zero` to create the amount with `0` as numerator in default currency (`FiatCurrency.$default`)

  * `Money.one` to create the amount with `1` as numerator in default currency (`FiatCurrency.$default`)

  * `Money.oneInt` to create the amount with `1` as integer in default currency (`FiatCurrency.$default`)

First of all, `Money` object is `comparable` and has all required operators:

  * unary `operator -`

  * binary `operator -`

  * `operator +`

  * `operator *`

  * `operator /`

  * `operator <`

  * `operator <=`

  * `operator >`

  * `operator >=`

  * `operator ==`

Regarding what you can do with this object, let's break down following methods/getters/fields:

  

  * `cents` - returns the `BigInt` `cents` representation of the amount 

  * `currency` - returns the `currency` of the amount

  * `precision` - returns the `precision` of the amount (quantity of digits in fractional part)

  * `sign` - returns the `sign` of the amount

  * `isEven` - whether the amount is `even` or not

  * `isOdd` - whether the amount is `odd` or not

  * `isNegative` - whether the amount is `negative` or not

  * `isPositive` - whether the amount is `positive` or not

  * `isZero` - whether the amount is equals to `zero` or not

  * `isGreaterThanZero` - whether the amount is greater than `zero` or not

  * `isGreaterThanOrEqualZero` - whether the amount is greater than or equals to `zero` or not

  * `isLessThanZero` - whether the amount is less than `zero` or not

  * `isLessThanOrEqualZero` - whether the amount is less than or equals to `zero` or not

  * `integer` - returns the `integer` part of the amount

  * `fractional` - returns the `fractional` part of the amount in `BigInt` cents

  * `fractionalDecimal` - returns the `fractional` part of the amount in `Decimal`

  * `fractionalDouble` - returns the `fractional` part of the amount in `double`

  * `abs` - returns the `absolute` (always positive) amount

  * `round` - returns the `rounded` amount

  * `ceil` - returns the `ceiled` amount (rounded to the next integer)

  * `floor` - returns the `floored` amount (truncating fractional part of the amount)

  * `toDecimal` - returns the amount in `Decimal`

  * `toDouble` - returns the amount in `double`

  * `toAmount` - returns the amount in `Amount`

  * `toString` - return the `String` representation of the amount with lots of customisation options, they are:

    * `DecimalSeparatorFormat` - specifies which decimal separator to use:

      * `point`

      * `comma` 

    * `RankFormat` - specifies rank formatting:

      * `none` (`XXXX`)

      * `space` (`X XXX`)

    * `AmountFormat` - specifies amount display formatting:

      * `integer` - only integer part (`XXXX`)

      * `flexibleDouble` - fractional parts will not display trailing zeros (`XXXX`/`XXXX.X`/`XXXX.XX`)

      * `fixedDouble` - fractional parts will display full precision, even zeros (`XXXX.XX`)

    * `FiatCurrencyFormat` - specifies how currency should be displayed:

      * `none`

      * `code` (`USD`/`EUR`/`UAH`/etc.)

      * `icon` (`$`/`€`/`₴`/etc.)

    * `CurrencyPosition` - specifies where currency should be:

      * `start`

      * `startSpaced`

      * `end`

      * `endSpaced`

      * `decimalSeparator`

    * `precision` - if set, this method will behave differently based on `AmountFormat`:

      * `integer` - `precision` is omitted

      * `fixedDouble` - `precision` will be used as an override to `Amount.precision`

      * `flexibleDouble` - `precision` will be used only if length of fractionals will be less than `precision`

### Known limitations

  * Max precision is `15`, everything that is beyond this precision will be trimmed due to Decimal's internal inability to work with such precisions.

## Examples

To see usage example navigate to the [Example](example/README.md) section.

## Feature requests and Bug reports

Feel free to post a feature requests or report a bug [here](https://github.com/marchdev-tk/mdmoney/issues).