1/*
2 * Copyright (C) 2009 The Android Open Source Project
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
17package android.util;
18
19/**
20 * A class that contains utility methods related to numbers.
21 *
22 * @hide Pending API council approval
23 */
24public final class MathUtils {
25    private static final float DEG_TO_RAD = 3.1415926f / 180.0f;
26    private static final float RAD_TO_DEG = 180.0f / 3.1415926f;
27
28    private MathUtils() {
29    }
30
31    public static float abs(float v) {
32        return v > 0 ? v : -v;
33    }
34
35    public static int constrain(int amount, int low, int high) {
36        return amount < low ? low : (amount > high ? high : amount);
37    }
38
39    public static long constrain(long amount, long low, long high) {
40        return amount < low ? low : (amount > high ? high : amount);
41    }
42
43    public static float constrain(float amount, float low, float high) {
44        return amount < low ? low : (amount > high ? high : amount);
45    }
46
47    public static float log(float a) {
48        return (float) Math.log(a);
49    }
50
51    public static float exp(float a) {
52        return (float) Math.exp(a);
53    }
54
55    public static float pow(float a, float b) {
56        return (float) Math.pow(a, b);
57    }
58
59    public static float sqrt(float a) {
60        return (float) Math.sqrt(a);
61    }
62
63    public static float max(float a, float b) {
64        return a > b ? a : b;
65    }
66
67    public static float max(int a, int b) {
68        return a > b ? a : b;
69    }
70
71    public static float max(float a, float b, float c) {
72        return a > b ? (a > c ? a : c) : (b > c ? b : c);
73    }
74
75    public static float max(int a, int b, int c) {
76        return a > b ? (a > c ? a : c) : (b > c ? b : c);
77    }
78
79    public static float min(float a, float b) {
80        return a < b ? a : b;
81    }
82
83    public static float min(int a, int b) {
84        return a < b ? a : b;
85    }
86
87    public static float min(float a, float b, float c) {
88        return a < b ? (a < c ? a : c) : (b < c ? b : c);
89    }
90
91    public static float min(int a, int b, int c) {
92        return a < b ? (a < c ? a : c) : (b < c ? b : c);
93    }
94
95    public static float dist(float x1, float y1, float x2, float y2) {
96        final float x = (x2 - x1);
97        final float y = (y2 - y1);
98        return (float) Math.hypot(x, y);
99    }
100
101    public static float dist(float x1, float y1, float z1, float x2, float y2, float z2) {
102        final float x = (x2 - x1);
103        final float y = (y2 - y1);
104        final float z = (z2 - z1);
105        return (float) Math.sqrt(x * x + y * y + z * z);
106    }
107
108    public static float mag(float a, float b) {
109        return (float) Math.hypot(a, b);
110    }
111
112    public static float mag(float a, float b, float c) {
113        return (float) Math.sqrt(a * a + b * b + c * c);
114    }
115
116    public static float sq(float v) {
117        return v * v;
118    }
119
120    public static float dot(float v1x, float v1y, float v2x, float v2y) {
121        return v1x * v2x + v1y * v2y;
122    }
123
124    public static float cross(float v1x, float v1y, float v2x, float v2y) {
125        return v1x * v2y - v1y * v2x;
126    }
127
128    public static float radians(float degrees) {
129        return degrees * DEG_TO_RAD;
130    }
131
132    public static float degrees(float radians) {
133        return radians * RAD_TO_DEG;
134    }
135
136    public static float acos(float value) {
137        return (float) Math.acos(value);
138    }
139
140    public static float asin(float value) {
141        return (float) Math.asin(value);
142    }
143
144    public static float atan(float value) {
145        return (float) Math.atan(value);
146    }
147
148    public static float atan2(float a, float b) {
149        return (float) Math.atan2(a, b);
150    }
151
152    public static float tan(float angle) {
153        return (float) Math.tan(angle);
154    }
155
156    public static float lerp(float start, float stop, float amount) {
157        return start + (stop - start) * amount;
158    }
159
160    /**
161     * Returns an interpolated angle in degrees between a set of start and end
162     * angles.
163     * <p>
164     * Unlike {@link #lerp(float, float, float)}, the direction and distance of
165     * travel is determined by the shortest angle between the start and end
166     * angles. For example, if the starting angle is 0 and the ending angle is
167     * 350, then the interpolated angle will be in the range [0,-10] rather
168     * than [0,350].
169     *
170     * @param start the starting angle in degrees
171     * @param end the ending angle in degrees
172     * @param amount the position between start and end in the range [0,1]
173     *               where 0 is the starting angle and 1 is the ending angle
174     * @return the interpolated angle in degrees
175     */
176    public static float lerpDeg(float start, float end, float amount) {
177        final float minAngle = (((end - start) + 180) % 360) - 180;
178        return minAngle * amount + start;
179    }
180
181    public static float norm(float start, float stop, float value) {
182        return (value - start) / (stop - start);
183    }
184
185    public static float map(float minStart, float minStop, float maxStart, float maxStop, float value) {
186        return maxStart + (maxStop - maxStart) * ((value - minStart) / (minStop - minStart));
187    }
188
189    /**
190     * Returns the sum of the two parameters, or throws an exception if the resulting sum would
191     * cause an overflow or underflow.
192     * @throws IllegalArgumentException when overflow or underflow would occur.
193     */
194    public static int addOrThrow(int a, int b) throws IllegalArgumentException {
195        if (b == 0) {
196            return a;
197        }
198
199        if (b > 0 && a <= (Integer.MAX_VALUE - b)) {
200            return a + b;
201        }
202
203        if (b < 0 && a >= (Integer.MIN_VALUE - b)) {
204            return a + b;
205        }
206        throw new IllegalArgumentException("Addition overflow: " + a + " + " + b);
207    }
208}
209