Package megamek.codeUtilities

Class MathUtility

java.lang.Object
megamek.codeUtilities.MathUtility
public class MathUtility extends Object

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    clamp(double value, double min, double max)
    Deprecated.
    Use the builtin Math.clamp() method instead.
    static float
    clamp(float value, float min, float max)
    Deprecated.
    Use the builtin Math.clamp() method instead.
    static int
    clamp(int value, int min, int max)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use the builtin Math.clamp() method instead.
    static long
    clamp(long value, long min, long max)
    Deprecated.
    Use the builtin Math.clamp() method instead.
    static double
    clamp01(double value)
     
    static double
    clampUlp1(double value)
    Clamps a double value between the limits of Math.ulp(1.0) and 1.0.
    static int
    getGaussianAverage(List<Integer> values)
    This is a convenience method for calling getGaussianAverage(List, double) with a strictness of 1.0 (neutral).
    static int
    getGaussianAverage(List<Integer> values, double strictness)
    Calculates a Gaussian-weighted average from a list of integer values.
    static double
    lerp(double min, double max, double factor)
     
    static float
    lerp(float min, float max, float factor)
     
    static int
    lerp(int min, int max, double factor)
     
    static long
    lerp(long min, long max, double factor)
     
    static boolean
    parseBoolean(String value)
    Parses a string into a boolean, returning false when the input is null or empty.
    static boolean
    parseBoolean(String value, boolean defaultValue)
    Utility function to handle parsing strings into boolean and to handle the possible NumberFormatException with logging and to return defaultValue.
    static double
    parseDouble(String value)
    Parses the provided string into a double.
    static Double
    parseDouble(String value, Double defaultValue)
    Utility function to handle parsing strings into Doubles and to handle the possible NumberFormatException with logging and to return defaultValue.
    static float
    parseFloat(String value, float defaultValue)
    Utility function to handle parsing strings into floats and to handle the possible NumberFormatException with logging and to return defaultValue.
    static int
    parseInt(String value)
    Attempts to parse the provided string into an integer.
    static int
    parseInt(String value, int defaultValue)
    Utility function to handle parsing strings into Integers and to handle the possible NumberFormatException with logging and to return defaultValue.
    static long
    parseLong(String value, long defaultValue)
    Utility function to handle parsing strings into Integers and to handle the possible NumberFormatException with logging and to return defaultValue.
    static int
    roundAwayFromZero(double value)
    Rounds a double value away from zero ("up" for both positive and negative values).
    static int
    roundTowardsZero(double value)
    Rounds a double value toward zero ("down" for both positive and negative values).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • roundAwayFromZero

      public static int roundAwayFromZero(double value)
      Rounds a double value away from zero ("up" for both positive and negative values).

      For positive values, this method returns the least integer greater than or equal to the value. For negative values, it returns the greatest integer less than or equal to the value (i.e., rounds further away from zero).

      Special cases:

      Parameters:
      value - The double value to round.
      Returns:
      The rounded integer value, away from zero.
      Since:
      0.50.10

    • roundTowardsZero

      public static int roundTowardsZero(double value)
      Rounds a double value toward zero ("down" for both positive and negative values).

      For positive values, this method returns the greatest integer less than or equal to the value. For negative values, it returns the least integer greater than or equal to the value (i.e., rounds closer to zero).

      Special cases:

      Parameters:
      value - The double value to round.
      Returns:
      The rounded integer value, toward zero.
      Since:
      0.50.10

    • getGaussianAverage

      public static int getGaussianAverage(List<Integer> values)
      This is a convenience method for calling getGaussianAverage(List, double) with a strictness of 1.0 (neutral).
      Parameters:
      values - the list of integer values to average; must not be null
      Returns:
      the Gaussian-weighted average as an int, or 0 if the list is empty
      Since:
      0.50.10

    • getGaussianAverage

      public static int getGaussianAverage(List<Integer> values, double strictness)
      Calculates a Gaussian-weighted average from a list of integer values.

      This method computes a "soft" average that down-weights statistical outliers using a Gaussian (normal-distribution) weighting function. This is useful when a handful of extreme values should not influence the final result as strongly as values clustered near the center of the distribution.

      How It Works

      1. Compute the arithmetic mean of all values.
      2. Compute the standard deviation. This measures how far values typically lie from the mean.
      3. If the standard deviation is zero (all values identical), simply return the mean. This avoids a divide-by-zero error when standardizing distances.
      4. Apply a configurable strictness factor to the standard deviation. Values less than 1.0 increase strictness by shrinking the effective deviation (causing outliers to be down-weighted more aggressively). Values greater than 1.0 reduce strictness.
      5. For each value, compute its standardized distance from the mean and apply a Gaussian weighting function: weight = exp( -0.5 * ((value - mean) / adjustedDeviation)^2). Values closer to the mean receive weights near 1.0, while more distant values rapidly approach zero weight.
      6. Return the ratio of the weighted sum of values to the total weight.

      The result behaves like a robust average: representative values dominate the calculation, while extreme outliers exert proportionally less influence. This is especially useful when working with mixed-force Battle Value (BV) or unit count arrays where unusually large or unusually small BVs/counts should not skew budgeting logic.

      Strictness Guidelines

      • strictness < 1.0: more strict; outliers are strongly suppressed.
      • strictness = 1.0: neutral; standard Gaussian weighting (default).
      • strictness > 1.0: less strict; outliers retain more influence.

      The strictness value should rarely be set below 0.5 or above 2.0. The default of 1.0 should work well for most distributions.

      To protect against overflow during conversion to int, the final result is clamped within Integer.MIN_VALUE and Integer.MIN_VALUE using clamp(int, int, int).

      Parameters:
      values - the list of integer values to average; must not be null
      strictness - how strict the calculations should be. Used to increase or decrease the influence of outliers.
      Returns:
      the Gaussian-weighted average as an int, or 0 if the list is empty
      Since:
      0.50.10

    • lerp

      public static int lerp(int min, int max, double factor)
      Parameters:
      min - the minimum value
      max - the maximum value
      factor - location factor between the two points
      Returns:
      integer rounded graphical linear interpolation value between min and max. A factor of 0d will return the minimum, a factor of 1d will return the maximum. Otherwise, this will return the rounded integer between the two points

    • lerp

      public static double lerp(double min, double max, double factor)
      Parameters:
      min - the minimum value
      max - the maximum value
      factor - location factor between the two points
      Returns:
      double graphical linear interpolation value between min and max. A factor of 0d will return the minimum, a factor of 1d will return the maximum. Otherwise, this will return the double value between the two points

    • lerp

      public static float lerp(float min, float max, float factor)
      Parameters:
      min - the minimum value
      max - the maximum value
      factor - location factor between the two points
      Returns:
      float graphical linear interpolation value between min and max. A factor of 0f will return the minimum, a factor of 1f will return the maximum. Otherwise, this will return the float value between the two points

    • lerp

      public static long lerp(long min, long max, double factor)
      Parameters:
      min - the minimum value
      max - the maximum value
      factor - location factor between the two points
      Returns:
      long rounded graphical linear interpolation value between min and max. A factor of 0d will return the minimum, a factor of 1d will return the maximum. Otherwise, this will return the rounded long between the two points

    • clamp

      @Deprecated(since="0.51.0", forRemoval=true) public static int clamp(int value, int min, int max)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use the builtin Math.clamp() method instead.
      Parameters:
      value - the int value to clamp
      min - the minimum limit
      max - the maximum limit
      Returns:
      The value if it is inside the range given by the limits (inclusive); the min value if value is below that range and the max value if value is above that range.
      • clamp(2, 6, 8) returns 6
      • clamp(7, 6, 8) returns 7
      • clamp(12, 3, 5) returns 5

    • clamp

      public static double clamp(double value, double min, double max)
      Deprecated.
      Use the builtin Math.clamp() method instead.
      Parameters:
      value - the double value to clamp
      min - the minimum limit
      max - the maximum limit
      Returns:
      The value if it is inside the range given by the limits (inclusive); the min value if value is below that range and the max value if value is above that range.
      • clamp(2, 6, 8) returns 6
      • clamp(7, 6, 8) returns 7
      • clamp(12, 3, 5) returns 5

    • clamp

      public static float clamp(float value, float min, float max)
      Deprecated.
      Use the builtin Math.clamp() method instead.
      Parameters:
      value - the float value to clamp
      min - the minimum limit
      max - the maximum limit
      Returns:
      The value if it is inside the range given by the limits (inclusive); the min value if value is below that range and the max value if value is above that range.
      • clamp(2, 6, 8) returns 6
      • clamp(7, 6, 8) returns 7
      • clamp(12, 3, 5) returns 5

    • clamp

      public static long clamp(long value, long min, long max)
      Deprecated.
      Use the builtin Math.clamp() method instead.
      Parameters:
      value - the long value to clamp
      min - the minimum limit
      max - the maximum limit
      Returns:
      The value if it is inside the range given by the limits (inclusive); the min value if value is below that range and the max value if value is above that range.
      • clamp(2, 6, 8) returns 6
      • clamp(7, 6, 8) returns 7
      • clamp(12, 3, 5) returns 5

    • clamp01

      public static double clamp01(double value)
      Parameters:
      value - the long value to clamp
      Returns:
      The value if it is inside the range given by the limits 0.0-1.0 (inclusive); the min value if value is below that range and the max value if value is above that range.
      • clamp01(1.3) returns 1.0
      • clamp01(0.3) returns 0.3
      • clamp01(-5) returns 0

    • clampUlp1

      public static double clampUlp1(double value)
      Clamps a double value between the limits of Math.ulp(1.0) and 1.0. Math.ulp is the smallest positive double value that is greater than 0.0.
      Parameters:
      value - the double value to clamp between Math.ulp(1.0) and 1.0
      Returns:
      The value if it is inside the range given by the limits (inclusive); the min value if value is below that range and the max value if value is above that range.
      • clamp(0.3) returns 0.3
      • clamp(7) returns 1
      • clamp(-4) returns 2.220446049250313E-16

    • parseInt

      public static int parseInt(String value, int defaultValue)
      Utility function to handle parsing strings into Integers and to handle the possible NumberFormatException with logging and to return defaultValue.
      Parameters:
      value - String value to parse.
      defaultValue - Default value to set if failed to parse.
      Returns:
      The int value or defaultValue.

    • parseInt

      public static int parseInt(String value)
      Attempts to parse the provided string into an integer.

      If parsing fails, the method defaults to returning 0. To specify a custom default value in case of failure, use the overloaded parseInt(String, int) method.

      Parameters:
      value - The string to parse. Can be a numeric string or null.
      Returns:
      The integer value parsed from the string, or 0 if parsing fails.
      See Also:

    • parseLong

      public static long parseLong(String value, long defaultValue)
      Utility function to handle parsing strings into Integers and to handle the possible NumberFormatException with logging and to return defaultValue.
      Parameters:
      value - String value to parse.
      defaultValue - Default value to set if failed to parse.
      Returns:
      The int value or defaultValue.

    • parseDouble

      public static Double parseDouble(String value, Double defaultValue)
      Utility function to handle parsing strings into Doubles and to handle the possible NumberFormatException with logging and to return defaultValue.
      Parameters:
      value - String value to parse.
      defaultValue - Default value to set if failed to parse.
      Returns:
      The double value or defaultValue.

    • parseDouble

      public static double parseDouble(String value)
      Parses the provided string into a double. If parsing fails, a default value of 0.0 is returned. This method delegates to parseDouble(String, Double) with a default value.
      Parameters:
      value - the string to parse. Can be a numeric string or null.
      Returns:
      the parsed double value, or 0.0 if parsing fails.
      Since:
      0.50.07

    • parseFloat

      public static float parseFloat(String value, float defaultValue)
      Utility function to handle parsing strings into floats and to handle the possible NumberFormatException with logging and to return defaultValue.
      Parameters:
      value - String value to parse.
      defaultValue - Default value to set if failed to parse.
      Returns:
      The float value or defaultValue.

    • parseBoolean

      public static boolean parseBoolean(String value, boolean defaultValue)
      Utility function to handle parsing strings into boolean and to handle the possible NumberFormatException with logging and to return defaultValue.
      Parameters:
      value - String value to parse.
      defaultValue - Default value to set if failed to parse.
      Returns:
      The boolean value or defaultValue.

    • parseBoolean

      public static boolean parseBoolean(String value)
      Parses a string into a boolean, returning false when the input is null or empty.

      Note: Boolean.parseBoolean(String) returns true only for (case-insensitive) "true".

      Parameters:
      value - String value to parse.
      Returns:
      The boolean value, or false if value is null or empty.