001 /*
002 * Java GPX Library (jpx-3.1.0).
003 * Copyright (c) 2016-2023 Franz Wilhelmstötter
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 *
017 * Author:
018 * Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com)
019 */
020 package io.jenetics.jpx;
021
022 import static java.lang.String.format;
023
024 import java.io.DataInput;
025 import java.io.DataOutput;
026 import java.io.IOException;
027 import java.io.InvalidObjectException;
028 import java.io.ObjectInputStream;
029 import java.io.Serial;
030 import java.io.Serializable;
031
032 /**
033 * Used for bearing, heading, course. Base unit is decimal degree. Only values
034 * in the range of {@code [0..360]} are valid.
035 *
036 * @see <a href="https://en.wikipedia.org/wiki/Value_object">Value object</a>
037 *
038 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
039 * @version 2.0
040 * @since 1.0
041 */
042 public final class Degrees
043 extends Number
044 implements
045 Comparable<Degrees>,
046 Serializable
047 {
048
049 @Serial
050 private static final long serialVersionUID = 2L;
051
052 /**
053 * A constant holding the maximum value a {@code Degrees} value can have,
054 * 0 inclusively.
055 *
056 * @since 2.0
057 */
058 public static final double MIN_VALUE = 0;
059
060 /**
061 * A constant holding the maximum value a {@code Degrees} value can have,
062 * 360 inclusively.
063 *
064 * @since 2.0
065 */
066 public static final double MAX_VALUE = 360;
067
068 private final double _value;
069
070 /**
071 * Create a new {@code Degrees} object with the given <i>decimal</i> degree
072 * value.
073 *
074 * @param value the decimal degree value
075 * @throws IllegalArgumentException if the give value is not within the
076 * range of {@code [0..360]}
077 */
078 private Degrees(final double value) {
079 if (value < MIN_VALUE || value >= MAX_VALUE) {
080 throw new IllegalArgumentException(format(
081 "%f not in the range [0, 360).", value
082 ));
083 }
084
085 _value = value;
086 }
087
088 /**
089 * Return the decimal degree value.
090 *
091 * @return the decimal degree value
092 */
093 @Override
094 public double doubleValue() {
095 return _value;
096 }
097
098 /**
099 * Return the degrees in radians.
100 *
101 * @return the degrees in radians
102 */
103 public double toRadians() {
104 return Math.toRadians(_value);
105 }
106
107 /**
108 * Return the decimal degree value.
109 *
110 * @return the decimal degree value
111 */
112 public double toDegrees() {
113 return _value;
114 }
115
116 @Override
117 public int intValue() {
118 return (int)doubleValue();
119 }
120
121 @Override
122 public long longValue() {
123 return (long)doubleValue();
124 }
125
126 @Override
127 public float floatValue() {
128 return (float)doubleValue();
129 }
130
131 @Override
132 public int compareTo(final Degrees other) {
133 return Double.compare(_value, other._value);
134 }
135
136 @Override
137 public int hashCode() {
138 return Double.hashCode(_value);
139 }
140
141 @Override
142 public boolean equals(final Object obj) {
143 return obj == this ||
144 obj instanceof Degrees deg &&
145 Double.compare(deg._value, _value) == 0;
146 }
147
148 @Override
149 public String toString() {
150 return Double.toString(_value);
151 }
152
153
154 /* *************************************************************************
155 * Static object creation methods
156 * ************************************************************************/
157
158 /**
159 * Create a new {@code Degrees} object with the given <i>decimal</i> degree
160 * value.
161 *
162 * @param degrees the decimal degree value
163 * @return a new {@code Degrees} object
164 * @throws IllegalArgumentException if the give value is not within the
165 * range of {@code [0..360]}
166 */
167 public static Degrees ofDegrees(final double degrees) {
168 return new Degrees(degrees);
169 }
170
171 /**
172 * Create a new {@code Degrees} object with the given radians value.
173 *
174 * @param radians the radians value
175 * @return a new {@code Degrees} object
176 * @throws IllegalArgumentException if the give value is not within the
177 * range of {@code [0..2*Pi]}
178 */
179 public static Degrees ofRadians(final double radians) {
180 return new Degrees(Math.toDegrees(radians));
181 }
182
183 static Degrees parse(final String value) {
184 final String deg = Strings.trim(value);
185
186 return deg != null
187 ? Degrees.ofDegrees(Double.parseDouble(deg))
188 : null;
189 }
190
191 /* *************************************************************************
192 * Java object serialization
193 * ************************************************************************/
194
195 @Serial
196 private Object writeReplace() {
197 return new SerialProxy(SerialProxy.DEGREES, this);
198 }
199
200 @Serial
201 private void readObject(final ObjectInputStream stream)
202 throws InvalidObjectException
203 {
204 throw new InvalidObjectException("Serialization proxy required.");
205 }
206
207 void write(final DataOutput out) throws IOException {
208 out.writeDouble(_value);
209 }
210
211 static Degrees read(final DataInput in) throws IOException {
212 return new Degrees(in.readDouble());
213 }
214
215 }
|