1 /*
2 * Copyright (C) 2018 Alberto Irurueta Carro (alberto@irurueta.com)
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.irurueta.units;
17
18 import java.math.BigDecimal;
19
20 /**
21 * Contains a frequency value and unit.
22 */
23 @SuppressWarnings("WeakerAccess")
24 public class Frequency extends Measurement<FrequencyUnit> {
25
26 /**
27 * Constructor with value and unit.
28 *
29 * @param value frequency value.
30 * @param unit unit of frequency.
31 * @throws IllegalArgumentException if either value or unit is null.
32 */
33 public Frequency(final Number value, final FrequencyUnit unit) {
34 super(value, unit);
35 }
36
37 /**
38 * Constructor.
39 */
40 Frequency() {
41 super();
42 }
43
44 /**
45 * Determines if two frequencies are equal up to a certain tolerance.
46 * If needed, this method attempts unit conversion to compare both objects.
47 *
48 * @param other another measurement to compare.
49 * @param tolerance amount of tolerance to determine whether two frequency instances are equal or not.
50 * @return true if provided frequency is assumed to be equal to this instance,
51 * false otherwise.
52 */
53 @Override
54 public boolean equals(
55 final Measurement<FrequencyUnit> other, final double tolerance) {
56 if (super.equals(other, tolerance)) {
57 return true;
58 }
59
60 //attempt conversion to common units
61 if (other == null) {
62 return false;
63 }
64
65 final var otherValue = FrequencyConverter.convert(other.getValue().doubleValue(), other.getUnit(), getUnit());
66 return Math.abs(getValue().doubleValue() - otherValue) <= tolerance;
67 }
68
69 /**
70 * Adds two frequency values and units and returns the result.
71 *
72 * @param value1 1st argument value.
73 * @param unit1 1st argument unit.
74 * @param value2 2nd argument value.
75 * @param unit2 2nd argument unit.
76 * @param resultUnit unit of result to be returned.
77 * @return result of addition.
78 */
79 public static double add(
80 final double value1, final FrequencyUnit unit1,
81 final double value2, final FrequencyUnit unit2,
82 final FrequencyUnit resultUnit) {
83 final var v1 = FrequencyConverter.convert(value1, unit1, resultUnit);
84 final var v2 = FrequencyConverter.convert(value2, unit2, resultUnit);
85 return v1 + v2;
86 }
87
88 /**
89 * Adds two frequency values and units and returns the result.
90 *
91 * @param value1 1st argument value.
92 * @param unit1 1st argument unit.
93 * @param value2 2nd argument value.
94 * @param unit2 2nd argument unit.
95 * @param resultUnit unit of result to be returned.
96 * @return result of addition.
97 */
98 public static Number add(
99 final Number value1, final FrequencyUnit unit1,
100 final Number value2, final FrequencyUnit unit2,
101 final FrequencyUnit resultUnit) {
102 return BigDecimal.valueOf(add(value1.doubleValue(), unit1, value2.doubleValue(), unit2, resultUnit));
103 }
104
105 /**
106 * Adds two frequency instances and stores the result into provided instance.
107 *
108 * @param arg1 1st argument.
109 * @param arg2 2nd argument.
110 * @param result instance where result will be stored.
111 */
112 public static void add(
113 final Frequency arg1, final Frequency arg2,
114 final Frequency result) {
115 result.setValue(add(arg1.getValue(), arg1.getUnit(), arg2.getValue(), arg2.getUnit(), result.getUnit()));
116 }
117
118 /**
119 * Adds two frequency instances.
120 *
121 * @param arg1 1st argument.
122 * @param arg2 2nd argument.
123 * @param unit unit of returned frequency.
124 * @return a new instance containing result.
125 */
126 public static Frequency addAndReturnNew(final Frequency arg1, final Frequency arg2, final FrequencyUnit unit) {
127 final var result = new Frequency();
128 result.setUnit(unit);
129 add(arg1, arg2, result);
130 return result;
131 }
132
133 /**
134 * Adds provided frequency value and unit and returns a new frequency instance
135 * using provided unit.
136 *
137 * @param value value to be added.
138 * @param unit unit of value to be added.
139 * @param resultUnit unit of returned frequency.
140 * @return a new frequency containing result.
141 */
142 public Frequency addAndReturnNew(final double value, final FrequencyUnit unit, final FrequencyUnit resultUnit) {
143 final var result = new Frequency();
144 result.setUnit(resultUnit);
145 result.setValue(add(getValue().doubleValue(), getUnit(), value, unit, resultUnit));
146 return result;
147 }
148
149 /**
150 * Adds provided frequency value and unit and returns a new frequency instance using
151 * provided unit.
152 *
153 * @param value value to be added.
154 * @param unit unit of value to be added.
155 * @param resultUnit unit of returned frequency.
156 * @return a new frequency containing result.
157 */
158 public Frequency addAndReturnNew(final Number value, final FrequencyUnit unit, final FrequencyUnit resultUnit) {
159 final var result = new Frequency();
160 result.setUnit(resultUnit);
161 result.setValue(add(getValue(), getUnit(), value, unit, resultUnit));
162 return result;
163 }
164
165 /**
166 * Adds provided frequency to current instance and returns a new frequency instance.
167 *
168 * @param f frequency to be added.
169 * @param unit unit of returned frequency.
170 * @return a new frequency containing result.
171 */
172 public Frequency addAndReturnNew(final Frequency f, final FrequencyUnit unit) {
173 return addAndReturnNew(this, f, unit);
174 }
175
176 /**
177 * Adds provided frequency value and unit and updates current frequency instance.
178 *
179 * @param value frequency value to be added.
180 * @param unit unit of frequency value.
181 */
182 public void add(final double value, final FrequencyUnit unit) {
183 setValue(add(getValue(), getUnit(), value, unit, getUnit()));
184 }
185
186 /**
187 * Adds provided frequency value and unit and updates current frequency instance.
188 *
189 * @param value frequency value to be added.
190 * @param unit unit of frequency value.
191 */
192 public void add(final Number value, final FrequencyUnit unit) {
193 setValue(add(getValue(), getUnit(), value, unit, getUnit()));
194 }
195
196 /**
197 * Adds provided frequency and updates current frequency instance.
198 *
199 * @param frequency frequency to be added.
200 */
201 public void add(final Frequency frequency) {
202 add(this, frequency, this);
203 }
204
205 /**
206 * Adds provided frequency and stores the result into provided frequency instance.
207 *
208 * @param f frequency to be added.
209 * @param result instance where result will be stored.
210 */
211 public void add(final Frequency f, final Frequency result) {
212 add(this, f, result);
213 }
214
215 /**
216 * Subtracts two frequency values and units and returns the result.
217 *
218 * @param value1 1st argument value.
219 * @param unit1 1st argument unit.
220 * @param value2 2nd argument value.
221 * @param unit2 2nd argument unit.
222 * @param resultUnit unit of result to be returned.
223 * @return result of subtraction.
224 */
225 public static double subtract(
226 final double value1, final FrequencyUnit unit1,
227 final double value2, final FrequencyUnit unit2,
228 final FrequencyUnit resultUnit) {
229 final var v1 = FrequencyConverter.convert(value1, unit1, resultUnit);
230 final var v2 = FrequencyConverter.convert(value2, unit2, resultUnit);
231 return v1 - v2;
232 }
233
234 /**
235 * Subtracts two frequency values and units and returns the result.
236 *
237 * @param value1 1st argument value.
238 * @param unit1 1st argument unit.
239 * @param value2 2nd argument value.
240 * @param unit2 2nd argument unit.
241 * @param resultUnit unit of result to be returned.
242 * @return result of subtraction.
243 */
244 public static Number subtract(
245 final Number value1, final FrequencyUnit unit1,
246 final Number value2, final FrequencyUnit unit2,
247 final FrequencyUnit resultUnit) {
248 return BigDecimal.valueOf(subtract(value1.doubleValue(), unit1, value2.doubleValue(), unit2, resultUnit));
249 }
250
251 /**
252 * Subtracts two frequency instances and stores the result into provided instance.
253 *
254 * @param arg1 1st argument.
255 * @param arg2 2nd argument.
256 * @param result instance where result will be stored.
257 */
258 public static void subtract(
259 final Frequency arg1, final Frequency arg2, final Frequency result) {
260 result.setValue(subtract(arg1.getValue(), arg1.getUnit(), arg2.getValue(), arg2.getUnit(), result.getUnit()));
261 }
262
263 /**
264 * Subtracts two frequency instances.
265 *
266 * @param arg1 1st argument.
267 * @param arg2 2nd argument.
268 * @param unit unit of returned frequency.
269 * @return a new instance containing result.
270 */
271 public static Frequency subtractAndReturnNew(
272 final Frequency arg1, final Frequency arg2, final FrequencyUnit unit) {
273 final var result = new Frequency();
274 result.setUnit(unit);
275 subtract(arg1, arg2, result);
276 return result;
277 }
278
279 /**
280 * Subtracts provided frequency value and unit and returns a new frequency instance
281 * using provided unit.
282 *
283 * @param value value to be subtracted.
284 * @param unit unit of value to be subtracted.
285 * @param resultUnit unit of returned frequency.
286 * @return a new frequency containing result.
287 */
288 public Frequency subtractAndReturnNew(
289 final double value, final FrequencyUnit unit, final FrequencyUnit resultUnit) {
290 final var result = new Frequency();
291 result.setUnit(resultUnit);
292 result.setValue(subtract(getValue().doubleValue(), getUnit(), value, unit, resultUnit));
293 return result;
294 }
295
296 /**
297 * Subtracts provided frequency value and unit and returns a new frequency instance
298 * using provided unit.
299 *
300 * @param value value to be subtracted.
301 * @param unit unit of value to be subtracted.
302 * @param resultUnit unit of returned frequency.
303 * @return a new frequency containing result.
304 */
305 public Frequency subtractAndReturnNew(
306 final Number value, final FrequencyUnit unit, final FrequencyUnit resultUnit) {
307 final var result = new Frequency();
308 result.setUnit(resultUnit);
309 result.setValue(subtract(getValue(), getUnit(), value, unit, resultUnit));
310 return result;
311 }
312
313 /**
314 * Subtracts provided frequency from current instance and returns a new instance.
315 *
316 * @param f frequency to be subtracted.
317 * @param unit unit of returned frequency.
318 * @return a new frequency containing result.
319 */
320 public Frequency subtractAndReturnNew(final Frequency f, final FrequencyUnit unit) {
321 return subtractAndReturnNew(this, f, unit);
322 }
323
324 /**
325 * Subtracts provided frequency value and unit and updates current frequency
326 * instance.
327 *
328 * @param value frequency value to be subtracted.
329 * @param unit unit of frequency value.
330 */
331 public void subtract(final double value, final FrequencyUnit unit) {
332 setValue(subtract(getValue(), getUnit(), value, unit, getUnit()));
333 }
334
335 /**
336 * Subtracts provided frequency value and unit and updates current frequency instance.
337 *
338 * @param value frequency value to be subtracted.
339 * @param unit unit of frequency value.
340 */
341 public void subtract(final Number value, final FrequencyUnit unit) {
342 setValue(subtract(getValue(), getUnit(), value, unit, getUnit()));
343 }
344
345 /**
346 * Subtracts provided frequency and updates current frequency.
347 *
348 * @param frequency frequency to be subtracted.
349 */
350 public void subtract(final Frequency frequency) {
351 subtract(this, frequency, this);
352 }
353
354 /**
355 * Subtracts provided frequency and stores the result into provided frequency.
356 *
357 * @param f frequency to be subtracted.
358 * @param result instance where result will be stored.
359 */
360 public void subtract(final Frequency f, final Frequency result) {
361 subtract(this, f, result);
362 }
363 }