flamingo.me/flamingo-commerce/v3@v3.11.0/price/Readme.md (about)

     1  # Price Module
     2  
     3  The price module defines value objects to deal with prices and charges.
     4  The following types exist:
     5  * Price: Represents simply a money value. See below for more details. For example: 5€
     6  * Charge: Represents a Price together with its Type. This is used to describe that something need to be paid in a certain currency and represents a certain value. For example it might be you need (or want) to pay the value of 5€ in 500 Loyaltypoints. This can be described in the Charge Type.
     7  * Charges: Is a list of the type Charge. For example to indicate that you are paying to value of 5€ with two Charges: 2€ and 300 Loyaltypoints
     8  
     9  ## Price Type:
    10  The price module offers a Price Type with useful methods.
    11  
    12  Price calculation is not a trivial topic and multiple solutions exist. 
    13  The implementation details of the price object is:
    14  
    15  * internally we use big.Float to hold the amount, this is to be able to calculate exactly
    16  * however, a float like representation of an amount cannot be paid, that is why the price has a method "GetPayablePrice" that returns a Price that can be paid in the given currency, using correct rounding and amount representation
    17  
    18  
    19  ### Example:
    20  
    21  ```go
    22  // get 2.45 EUR Price
    23  price := NewFromInt(245,100,"EUR")
    24  
    25  rowPrice := price.Multiply(10)
    26  
    27  // 10% discount
    28  discountedRowPrice := rowPrice.Discounted(10.0)
    29  
    30  // What needs to be paid:
    31  priceToPay := discountedRowPrice.GetPayable()
    32  
    33  // what needs to be paid by item()
    34  singleItemsPrices := discountedRowPrice.SplitInPayables(10)
    35  
    36  // you can also set price from float:
    37  price2 := NewFromFloat(2.45,"EUR")
    38  ```
    39  
    40  Be aware that `price.Equals(price2)` may be false but due to float arithmetic but
    41  `price.GetPayable().Equals(price2.GetPayable())` will be true
    42  
    43  #### Rounding Modes
    44  
    45  We support a variety of rounding modes. These can be used with the `GetPayableByRoundingMode` function by specifying a mode and precision. The following modes are available:
    46  
    47  * `RoundingModeFloor`
    48    
    49    Rounding mode to round towards negative infinity.
    50    _Note that this rounding mode never increases the calculated value._
    51  
    52    | `price` | `price.GetPayableByRoundingMode(RoundingModeFloor, 1)` |
    53    |---------|--------------------------------------------------------|
    54    |     5.5 |                                                      5 |
    55    |     2.5 |                                                      2 |
    56    |     1.6 |                                                      1 |
    57    |     1.1 |                                                      1 |
    58    |     1.0 |                                                      1 |
    59    |    -1.0 |                                                     -1 |
    60    |    -1.1 |                                                     -2 |
    61    |    -1.6 |                                                     -2 |
    62    |    -2.5 |                                                     -3 |
    63    |    -5.5 |                                                     -6 |
    64  * `RoundingModeCeil`
    65    
    66    Rounding mode to round towards positive infinity.
    67    _Note that this rounding mode never decreases the calculated value._
    68  
    69    | `price` | `price.GetPayableByRoundingMode(RoundingModeCeil, 1)` |
    70    |---------|-------------------------------------------------------|
    71    |     5.5 |                                                     6 |
    72    |     2.5 |                                                     3 |
    73    |     1.6 |                                                     2 |
    74    |     1.1 |                                                     2 |
    75    |     1.0 |                                                     1 |
    76    |    -1.0 |                                                    -1 |
    77    |    -1.1 |                                                    -1 |
    78    |    -1.6 |                                                    -1 |
    79    |    -2.5 |                                                    -2 |
    80    |    -5.5 |                                                    -5 |
    81  * `RoundingModeHalfUp` default mode for `GetPayable()`
    82    
    83    Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
    84    _Note that this is the rounding mode commonly taught at school._
    85  
    86    | `price` | `price.GetPayableByRoundingMode(RoundingModeHalfUp, 1)` |
    87    |---------|---------------------------------------------------------|
    88    |     5.5 |                                                       6 |
    89    |     2.5 |                                                       3 |
    90    |     1.6 |                                                       2 |
    91    |     1.1 |                                                       1 |
    92    |     1.0 |                                                       1 |
    93    |    -1.0 |                                                      -1 |
    94    |    -1.1 |                                                      -1 |
    95    |    -1.6 |                                                      -2 |
    96    |    -2.5 |                                                      -3 |
    97    |    -5.5 |                                                      -6 |
    98    
    99  * `RoundingModeHalfDown`
   100    
   101    Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
   102  
   103    | `price` | `price.GetPayableByRoundingMode(RoundingModeHalfDown, 1)` |
   104    |---------|-----------------------------------------------------------|
   105    |     5.5 |                                                         5 |
   106    |     2.5 |                                                         2 |
   107    |     1.6 |                                                         2 |
   108    |     1.1 |                                                         1 |
   109    |     1.0 |                                                         1 |
   110    |    -1.0 |                                                        -1 |
   111    |    -1.1 |                                                        -1 |
   112    |    -1.6 |                                                        -2 |
   113    |    -2.5 |                                                        -2 |
   114    |    -5.5 |                                                        -5 |
   115  
   116  
   117  ## Charge:
   118  Represents a price together with a type. A charge has a values price (normally in default currency) and a the price that is paid that might be in a different currency.
   119  Can be used in places where you need to give the price value a certain extra semantic information or to represent something that need to be paid (charged).
   120  
   121  ## Template Func - Formatting a Price Object
   122  
   123  Just use the template function commercePriceFormat like this: `commercePriceFormat(priceObject)` 
   124  The template functions used the configurations of the Flamingo "locale" package. For more details on the configuration options please read there.