money 项目技术文档

本文档旨在帮助用户了解和掌握money项目的安装、使用以及API调用等细节。

1. 安装指南

在您的Ruby项目中，可以通过添加以下依赖到Gemfile文件来进行安装：

gem 'shopify-money'

然后执行以下命令来安装依赖：

bundle install

确保已经安装了 bundler。如果没有，可以使用以下命令安装：

gem install bundler

2. 项目使用说明

money项目提供了Money类来封装关于特定金额的所有信息，例如金额和货币单位。以下是基本的使用示例：

require 'money'

# 创建金额对象
money = Money.new(10.00, "USD")

# 获取子单位
money.subunits     #=> 1000

# 获取货币单位
money.currency     #=> Money::Currency.new("USD")

比较

Money.new(1000, "USD") == Money.new(1000, "USD")   #=> true
Money.new(1000, "USD") == Money.new(100, "USD")    #=> false
Money.new(1000, "USD") == Money.new(1000, "EUR")   #=> false

算术运算

Money.new(1000, "USD") + Money.new(500, "USD") == Money.new(1500, "USD")
Money.new(1000, "USD") - Money.new(200, "USD") == Money.new(800, "USD")
Money.new(1000, "USD") * 5                     == Money.new(5000, "USD")

分割金额

m = Money.new(1000, "USD")
m.split(2)              == [Money.new(500, "USD"), Money.new(500, "USD")]
m.split(3).map(&:value) == [333.34, 333.33, 333.33]

分配金额

m.allocate([0.50, 0.25, 0.25]).map(&:value)               == [500, 250, 250]
m.allocate([Rational(2, 3), Rational(1, 3)]).map(&:value) == [666.67, 333.33]

分配最大金额

m.allocate_max_amounts([500, 300, 200]).map(&:value) == [500, 300, 200]
m.allocate_max_amounts([500, 300, 300]).map(&:value) == [454.55, 272.73, 272.72]

四舍五入策略

m = Money::Allocator.new(Money.new(10.55, "USD"))
monies = m.allocate([0.25, 0.5, 0.25], :roundrobin)
# monies[0] == 2.64  <-- 获得1分
# monies[1] == 5.28  <-- 获得1分
# monies[2] == 2.63  <-- 未获得分

3. 项目API使用文档

money项目的API主要包括以下几个部分：

• Money.new(value, currency)：创建一个新的金额对象。
• Money.from_subunits(subunits, currency)：从子单位创建金额对象。
• Money.allocate(amounts)：按照给定比例分配金额。
• Money.allocate_max_amounts(amounts)：按照给定金额分配，超出部分按比例减少。
• Money::Allocator.new(money)：创建一个分配器，用于更复杂的金额分配。

更多API细节可以参考项目的GitHub仓库中的wiki页面。

4. 项目安装方式

项目的安装方式已在“安装指南”部分详细说明。简要概括如下：

• 将gem 'shopify-money'添加到项目的Gemfile文件中。
• 运行bundle install命令来安装依赖。