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

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

amount dart dart-console dart-package dart3 dartlang decimal flutter flutter-desktop flutter-mobile flutter-package flutter-web

Last synced: 11 months ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/marchdev-tk/mdamount
• Owner: marchdev-tk
• License: bsd-3-clause
• Created: 2024-10-24T16:51:58.000Z (over 1 year ago)
• Default Branch: master
• Last Pushed: 2025-03-11T14:37:08.000Z (12 months ago)
• Last Synced: 2025-03-11T15:45:45.946Z (12 months ago)
• Topics: amount, dart, dart-console, dart-package, dart3, dartlang, decimal, flutter, flutter-desktop, flutter-mobile, flutter-package, flutter-web
• Language: Dart
• Homepage:
• Size: 56.6 KB
• Stars: 0
• 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

          
# mdamount

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

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

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

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

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

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

## Getting Started

### Construction

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

  * `Amount` with following args:

    * `BigInt` numerator

    * custom `precision`, if not provided or if negative precision was set - `Amount.defaultPrecision` will be used instead

  * `Amount.fromNumerator` with following args:

    * `int` numerator

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

  * `Amount.fromBigInt` with following args:

    * `BigInt` amount

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

  * `Amount.fromInt` with following args:

    * `int` amount

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

  * `Amount.fromDecimal` with following args:

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

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

  * `Amount.fromDouble` with following args:

    * `double` amount

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

  * `Amount.fromString` with following args:

    * `String`

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

Also there are some convenient ways to create an object:

  * `Amount.zeroOf` to create the amount with `0` as numerator with custom `precision`

  * `Amount.oneOf` to create the amount with `1` as numerator with custom `precision`

  * `Amount.oneIntOf` to create the amount with `1` as integer with custom `precision`

  * `Amount.zero` to create the amount with `0` as numerator with default precision (`Amount.defaultPrecision`)

  * `Amount.one` to create the amount with `1` as numerator with default precision (`Amount.defaultPrecision`)

  * `Amount.oneInt` to create the amount with `1` as integer with default precision (`Amount.defaultPrecision`)

### Manipulation

First of all, `Amount` 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`

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

  * `toDouble` - returns theamount 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)

  * `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`)

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

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

    * `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`

### Changing or accessing default precision

To access default precision use following static getter:

  * `Amount.defaultPrecision`

And for changing default precision use following static method:

  * `Amount.setDefaultPrecision()`

But be cautious, precision cannot be less than zero.

### 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/mdamount/issues).