Math module

build.gradle

@@ -11,7 +11,7 @@ plugins {
 
 allprojects {
     group = "com.dumbdogdiner"
-    version = "3.0.2"
+    version = "3.1.0"
 
     // java plugin is applied in subprojects
     apply plugin: "jacoco"

bukkit/src/main/java/com/dumbdogdiner/stickyapi/bukkit/util/LocationUtil.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2020-2021 DumbDogDiner <dumbdogdiner.com>. All rights reserved.
+ * Licensed under the MIT license, see LICENSE for more information...
+ */
+package com.dumbdogdiner.stickyapi.bukkit.util;
+
+import com.dumbdogdiner.stickyapi.math.vector.Vector3;
+import org.bukkit.Location;
+import org.bukkit.World;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Utilities for converting {@link Vector3}s into Bukkit's {@link Location} object.
+ */
+public final class LocationUtil {
+	private LocationUtil() {}
+
+	/**
+	 * Convert the target {@link Vector3} into a Bukkit {@link Location}.
+	 * @param world The world this location should be contained in
+	 * @param vector The target vector
+	 * @return A new {@link Location} in the target world.
+	 */
+	public static @NotNull Location toLocation(@NotNull World world, @NotNull Vector3 vector) {
+		return new Location(world, vector.getX(), vector.getY(), vector.getZ());
+	}
+
+	/**
+	 * Convert the target {@link Location} into a {@link Vector3}.
+	 * @param location The target location
+	 * @return A new {@link Location} in the target world.
+	 */
+	public static @NotNull Vector3 toVector3(@NotNull Location location) {
+		return new Vector3(location.getX(), location.getY(), location.getZ());
+	}
+}

bukkit/src/main/java/com/dumbdogdiner/stickyapi/bukkit/util/PlayerSelector.java

@@ -4,7 +4,7 @@
  */
 package com.dumbdogdiner.stickyapi.bukkit.util;
 
-import com.dumbdogdiner.stickyapi.common.util.MathUtil;
+import com.dumbdogdiner.stickyapi.math.RandomUtil;
 import org.bukkit.Bukkit;
 import org.bukkit.GameMode;
 import org.bukkit.Location;
@@ -101,7 +101,7 @@ public static Predicate<Player> inRange(Location center, double radius) {
      */
     public static Player selectRandom(Predicate<Player> condition) {
         List<Player> list = selectPlayers(condition);
-        return list.get(MathUtil.randomInt(list.size()));
+        return RandomUtil.randomElement(list);
     }
 
     /**

common/build.gradle

@@ -9,6 +9,7 @@ plugins {
 dependencies {
     // Depend on the config project
     api project(":config") // api - transistively expose config dependency when implementing :common
+    api project(":math") // api - transistively expose api dependency when implementing :common
     testImplementation project(":config").sourceSets.test.output
 
     // LocaleProviderTest - add snakeyaml so YamlProvider (from the :config project) can work properly

common/src/main/java/com/dumbdogdiner/stickyapi/common/arguments/Arguments.java

@@ -12,9 +12,9 @@
 import java.util.List;
 
 import com.dumbdogdiner.stickyapi.common.util.Debugger;
-import com.dumbdogdiner.stickyapi.common.util.NumberUtil;
 import com.dumbdogdiner.stickyapi.common.util.TimeUtil;
 
+import com.dumbdogdiner.stickyapi.math.NumberUtil;
 import lombok.Getter;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -356,7 +356,7 @@ public Arguments requiredTimeString(@NotNull String name) {
 
     private Arguments optionalIntImplementation(@NotNull String name, @NotNull Integer fallback) {
         debug.print("Looking for optional integer " + name + "...");
-        if (unparsedArgs.size() > position && NumberUtil.isNumeric(unparsedArgs.get(position))) {
+        if (unparsedArgs.size() > position && NumberUtil.isInteger(unparsedArgs.get(position), false)) {
             parsedArgs.put(name, unparsedArgs.get(position));
             position++;
             debug.print("Found int at position " + String.valueOf(position) + " - new args size = "
@@ -405,7 +405,7 @@ public Arguments optionalInt(@NotNull String name, @NotNull Integer fallback) {
     public Arguments requiredInt(@NotNull String name) {
         debug.print("Looking for optional required " + name + "...");
 
-        if (unparsedArgs.size() > position && NumberUtil.isNumeric(unparsedArgs.get(position))) {
+        if (unparsedArgs.size() > position && NumberUtil.isInteger(unparsedArgs.get(position), false)) {
             parsedArgs.put(name, unparsedArgs.get(position));
             position++;
             debug.print("Found int at position " + String.valueOf(position) + " - new args size = "

common/src/main/java/com/dumbdogdiner/stickyapi/common/util/MathUtil.java

@@ -15,10 +15,10 @@
 import java.util.Random;
 
 /**
- * <p>
  * Util class for commonly used math operations.
- * </p>
+ * @deprecated in favor of the stickyapi:math module.
  */
+@Deprecated(since = "3.1")
 public class MathUtil {
     private MathUtil() {
     }

common/src/main/java/com/dumbdogdiner/stickyapi/common/util/NumberUtil.java

@@ -10,7 +10,9 @@
  * <p>
  * Provides extra functionality for Java Number classes.
  * </p>
- */
+ *  @deprecated in favor of the stickyapi:math module.
+*/
+@Deprecated(since = "3.1")
 public final class NumberUtil {
     private NumberUtil() {
     }

common/src/main/java/com/dumbdogdiner/stickyapi/common/util/StringUtil.java

@@ -9,6 +9,7 @@
 import java.util.Map;
 import java.util.UUID;
 
+import com.dumbdogdiner.stickyapi.math.RandomUtil;
 import com.google.common.base.Preconditions;
 
 import net.md_5.bungee.api.ChatColor;
@@ -333,16 +334,16 @@ public static String randomObfuscatedString(int min, int max, int minRunBeforeSp
         };
         StringBuilder obfuscated = new StringBuilder();
 
-        int len = MathUtil.randomInt(min, max);
+        int len = RandomUtil.randomInt(min, max);
         int charsSinceSpace = 0;
         while (obfuscated.length() < len) {
             if (minRunBeforeSpace > 0 && charsSinceSpace > minRunBeforeSpace &&
             // Set a 5% probability of the character being a space
-                    MathUtil.randomInt(1, 100) <= 5) {
+                    RandomUtil.probability(0.05)) {
                 obfuscated.append(' ');
                 charsSinceSpace = 0;
             } else {
-                obfuscated.append(MathUtil.randomElement(choices));
+                obfuscated.append(RandomUtil.randomElement(choices));
                 charsSinceSpace++;
             }
         }

common/src/main/java/com/dumbdogdiner/stickyapi/common/util/TimeUtil.java

@@ -12,6 +12,7 @@
 import java.util.List;
 import java.util.Optional;
 
+import com.dumbdogdiner.stickyapi.math.NumberUtil;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -286,7 +287,7 @@ public static Timestamp toTimestamp(@NotNull String timePeriod) {
             return null;
 
         // If it's numeric, lets do some extra checks!
-        if (NumberUtil.isNumeric(timePeriod)) {
+        if (NumberUtil.isInteger(timePeriod, false)) {
             // Return null if it's greater 12 characters long
             if (timePeriod.length() > 12)
                 return null;

common/src/test/java/com/dumbdogdiner/stickyapi/common/nbt/NbtNumberTagTest.java

@@ -4,15 +4,14 @@
  */
 package com.dumbdogdiner.stickyapi.common.nbt;
 
+import com.dumbdogdiner.stickyapi.math.RandomUtil;
 import com.google.gson.JsonPrimitive;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.RepeatedTest;
 import org.junit.jupiter.api.Test;
 
 import java.text.MessageFormat;
 
-import static com.dumbdogdiner.stickyapi.common.util.MathUtil.randomDouble;
-import static com.dumbdogdiner.stickyapi.common.util.MathUtil.randomInt;
 import static org.junit.jupiter.api.Assertions.*;
 import static org.junit.jupiter.api.Assumptions.*;
 
@@ -23,8 +22,8 @@ class NbtNumberTagTest {
 
     @BeforeEach
     public void setUp(){
-        i = randomInt(-256,  4096);
-        f = (float) randomDouble(-256, 8192);
+        i = RandomUtil.randomInt(-256,  4096);
+        f = (float) RandomUtil.randomDouble(-256, 8192);
     }
 
     @RepeatedTest(REPEAT)

math/README.md

@@ -0,0 +1,3 @@
+# stickyapi:math
+
+Provides a lightweight mathematics library for general purpose use.

math/build.gradle

@@ -0,0 +1,4 @@
+dependencies {
+    // TODO: Investigate why this isn't provided by common.
+    implementation "com.google.guava:guava:30.1.1-jre"
+}

math/lombok.config

@@ -0,0 +1,3 @@
+# This file is generated by the 'io.freefair.lombok' Gradle plugin
+config.stopBubbling = true
+lombok.addLombokGeneratedAnnotation = true

math/src/main/java/com/dumbdogdiner/stickyapi/math/Interpolation.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2020-2021 DumbDogDiner <dumbdogdiner.com>. All rights reserved.
+ * Licensed under the MIT license, see LICENSE for more information...
+ */
+package com.dumbdogdiner.stickyapi.math;
+
+import com.google.common.base.Preconditions;
+
+/**
+ * Utility class for interpolating between values.
+ * TODO: Inaccuracy issues for longs.
+ */
+public final class Interpolation {
+	private Interpolation() {}
+
+	/**
+	 * Clamp the value `t` between `min` and `max`.
+	 * @param max The minimum value
+	 * @param min The maximum value
+	 * @param t The value to clamp
+	 * @return The clamped value between `max` and `min`.
+	 */
+	public static double clamp(Number min, Number max, Number t) {
+		Preconditions.checkNotNull(min);
+		Preconditions.checkNotNull(max);
+		Preconditions.checkNotNull(t);
+		return Double.min(max.doubleValue(), Double.max(min.doubleValue(), t.doubleValue()));
+	}
+
+	/**
+	 * Linearly interpolate between a and b with time parameter t.
+	 * `t` is clamped between `0` and `1`.
+	 * @param a The first value
+	 * @param b The second value
+	 * @param t The time parameter
+	 * @return The linearly interpolated value between `a` and `b`.
+	 */
+	public static double lerp(Number a, Number b, Number t) {
+		return lerpUnclamped(a, b, clamp(0, 1, t));
+	}
+
+	/**s
+	 * Linearly interpolate between a and b with time parameter t.
+	 * `t` is not clamped between `0` and `1`.
+	 * @param a The first value
+	 * @param b The second value
+	 * @param t The time parameter
+	 * @return The linearly interpolated value.
+	 */
+	public static double lerpUnclamped(Number a, Number b, Number t) {
+		Preconditions.checkNotNull(a);
+		Preconditions.checkNotNull(b);
+		Preconditions.checkNotNull(t);
+		return b.doubleValue() * t.doubleValue() + (1 - t.doubleValue()) * a.doubleValue();
+	}
+
+	/**
+	 * Sinusoidaly interpolate between <code>a</code> and <code>b</code> with time parameter <code>t</code>.
+	 * @param a The first value
+	 * @param b The second value
+	 * @param t The time parameter
+	 * @return The sinusoidaly interpolated value.
+	 */
+	public static double sinusoidal(Number a, Number b, Number t) {
+		// calculate sinusoidal param
+		double param = Math.pow(Math.sin(t.doubleValue() * Math.PI / 2), 2);
+		return lerp(a, b, param);
+	}
+}