README.md in measured-1.6.0 vs README.md in measured-2.0.0.pre1
- old
+ new
@@ -1,10 +1,10 @@
# Measured [](https://travis-ci.org/Shopify/measured) [](http://badge.fury.io/rb/measured)
Encapsulates measurements with their units. Provides easy conversion between units.
-Light weight and easily extensible to include other units and conversions. Conversions done with `BigDecimal` for precision.
+Lightweight and easily extensible to include other units and conversions. Conversions done with `Rational` for precision.
The adapter to integrate `measured` with Ruby on Rails is in a separate [`measured-rails`](https://github.com/Shopify/measured-rails) gem.
## Installation
@@ -14,11 +14,13 @@
gem 'measured'
```
Or stand alone:
- $ gem install measured
+```
+$ gem install measured
+```
## Usage
Initialize a measurement:
@@ -30,16 +32,10 @@
```ruby
Measured::Weight.new("12", "g").convert_to("kg")
```
-Or convert inline:
-
-```ruby
-Measured::Weight.new("12", "g").convert_to!("kg")
-```
-
Agnostic to symbols/strings:
```ruby
Measured::Weight.new(1, "kg") == Measured::Weight.new(1, :kg)
```
@@ -48,59 +44,45 @@
```ruby
Measured::Weight.new(12, :oz) == Measured::Weight.new("12", :ounce)
```
-Comparison with zero works without the need to specify units, useful for validations:
-```ruby
-Measured::Weight.new(0.001, :kg) > 0
-> true
-
-Measured::Length.new(-1, :m) < 0
-> true
-
-Measured::Weight.new(0, :oz) == 0
-> true
-```
-
Raises on unknown units:
```ruby
begin
Measured::Weight.new(1, :stone)
rescue Measured::UnitError
puts "Unknown unit"
end
```
-Perform mathematical operations against other units, all represented internally as `BigDecimal`:
+Perform addition / subtraction against other units, all represented internally as `Rational` or `BigDecimal`:
```ruby
Measured::Weight.new(1, :g) + Measured::Weight.new(2, :g)
> #<Measured::Weight 3 g>
-Measured::Weight.new(2, :g) - Measured::Weight.new(1, :g)
-> #<Measured::Weight 1 g>
-Measured::Weight.new(10, :g) / Measured::Weight.new(2, :g)
+Measured::Weight.new("2.1", :g) - Measured::Weight.new(1, :g)
+> #<Measured::Weight 1.1 g>
+```
+
+Multiplication and division by units is not supported, but the actual value can be scaled by a scalar:
+
+```ruby
+Measured::Weight.new(10, :g).scale(0.5)
> #<Measured::Weight 5 g>
-Measured::Weight.new(2, :g) * Measured::Weight.new(3, :g)
+Measured::Weight.new(2, :g).scale(3)
> #<Measured::Weight 6 g>
```
In cases of differing units, the left hand side takes precedence:
```ruby
Measured::Weight.new(1000, :g) + Measured::Weight.new(1, :kg)
> #<Measured::Weight 2000 g>
```
-Also perform mathematical operations against `Numeric` things:
-
-```ruby
-Measured::Weight.new(3, :g) * 2
-> #<Measured::Weight 6 g>
-```
-
Converts units only as needed for equality comparison:
```ruby
> Measured::Weight.new(1000, :g) == Measured::Weight.new(1, :kg)
true
@@ -172,50 +154,35 @@
Measured::Weight(1, :g)
```
### Adding new units
-Extending this library to support other units is simple. To add a new conversion, subclass `Measured::Measurable`, define your base units, then add your conversion units.
+Extending this library to support other units is simple. To add a new conversion, use `Measured.build` to define your base unit and conversion units:
```ruby
-class Measured::Thing < Measured::Measurable
- conversion.set_base :base_unit, # Define the basic unit for the system
- aliases: [:bu] # Allow it to be aliased to other names/symbols
+Measured::Thing = Measured.build do
+ unit :base_unit, # Add a unit to the system
+ aliases: [:bu] # Allow it to be aliased to other names/symbols
- conversion.add :another_unit, # Add a second unit to the system
- aliases: [:au], # All units allow aliases, as long as they are unique
- value: ["1.5 base_unit"] # The conversion rate to another unit
-
- conversion.add :different_unit
- aliases: [:du],
- value: [Rational(2,3), "another_unit"] # Conversion rate can be Rational, otherwise it is coerced to BigDecimal
+ unit :another_unit, # Add a second unit to the system
+ aliases: [:au], # All units allow aliases, as long as they are unique
+ value: ["1.5 bu"] # The conversion rate to another unit
end
```
-By default all names and aliases and case insensitive. If you would like to create a new unit with names and aliases that are case sensitive, you should subclass `Measured::CaseSensitiveMeasurable` instead. Other than case sensitivity, both classes are identical to each other.
+By default all names and aliases are case insensitive. If you would like to create a new unit with names and aliases that are case sensitive, specify the case sensitive flag when building your unit:
```ruby
-class Measured::Thing < Measured::CaseSensitiveMeasurable
- conversion.set_base :base_unit,
- aliases: [:bu]
+Measured::Thing = Measured.build(case_sensitive: true) do
+ unit :base_unit, aliases: [:bu]
end
```
-The base unit takes no value. Values for conversion units can be defined as a string with two tokens `"number unit"` or as an array with two elements. The numbers must be `Rational` or `BigDecimal`, else they will be coerced to `BigDecimal`. Conversion paths don't have to be direct as a conversion table will be built for all possible conversions using tree traversal.
+Other than case sensitivity, both classes are identical to each other. The `case_sensitive` flag, which is false by default, gets taken into account any time you attempt to reference a unit by name or alias.
-The `case_sensitive` flag, which is false by default, gets taken into account any time you attempt to reference a unit by name or alias.
+Values for conversion units can be defined as a string with two tokens `"number unit"` or as an array with two elements. All values will be parsed as / coerced to `Rational`. Conversion paths don't have to be direct as a conversion table will be built for all possible conversions.
-You can also open up the existing classes and add a new conversion:
-
-```ruby
-class Measured::Length
- conversion.add :dm,
- aliases: [:decimeter, :decimetre, :decimeters, :decimetres],
- value: "0.1 m"
-end
-```
-
### Namespaces
All units and classes are namespaced by default, but can be aliased in your application.
```ruby
@@ -236,10 +203,10 @@
* Lots of code to solve a relatively simple problem.
* No ActiveRecord adapter.
### Gem: [quantified](https://github.com/Shopify/quantified)
* **Pros**
- * Light weight.
+ * Lightweight.
* Included with ActiveShipping/ActiveUtils.
* **Cons**
* All math done with floats making it highly lossy.
* All units assumed to be pluralized, meaning using unit abbreviations is not possible.
* Not actively maintained.