feat: added mathematic calculators

num4j/build.gradle.kts

@@ -0,0 +1,19 @@
+plugins {
+    id("java")
+}
+
+group = "com.onixbyte"
+version = "unspecified"
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    testImplementation(platform("org.junit:junit-bom:5.10.0"))
+    testImplementation("org.junit.jupiter:junit-jupiter")
+}
+
+tasks.test {
+    useJUnitPlatform()
+}

num4j/src/main/java/com/onixbyte/nums/ChainedCalcUtil.java

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-package com.onixbyte.devkit.utils;
+package com.onixbyte.nums;
 
 import lombok.Getter;
 
@@ -87,7 +87,7 @@ import java.util.function.Function;
  *
  * @author sunzsh
  * @version 1.1.0
- * @see java.math.BigDecimal
+ * @see BigDecimal
  * @since 1.0.0
  */
 @Getter

num4j/src/main/java/com/onixbyte/nums/PercentileCalculator.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright (C) 2024 OnixByte.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.onixbyte.nums;
+
+import com.onixbyte.nums.model.QuartileBounds;
+
+import java.util.List;
+
+/**
+ * Percentile calculator.
+ *
+ * @author zihluwang
+ * @version 1.7.0
+ * @since 1.7.0
+ */
+public final class PercentileCalculator {
+
+    public static Double calculatePercentile(List<Double> values, Double percentile) {
+        var sorted = values.stream().sorted().toList();
+        if (sorted.isEmpty()) {
+            throw new IllegalArgumentException("Unable to sort an empty list.");
+        }
+
+        var rank = percentile / 100. * (sorted.size() - 1);
+        var lowerIndex = ((int) Math.floor(rank));
+        var upperIndex = ((int) Math.ceil(rank));
+        var weight = rank - lowerIndex;
+
+        return sorted.get(lowerIndex) * (1 - weight) + sorted.get(upperIndex) * weight;
+    }
+
+    public static QuartileBounds calculatePercentileBounds(List<Double> data) {
+        var sorted = data.stream().sorted().toList();
+        var Q1 = calculatePercentile(sorted, 25.);
+        var Q3 = calculatePercentile(sorted, 75.);
+
+        var IQR = Q3 - Q1;
+
+        var lowerBound = Q1 - 1.5 * IQR;
+        var upperBound = Q3 + 1.5 * IQR;
+
+        return QuartileBounds.builder()
+                .upperBound(upperBound)
+                .lowerBound(lowerBound)
+                .build();
+    }
+
+}

num4j/src/main/java/com/onixbyte/nums/model/QuartileBounds.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright (C) 2024-2024 OnixByte.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.onixbyte.nums.model;
+
+/**
+ * QuartileBound.
+ *
+ * @param upperBound
+ * @param lowerBound
+ * @author zihluwang
+ */
+public record QuartileBounds(
+        Double upperBound,
+        Double lowerBound
+) {
+
+    /**
+     * Get a builder for {@link QuartileBounds}.
+     *
+     * @return a builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static class Builder {
+        private Double upperBound;
+        private Double lowerBound;
+
+        private Builder() {
+        }
+
+        public Builder upperBound(Double upperBound) {
+            this.upperBound = upperBound;
+            return this;
+        }
+
+        public Builder lowerBound(Double lowerBound) {
+            this.lowerBound = lowerBound;
+            return this;
+        }
+
+        public QuartileBounds build() {
+            return new QuartileBounds(upperBound, lowerBound);
+        }
+    }
+
+}

settings.gradle.kts

@@ -28,3 +28,4 @@ include(
     "simple-jwt-spring-boot-starter",
     "property-guard-spring-boot-starter"
 )
+include("num4j")