Module: SY::Unit

Includes:
NameMagic
Defined in:
lib/sy/unit.rb

Overview

This class represents a unit of measurement – a predefined magnitude of a metrological quantity.

Constant Summary collapse

PROTECTED_NAMES = 
[ "kilogram" ]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#abbreviation ⇒ Object Also known as: short

Unlike ordinary magnitudes, units can have names and abbreviations.



126
127
128
 
# File 'lib/sy/unit.rb', line 126

def abbreviation
  @abbreviation
end

#warns ⇒ Object Also known as: warns?

Whether the unit warns when the module in which unit method mixin is included contains blatant name collisions with this unit name/abbreviation.



132
133
134
 
# File 'lib/sy/unit.rb', line 132

def warns
  @warns
end

Class Method Details

.abbreviations ⇒ Object

Unit abbreviations as a hash of abbreviation => unit pairs.



105
106
107
108
 
# File 'lib/sy/unit.rb', line 105

def abbreviations
  ii = instances
  Hash[ ii.map( &:short ).zip( ii ).select { |short, _| ! short.nil? } ]
end

.included(target) ⇒ Object 



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/sy/unit.rb', line 30

def included target
  target.namespace = self

  name_set_hook do |name, new_instance, old_name|

.instance(arg) ⇒ Object

Make Unit#instance ignore capitalization, accept abbreviations.



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 
# File 'lib/sy/unit.rb', line 12

def instance arg
  begin
    super # let's first try the original method
  rescue NameError # if we fail...
    begin # ... let's try the abbreviation
      super instances.find { |unit_inst|
        unit_inst.short.to_s == arg.to_s if unit_inst.short
      }.tap { |rslt| fail NameError if rslt.nil? } # fail if nothing found
    rescue NameError, TypeError
      begin # Let's to try upcase if we have all-downcase arg
        super arg.to_s.upcase
      rescue NameError # if not, tough luck
        raise NameError, "Unknown unit symbol: #{arg}"
      end
    end
  end
end

.known_symbols ⇒ Object

Full list of known unit names and unit abbreviations.



112
113
114
 
# File 'lib/sy/unit.rb', line 112

def known_symbols
  instance_names.map( &:downcase ) + abbreviations.keys
end

.of(quantity, **nn) ⇒ Object

Constructor of units of a given quantity.



85
86
87
 
# File 'lib/sy/unit.rb', line 85

def of quantity, **nn
  quantity.unit **nn
end

.parse_sps_using_all_prefixes(sps) ⇒ Object

Parses an SPS, curring it with known unit names and abbreviations, and all known full and short prefixes.



119
120
121
 
# File 'lib/sy/unit.rb', line 119

def parse_sps_using_all_prefixes sps
  SY::PREFIX_TABLE.parse_sps( sps, known_symbols )
end

.standard(of: nil, **nn) ⇒ Object

Standard unit constructor. In absence of other named arguments, standard unit of the specified quantity is merely retrieved. If other named arguments than :quantity (alias :of) are supplied, they are forwarded to Quantity#new_standard_unit method, that resets the standard unit of the specified quantity. Note that :amount for standard units, if supplied, has special meaning of setting the relationship of that quantity.



96
97
98
99
100
101
 
# File 'lib/sy/unit.rb', line 96

def standard( of: nil, **nn )
  puts "Constructing a standard unit of #{of}." if SY::DEBUG
  fail ArgumentError, ":of argument missing!" if of.nil?
  qnt = SY::Quantity.instance( of )
  nn.empty? ? qnt.standard_unit : qnt.new_standard_unit( **nn )
end

Instance Method Details

#*(other) ⇒ Object

Multiplication: Unit is converted to a magnitude before the operation.



183
184
185
 
# File 'lib/sy/unit.rb', line 183

def * other
  to_magnitude * other
end

#**(exponent) ⇒ Object

Exponentiation: Unit is converted to a magnitude before the operation.



195
196
197
 
# File 'lib/sy/unit.rb', line 195

def ** exponent
  to_magnitude ** exponent
end

#+(other) ⇒ Object

Addition: Unit is converted to a magnitude before the operation.



171
172
173
 
# File 'lib/sy/unit.rb', line 171

def + other
  to_magnitude + other
end

#-(other) ⇒ Object

Subtraction: Unit is converted to a magnitude before the operation.



177
178
179
 
# File 'lib/sy/unit.rb', line 177

def - other
  to_magnitude - other
end

#/(other) ⇒ Object

Division: Unit is converted to a magnitude before the operation.



189
190
191
 
# File 'lib/sy/unit.rb', line 189

def / other
  to_magnitude / other
end

#coerce(other) ⇒ Object

Coercion: Unit is converted to a magnitude before coercion is actually performed.



202
203
204
 
# File 'lib/sy/unit.rb', line 202

def coerce other
  to_magnitude.coerce( other )
end

#initialize(short: nil, warns: true, **nn) ⇒ Object

Constructor of units provides support for one additional named argument: :abbreviation, alias :short. (This is in addition to :name, alias :ɴ named argument provided by NameMagic.) As a general rule, only named units unit should be given abbreviations. In choosing unit names and abbreviations, ambiguity with regard to standard prefixes and abbreviations thereof should also be avoided. Another argument, :warns, Boolean, true by default, determines whether the method warns about name collisions with other methods defined where the SY::ExpressibleInUnits mixin is included.



156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/sy/unit.rb', line 156

def initialize( short: nil, warns: true, **nn )
  @abbreviation = short.to_sym if short
  @warns = warns # does this unit care about blatant name collisions?
    
  # FIXME: Here, we would have to watch out for :amount being set
  # if it is a number, amount is in standard units
  # however, if it is a magnitude, especially one of another equidimensional quantity,
  # it estableshes a relationship between this and that quantity. It means that
  # the unit amount automatically becomes ... one ... and such relationship can
  # only be established for standard quantity
  super nn
end

#inspect ⇒ Object

Inspect string for the unit.



220
221
222
 
# File 'lib/sy/unit.rb', line 220

def inspect
  name.nil? ? inspect_when_anonymous : inspect_when_named
end

#quantity_by_prefix(prefix) ⇒ Object

Some prefixes of some units are almost exclusively used in certain areas of science or engineering, and their appearance would indicate such specific quantity. By default, this method simply returns unit’s own quantity unchanged. But it is expected that the method will be overriden by a singleton method in those units, which have area-specific prefixes. For example, centimetre, typical for civil engineering, could cause reframing into its own CentimetreLength quantity. Assuming METRE unit, this could be specified for example by: <tt> METRE.define_singleton_method :quantity_by_prefix do |full_prefix|

case full_prefix
when :centi then CentimetreLength
else self.quantity end

end </tt>



240
241
242
 
# File 'lib/sy/unit.rb', line 240

def quantity_by_prefix prefix
  quantity
end

#reframe(other_quantity) ⇒ Object

Reframing: Unit is converted to a magnitude before reframing.



208
209
210
 
# File 'lib/sy/unit.rb', line 208

def reframe other_quantity
  to_magnnitude.reframe( other_quantity )
end

#short=(unit_abbreviation) ⇒ Object

Unit abbreviation setter (alias for #abbreviation=).



143
144
145
 
# File 'lib/sy/unit.rb', line 143

def short= unit_abbreviation
  @abbreviation = unit_abbreviation.to_sym
end

#to_s ⇒ Object

Unit as string.



214
215
216
 
# File 'lib/sy/unit.rb', line 214

def to_s
  name.nil? ? to_s_when_anonymous : to_s_when_named
end