ruby-units 2.3.1 → 2.3.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/.codeclimate.yml +32 -0
- data/.csslintrc +2 -0
- data/.eslintignore +1 -0
- data/.eslintrc +213 -0
- data/.github/workflows/tests.yml +40 -0
- data/.gitignore +11 -0
- data/.rspec +2 -0
- data/.rubocop.yml +24 -0
- data/.ruby-version +1 -0
- data/.solargraph.yml +16 -0
- data/CHANGELOG.txt +4 -0
- data/CODE_OF_CONDUCT.md +74 -0
- data/Gemfile +9 -0
- data/Gemfile.lock +164 -0
- data/Guardfile +31 -0
- data/LICENSE.txt +18 -17
- data/README.md +124 -96
- data/Rakefile +3 -24
- data/lib/ruby_units/unit.rb +0 -1
- data/lib/ruby_units/version.rb +1 -4
- data/ruby-units.gemspec +35 -78
- metadata +95 -26
- data/VERSION +0 -1
data/Gemfile
ADDED
data/Gemfile.lock
ADDED
@@ -0,0 +1,164 @@
|
|
1
|
+
PATH
|
2
|
+
remote: .
|
3
|
+
specs:
|
4
|
+
ruby-units (2.3.2)
|
5
|
+
|
6
|
+
GEM
|
7
|
+
remote: https://rubygems.org/
|
8
|
+
specs:
|
9
|
+
ast (2.4.1)
|
10
|
+
backport (1.1.2)
|
11
|
+
benchmark (0.1.1)
|
12
|
+
byebug (11.1.3)
|
13
|
+
coderay (1.1.3)
|
14
|
+
diff-lcs (1.4.4)
|
15
|
+
docile (1.3.4)
|
16
|
+
e2mmap (0.1.0)
|
17
|
+
ffi (1.14.2)
|
18
|
+
ffi (1.14.2-java)
|
19
|
+
formatador (0.2.5)
|
20
|
+
guard (2.16.2)
|
21
|
+
formatador (>= 0.2.4)
|
22
|
+
listen (>= 2.7, < 4.0)
|
23
|
+
lumberjack (>= 1.0.12, < 2.0)
|
24
|
+
nenv (~> 0.1)
|
25
|
+
notiffany (~> 0.0)
|
26
|
+
pry (>= 0.9.12)
|
27
|
+
shellany (~> 0.0)
|
28
|
+
thor (>= 0.18.1)
|
29
|
+
guard-compat (1.2.1)
|
30
|
+
guard-rspec (4.7.3)
|
31
|
+
guard (~> 2.1)
|
32
|
+
guard-compat (~> 1.1)
|
33
|
+
rspec (>= 2.99.0, < 4.0)
|
34
|
+
jaro_winkler (1.5.4)
|
35
|
+
jaro_winkler (1.5.4-java)
|
36
|
+
kramdown (2.3.0)
|
37
|
+
rexml
|
38
|
+
kramdown-parser-gfm (1.1.0)
|
39
|
+
kramdown (~> 2.0)
|
40
|
+
listen (3.3.3)
|
41
|
+
rb-fsevent (~> 0.10, >= 0.10.3)
|
42
|
+
rb-inotify (~> 0.9, >= 0.9.10)
|
43
|
+
lumberjack (1.2.8)
|
44
|
+
method_source (1.0.0)
|
45
|
+
mini_portile2 (2.4.0)
|
46
|
+
nenv (0.3.0)
|
47
|
+
nokogiri (1.10.10)
|
48
|
+
mini_portile2 (~> 2.4.0)
|
49
|
+
nokogiri (1.10.10-java)
|
50
|
+
notiffany (0.1.3)
|
51
|
+
nenv (~> 0.1)
|
52
|
+
shellany (~> 0.0)
|
53
|
+
parallel (1.20.1)
|
54
|
+
parser (2.7.2.0)
|
55
|
+
ast (~> 2.4.1)
|
56
|
+
pry (0.13.1)
|
57
|
+
coderay (~> 1.1)
|
58
|
+
method_source (~> 1.0)
|
59
|
+
pry (0.13.1-java)
|
60
|
+
coderay (~> 1.1)
|
61
|
+
method_source (~> 1.0)
|
62
|
+
spoon (~> 0.0)
|
63
|
+
pry-byebug (3.9.0)
|
64
|
+
byebug (~> 11.0)
|
65
|
+
pry (~> 0.13.0)
|
66
|
+
rainbow (3.0.0)
|
67
|
+
rake (13.0.3)
|
68
|
+
rb-fsevent (0.10.4)
|
69
|
+
rb-inotify (0.10.1)
|
70
|
+
ffi (~> 1.0)
|
71
|
+
regexp_parser (2.0.3)
|
72
|
+
reverse_markdown (2.0.0)
|
73
|
+
nokogiri
|
74
|
+
rexml (3.2.4)
|
75
|
+
rspec (3.10.0)
|
76
|
+
rspec-core (~> 3.10.0)
|
77
|
+
rspec-expectations (~> 3.10.0)
|
78
|
+
rspec-mocks (~> 3.10.0)
|
79
|
+
rspec-core (3.10.1)
|
80
|
+
rspec-support (~> 3.10.0)
|
81
|
+
rspec-expectations (3.10.1)
|
82
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
83
|
+
rspec-support (~> 3.10.0)
|
84
|
+
rspec-mocks (3.10.1)
|
85
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
86
|
+
rspec-support (~> 3.10.0)
|
87
|
+
rspec-support (3.10.1)
|
88
|
+
rubocop (1.7.0)
|
89
|
+
parallel (~> 1.10)
|
90
|
+
parser (>= 2.7.1.5)
|
91
|
+
rainbow (>= 2.2.2, < 4.0)
|
92
|
+
regexp_parser (>= 1.8, < 3.0)
|
93
|
+
rexml
|
94
|
+
rubocop-ast (>= 1.2.0, < 2.0)
|
95
|
+
ruby-progressbar (~> 1.7)
|
96
|
+
unicode-display_width (>= 1.4.0, < 2.0)
|
97
|
+
rubocop-ast (1.3.0)
|
98
|
+
parser (>= 2.7.1.5)
|
99
|
+
rubocop-rake (0.5.1)
|
100
|
+
rubocop
|
101
|
+
rubocop-rspec (2.1.0)
|
102
|
+
rubocop (~> 1.0)
|
103
|
+
rubocop-ast (>= 1.1.0)
|
104
|
+
ruby-maven (3.3.12)
|
105
|
+
ruby-maven-libs (~> 3.3.9)
|
106
|
+
ruby-maven-libs (3.3.9)
|
107
|
+
ruby-prof (1.4.2)
|
108
|
+
ruby-progressbar (1.10.1)
|
109
|
+
shellany (0.0.1)
|
110
|
+
simplecov (0.20.0)
|
111
|
+
docile (~> 1.1)
|
112
|
+
simplecov-html (~> 0.11)
|
113
|
+
simplecov_json_formatter (~> 0.1)
|
114
|
+
simplecov-html (0.12.3)
|
115
|
+
simplecov_json_formatter (0.1.2)
|
116
|
+
solargraph (0.40.1)
|
117
|
+
backport (~> 1.1)
|
118
|
+
benchmark
|
119
|
+
bundler (>= 1.17.2)
|
120
|
+
e2mmap
|
121
|
+
jaro_winkler (~> 1.5)
|
122
|
+
kramdown (~> 2.3)
|
123
|
+
kramdown-parser-gfm (~> 1.1)
|
124
|
+
parser (~> 2.3)
|
125
|
+
reverse_markdown (>= 1.0.5, < 3)
|
126
|
+
rubocop (>= 0.52)
|
127
|
+
thor (~> 1.0)
|
128
|
+
tilt (~> 2.0)
|
129
|
+
yard (~> 0.9, >= 0.9.24)
|
130
|
+
spoon (0.0.6)
|
131
|
+
ffi
|
132
|
+
terminal-notifier (2.0.0)
|
133
|
+
terminal-notifier-guard (1.7.0)
|
134
|
+
thor (1.0.1)
|
135
|
+
tilt (2.0.10)
|
136
|
+
unicode-display_width (1.7.0)
|
137
|
+
yard (0.9.26)
|
138
|
+
|
139
|
+
PLATFORMS
|
140
|
+
java
|
141
|
+
ruby
|
142
|
+
universal-java-11
|
143
|
+
x86_64-darwin-19
|
144
|
+
|
145
|
+
DEPENDENCIES
|
146
|
+
guard-rspec
|
147
|
+
pry
|
148
|
+
pry-byebug
|
149
|
+
rake
|
150
|
+
rspec (~> 3.0)
|
151
|
+
rubocop
|
152
|
+
rubocop-rake
|
153
|
+
rubocop-rspec
|
154
|
+
ruby-maven
|
155
|
+
ruby-prof
|
156
|
+
ruby-units!
|
157
|
+
simplecov
|
158
|
+
simplecov-html
|
159
|
+
solargraph
|
160
|
+
terminal-notifier
|
161
|
+
terminal-notifier-guard
|
162
|
+
|
163
|
+
BUNDLED WITH
|
164
|
+
2.2.3
|
data/Guardfile
ADDED
@@ -0,0 +1,31 @@
|
|
1
|
+
# A sample Guardfile
|
2
|
+
# More info at https://github.com/guard/guard#readme
|
3
|
+
|
4
|
+
## Uncomment and set this to only include directories you want to watch
|
5
|
+
directories %w[lib spec]
|
6
|
+
|
7
|
+
## Uncomment to clear the screen before every task
|
8
|
+
clearing :on
|
9
|
+
|
10
|
+
# Note: The cmd option is now required due to the increasing number of ways
|
11
|
+
# rspec may be run, below are examples of the most common uses.
|
12
|
+
# * bundler: 'bundle exec rspec'
|
13
|
+
# * bundler binstubs: 'bin/rspec'
|
14
|
+
# * spring: 'bin/rspec' (This will use spring if running and you have
|
15
|
+
# installed the spring binstubs per the docs)
|
16
|
+
# * zeus: 'zeus rspec' (requires the server to be started separately)
|
17
|
+
# * 'just' rspec: 'rspec'
|
18
|
+
|
19
|
+
guard :rspec, cmd: 'bundle exec rspec' do
|
20
|
+
require 'ostruct'
|
21
|
+
|
22
|
+
# Generic Ruby apps
|
23
|
+
rspec = OpenStruct.new
|
24
|
+
rspec.spec = ->(m) { "spec/#{m}_spec.rb" }
|
25
|
+
rspec.spec_dir = 'spec'
|
26
|
+
rspec.spec_helper = 'spec/spec_helper.rb'
|
27
|
+
|
28
|
+
watch(%r{^spec/.+_spec\.rb$})
|
29
|
+
watch(%r{^lib/(.+)\.rb$}) { |m| rspec.spec.call(m[1]) }
|
30
|
+
watch(rspec.spec_helper) { rspec.spec_dir }
|
31
|
+
end
|
data/LICENSE.txt
CHANGED
@@ -1,20 +1,21 @@
|
|
1
|
-
|
1
|
+
The MIT License (MIT)
|
2
2
|
|
3
|
-
|
4
|
-
a copy of this software and associated documentation files (the
|
5
|
-
"Software"), to deal in the Software without restriction, including
|
6
|
-
without limitation the rights to use, copy, modify, merge, publish,
|
7
|
-
distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
-
permit persons to whom the Software is furnished to do so, subject to
|
9
|
-
the following conditions:
|
3
|
+
Copyright (c) 2019 Kevin Olbrich
|
10
4
|
|
11
|
-
|
12
|
-
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
7
|
+
in the Software without restriction, including without limitation the rights
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
10
|
+
furnished to do so, subject to the following conditions:
|
13
11
|
|
14
|
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
13
|
+
all copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
21
|
+
THE SOFTWARE.
|
data/README.md
CHANGED
@@ -1,38 +1,45 @@
|
|
1
|
-
Ruby Units
|
2
|
-
==========
|
1
|
+
# Ruby Units
|
3
2
|
|
4
|
-
[![
|
3
|
+
[![Maintainability](https://api.codeclimate.com/v1/badges/4e858d14a07dd453f748/maintainability.svg)](https://codeclimate.com/github/olbrich/ruby-units/maintainability)
|
4
|
+
[![CodeClimate Status](https://api.codeclimate.com/v1/badges/4e858d14a07dd453f748/test_coverage.svg)](https://codeclimate.com/github/olbrich/ruby-units/test_coverage)
|
5
|
+
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Folbrich%2Fruby-units.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Folbrich%2Fruby-units?ref=badge_shield)
|
5
6
|
|
6
7
|
Kevin C. Olbrich, Ph.D.
|
7
8
|
|
8
|
-
Project page:
|
9
|
+
Project page:
|
10
|
+
[http://github.com/olbrich/ruby-units](http://github.com/olbrich/ruby-units)
|
9
11
|
|
10
|
-
|
11
|
-
-----
|
12
|
+
## Introduction
|
12
13
|
|
13
|
-
|
14
|
-
|
15
|
-
|
14
|
+
Many technical applications make use of specialized calculations at some point.
|
15
|
+
Frequently, these calculations require unit conversions to ensure accurate
|
16
|
+
results. Needless to say, this is a pain to properly keep track of, and is prone
|
17
|
+
to numerous errors.
|
16
18
|
|
17
|
-
|
18
|
-
------------
|
19
|
+
## Solution
|
19
20
|
|
20
|
-
|
21
|
+
The 'Ruby units' gem is designed to simplify the handling of units for
|
22
|
+
scientific calculations. The units of each quantity are specified when a Unit
|
23
|
+
object is created and the Unit class will handle all subsequent conversions and
|
24
|
+
manipulations to ensure an accurate result.
|
21
25
|
|
22
|
-
|
23
|
-
--------
|
26
|
+
## Installation
|
24
27
|
|
25
|
-
|
28
|
+
This package may be installed using:
|
26
29
|
|
27
|
-
|
28
|
-
|
29
|
-
|
30
|
-
This package may be installed using: `gem install ruby-units`
|
30
|
+
```bash
|
31
|
+
gem install ruby-units
|
32
|
+
```
|
31
33
|
|
32
|
-
|
33
|
-
------
|
34
|
+
or add this to your `Gemfile`
|
34
35
|
|
36
|
+
```ruby
|
37
|
+
gem 'ruby-units'
|
35
38
|
```
|
39
|
+
|
40
|
+
## Usage
|
41
|
+
|
42
|
+
```ruby
|
36
43
|
unit = Unit.new("1") # constant only
|
37
44
|
unit = Unit.new("mm") # unit only (defaults to a scalar of 1)
|
38
45
|
unit = Unit.new("1 mm") # create a simple unit
|
@@ -47,32 +54,32 @@ unit = Unit.new('1/4 cup') # Rational number
|
|
47
54
|
unit = Unit.new('1+1i mm') # Complex Number
|
48
55
|
```
|
49
56
|
|
50
|
-
Rules
|
51
|
-
------
|
57
|
+
### Rules
|
52
58
|
|
53
|
-
1.
|
54
|
-
2.
|
55
|
-
3.
|
59
|
+
1. only 1 quantity per unit (with 2 exceptions... 6'5" and '8 lbs 8 oz')
|
60
|
+
2. use SI notation when possible
|
61
|
+
3. spaces in units are allowed, but ones like '11/m' will be recognized as '11
|
62
|
+
1/m'.
|
56
63
|
|
57
|
-
Unit compatibility
|
58
|
-
-------------------
|
64
|
+
### Unit compatibility
|
59
65
|
|
60
|
-
Many methods require that the units of two operands are compatible. Compatible
|
66
|
+
Many methods require that the units of two operands are compatible. Compatible
|
67
|
+
units are those that can be easily converted into each other, such as 'meters'
|
68
|
+
and 'feet'.
|
61
69
|
|
62
|
-
```
|
70
|
+
```ruby
|
63
71
|
unit1 =~ unit2 #=> true if units are compatible
|
64
72
|
unit1.compatible?(unit2) #=> true if units are compatible
|
65
73
|
```
|
66
74
|
|
67
|
-
Unit Math
|
68
|
-
----------
|
75
|
+
### Unit Math
|
69
76
|
|
70
|
-
```
|
77
|
+
```text
|
71
78
|
Unit#+() # Add. only works if units are compatible
|
72
79
|
Unit#-() # Subtract. only works if units are compatible
|
73
|
-
Unit#*() # Multiply.
|
80
|
+
Unit#*() # Multiply.
|
74
81
|
Unit#/() # Divide.
|
75
|
-
Unit#**() # Exponentiate. Exponent must be an integer, can be positive, negative, or zero
|
82
|
+
Unit#**() # Exponentiate. Exponent must be an integer, can be positive, negative, or zero
|
76
83
|
Unit#inverse # Returns 1/unit
|
77
84
|
Unit#abs # Returns absolute value of the unit quantity. Strips off the units
|
78
85
|
Unit#ceil # rounds quantity to next highest integer
|
@@ -81,20 +88,20 @@ Unit#round # rounds quantity to nearest integer
|
|
81
88
|
Unit#to_int # returns the quantity as an integer
|
82
89
|
```
|
83
90
|
|
84
|
-
Unit will coerce other objects into a Unit if used in a formula. This means
|
91
|
+
Unit will coerce other objects into a Unit if used in a formula. This means...
|
85
92
|
|
86
|
-
```
|
93
|
+
```ruby
|
87
94
|
Unit.new("1 mm") + "2 mm" == Unit.new("3 mm")
|
88
95
|
```
|
89
96
|
|
90
|
-
This will work as expected so long as you start the formula with a Unit
|
97
|
+
This will work as expected so long as you start the formula with a `Unit`
|
98
|
+
object.
|
91
99
|
|
92
|
-
Conversions &
|
93
|
-
-------------------------
|
100
|
+
### Conversions & Comparisons
|
94
101
|
|
95
102
|
Units can be converted to other units in a couple of ways.
|
96
103
|
|
97
|
-
```
|
104
|
+
```ruby
|
98
105
|
unit.convert_to('ft') # convert
|
99
106
|
unit1 = unit >> "ft" # convert to 'feet'
|
100
107
|
unit >>= "ft" # convert and overwrite original object
|
@@ -106,83 +113,89 @@ unit1 + unit2 >> "ft" # converts result of math to 'ft'
|
|
106
113
|
(unit1 + unit2).convert_to('ft') # converts result to 'ft'
|
107
114
|
```
|
108
115
|
|
109
|
-
Any object that defines a
|
116
|
+
Any object that defines a `to_unit` method will be automatically coerced to a
|
117
|
+
unit during calculations.
|
110
118
|
|
111
|
-
Text Output
|
112
|
-
-----------
|
119
|
+
### Text Output
|
113
120
|
|
114
|
-
Units will display themselves nicely based on the display_name for the units and
|
121
|
+
Units will display themselves nicely based on the display_name for the units and
|
122
|
+
prefixes. Since `Unit` implements a `Unit#to_s`, all that is needed in most
|
123
|
+
cases is:
|
115
124
|
|
116
|
-
```
|
125
|
+
```ruby
|
117
126
|
"#{Unit.new('1 mm')}" #=> "1 mm"
|
118
127
|
```
|
119
128
|
|
120
|
-
The to_s also accepts some options.
|
129
|
+
The `to_s` also accepts some options.
|
121
130
|
|
122
|
-
```
|
131
|
+
```ruby
|
123
132
|
Unit.new('1.5 mm').to_s("%0.2f") # "1.50 mm". Enter any valid format
|
124
|
-
|
133
|
+
# string. Also accepts strftime format
|
125
134
|
Unit.new('1.5 mm').to_s("in") # converts to inches before printing
|
126
135
|
Unit.new("2 m").to_s(:ft) # returns 6'7"
|
127
136
|
Unit.new("100 kg").to_s(:lbs) # returns 220 lbs, 7 oz
|
128
137
|
Unit.new("100 kg").to_s(:stone) # returns 15 stone, 10 lb
|
129
138
|
```
|
130
139
|
|
131
|
-
Time Helpers
|
132
|
-
------------
|
140
|
+
### Time Helpers
|
133
141
|
|
134
|
-
Time
|
142
|
+
`Time`, `Date`, and `DateTime` objects can have time units added or subtracted.
|
135
143
|
|
136
|
-
```
|
144
|
+
```ruby
|
137
145
|
Time.now + Unit.new("10 min")
|
138
146
|
```
|
139
147
|
|
140
|
-
Several helpers have also been defined. Note: If you include the 'Chronic' gem,
|
148
|
+
Several helpers have also been defined. Note: If you include the 'Chronic' gem,
|
149
|
+
you can specify times in natural language.
|
141
150
|
|
142
|
-
```
|
143
|
-
|
151
|
+
```ruby
|
152
|
+
Unit.new('min').since(DateTime.parse('9/18/06 3:00pm'))
|
144
153
|
```
|
145
154
|
|
146
155
|
Durations may be entered as 'HH:MM:SS, usec' and will be returned in 'hours'.
|
147
156
|
|
148
|
-
```
|
157
|
+
```ruby
|
149
158
|
Unit.new('1:00') #=> 1 h
|
150
159
|
Unit.new('0:30') #=> 0.5 h
|
151
160
|
Unit.new('0:30:30') #=> 0.5 h + 30 sec
|
152
161
|
```
|
153
162
|
|
154
|
-
If only one ":" is present, it is interpreted as the separator between hours and
|
163
|
+
If only one ":" is present, it is interpreted as the separator between hours and
|
164
|
+
minutes.
|
155
165
|
|
156
|
-
Ranges
|
157
|
-
------
|
166
|
+
### Ranges
|
158
167
|
|
159
|
-
```
|
168
|
+
```ruby
|
160
169
|
[Unit.new('0 h')..Unit.new('10 h')].each {|x| p x}
|
161
170
|
```
|
162
171
|
|
163
172
|
works so long as the starting point has an integer scalar
|
164
173
|
|
165
|
-
Math functions
|
166
|
-
--------------
|
174
|
+
### Math functions
|
167
175
|
|
168
|
-
All Trig math functions (sin, cos, sinh, hypot...) can take a unit as their
|
176
|
+
All Trig math functions (sin, cos, sinh, hypot...) can take a unit as their
|
177
|
+
parameter. It will be converted to radians and then used if possible.
|
169
178
|
|
170
|
-
Temperatures
|
171
|
-
------------
|
179
|
+
### Temperatures
|
172
180
|
|
173
|
-
Ruby-units makes a distinction between a temperature (which technically is a
|
181
|
+
Ruby-units makes a distinction between a temperature (which technically is a
|
182
|
+
property) and degrees of temperature (which temperatures are measured in).
|
174
183
|
|
175
|
-
Temperature units (i.e., 'tempK') can be converted back and forth, and will take
|
184
|
+
Temperature units (i.e., 'tempK') can be converted back and forth, and will take
|
185
|
+
into account the differences in the zero points of the various scales.
|
186
|
+
Differential temperature (e.g., Unit.new('100 degC')) units behave like most
|
187
|
+
other units.
|
176
188
|
|
177
|
-
```
|
189
|
+
```ruby
|
178
190
|
Unit.new('37 tempC').convert_to('tempF') #=> 98.6 tempF
|
179
191
|
```
|
180
192
|
|
181
|
-
Ruby-units will raise an exception if you attempt to create a temperature unit
|
193
|
+
Ruby-units will raise an exception if you attempt to create a temperature unit
|
194
|
+
that would fall below absolute zero.
|
182
195
|
|
183
196
|
Unit math on temperatures is fairly limited.
|
184
197
|
|
185
|
-
```
|
198
|
+
```ruby
|
186
199
|
Unit.new('100 tempC') + Unit.new('10 degC') # '110 tempC'.to_unit
|
187
200
|
Unit.new('100 tempC') - Unit.new('10 degC') # '90 tempC'.to_unit
|
188
201
|
Unit.new('100 tempC') + Unit.new('50 tempC') # exception (can't add two temperatures)
|
@@ -194,31 +207,31 @@ Unit.new('100 tempC') * unit # exception
|
|
194
207
|
Unit.new('100 tempC') / unit # exception
|
195
208
|
Unit.new('100 tempC') ** N # exception
|
196
209
|
|
197
|
-
Unit.new('100 tempC').convert_to('degC') #=> Unit.new('100 degC')
|
210
|
+
Unit.new('100 tempC').convert_to('degC') #=> Unit.new('100 degC')
|
198
211
|
```
|
199
212
|
|
200
213
|
This conversion references the 0 point on the scale of the temperature unit
|
201
214
|
|
202
|
-
```
|
215
|
+
```ruby
|
203
216
|
Unit.new('100 degC').convert_to('tempC') #=> '-173 tempC'.to_unit
|
204
217
|
```
|
205
218
|
|
206
|
-
These conversions are always interpreted as being relative to absolute zero.
|
219
|
+
These conversions are always interpreted as being relative to absolute zero.
|
220
|
+
Conversions are probably better done like this...
|
207
221
|
|
208
|
-
```
|
222
|
+
```ruby
|
209
223
|
Unit.new('0 tempC') + Unit.new('100 degC') #=> Unit.new('100 tempC')
|
210
224
|
```
|
211
225
|
|
212
|
-
Defining Units
|
213
|
-
--------------
|
226
|
+
### Defining Units
|
214
227
|
|
215
228
|
It is possible to define new units or redefine existing ones.
|
216
229
|
|
217
|
-
|
230
|
+
#### Define New Unit
|
218
231
|
|
219
232
|
The easiest approach is to define a unit in terms of other units.
|
220
233
|
|
221
|
-
```
|
234
|
+
```ruby
|
222
235
|
Unit.define("foobar") do |foobar|
|
223
236
|
foobar.definition = Unit.new("1 foo") * Unit.new("1 bar") # anything that results in a Unit object
|
224
237
|
foobar.aliases = %w{foobar fb} # array of synonyms for the unit
|
@@ -226,11 +239,13 @@ Unit.define("foobar") do |foobar|
|
|
226
239
|
end
|
227
240
|
```
|
228
241
|
|
229
|
-
|
242
|
+
#### Redefine Existing Unit
|
230
243
|
|
231
|
-
Redefining a unit allows the user to change a single aspect of a definition
|
244
|
+
Redefining a unit allows the user to change a single aspect of a definition
|
245
|
+
without having to re-create the entire definition. This is useful for changing
|
246
|
+
display names, adding aliases, etc.
|
232
247
|
|
233
|
-
```
|
248
|
+
```ruby
|
234
249
|
Unit.redefine!("cup") do |cup|
|
235
250
|
cup.display_name = "cup"
|
236
251
|
end
|
@@ -238,39 +253,46 @@ end
|
|
238
253
|
|
239
254
|
### Useful methods
|
240
255
|
|
241
|
-
1. `scalar` will return the numeric portion of the unit without the attached
|
256
|
+
1. `scalar` will return the numeric portion of the unit without the attached
|
257
|
+
units
|
242
258
|
2. `base_scalar` will return the scalar in base units (SI)
|
243
259
|
3. `units` will return the name of the units (without the scalar)
|
244
260
|
4. `base` will return the unit converted to base units (SI)
|
245
261
|
|
246
262
|
### Storing in a database
|
247
263
|
|
248
|
-
Units can be stored in a database as either the string representation or in two
|
249
|
-
|
264
|
+
Units can be stored in a database as either the string representation or in two
|
265
|
+
separate columns defining the scalar and the units. Note that if sorting by
|
266
|
+
units is desired you will want to ensure that you are storing the scalars in a
|
267
|
+
consistent unit (i.e, the base units).
|
250
268
|
|
251
269
|
### Namespaced Class
|
252
270
|
|
253
|
-
Sometimes the default class 'Unit' may conflict with other gems or applications.
|
271
|
+
Sometimes the default class 'Unit' may conflict with other gems or applications.
|
272
|
+
Internally ruby-units defines itself using the RubyUnits namespace. The actual
|
273
|
+
class of a unit is the RubyUnits::Unit. For simplicity and backwards
|
274
|
+
compatibility, the `::Unit` class is defined as an alias to `::RubyUnits::Unit`.
|
254
275
|
|
255
276
|
To load ruby-units without this alias...
|
256
277
|
|
257
|
-
```
|
278
|
+
```ruby
|
258
279
|
require 'ruby_units/namespaced'
|
259
280
|
```
|
260
281
|
|
261
282
|
When using bundler...
|
262
283
|
|
263
|
-
```
|
284
|
+
```ruby
|
264
285
|
gem 'ruby-units', require: 'ruby_units/namespaced'
|
265
286
|
```
|
266
287
|
|
267
|
-
Note: when using the namespaced version, the Unit.new('unit string') helper
|
288
|
+
Note: when using the namespaced version, the `Unit.new('unit string')` helper
|
289
|
+
will not be defined.
|
268
290
|
|
269
291
|
### Configuration
|
270
292
|
|
271
293
|
Configuration options can be set like:
|
272
294
|
|
273
|
-
```
|
295
|
+
```ruby
|
274
296
|
RubyUnits.configure do |config|
|
275
297
|
config.separator = false
|
276
298
|
end
|
@@ -278,14 +300,20 @@ end
|
|
278
300
|
|
279
301
|
Currently there is only one configuration you can set:
|
280
302
|
|
281
|
-
1. separator (true/false): should a space be used to separate the scalar from
|
282
|
-
|
303
|
+
1. separator (true/false): should a space be used to separate the scalar from
|
304
|
+
the unit part during output.
|
283
305
|
|
284
306
|
### NOTES
|
285
307
|
|
286
308
|
#### Performance vs. Accuracy
|
287
309
|
|
288
|
-
Ruby units was originally intended to provide a robust and accurate way to do
|
289
|
-
In some cases, these conversions can result in the
|
290
|
-
|
291
|
-
|
310
|
+
Ruby units was originally intended to provide a robust and accurate way to do
|
311
|
+
arbitrary unit conversions. In some cases, these conversions can result in the
|
312
|
+
creation and garbage collection of a lot of intermediate objects during
|
313
|
+
calculations. This in turn can have a negative impact on performance. The design
|
314
|
+
of ruby-units has emphasized accuracy over speed. YMMV if you are doing a lot of
|
315
|
+
math involving units.
|
316
|
+
|
317
|
+
## License
|
318
|
+
|
319
|
+
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Folbrich%2Fruby-units.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Folbrich%2Fruby-units?ref=badge_large)
|