Guide to Mathematical Utilities in Guava – Guava中的数学实用程序指南

1. Overview

1.概述

In this article, we will see some useful Mathematical Operations available in the Guava Library.

在这篇文章中，我们将看到Guava库中一些有用的数学运算。

There are four maths utility classes available with Guava:

Guava有四个数学实用类。

1. IntMath – operation on int values
2. LongMath – operations on long values
3. BigIntegerMath – operations on BigIntegers
4. DoubleMath – operations on double values

2. IntMath Utility

2.IntMath实用程序

IntMath is used to perform mathematical operations on Integer values. We’ll go through the available method list explaining each of their behavior.

IntMath是用来对整数值进行数学运算的。我们将通过可用的方法列表，解释它们的每一个行为。

2.1. binomial(int n, int k)

2.1.二项式(int n, int k)

This function calculates the binomial coefficient of n and k. It makes sure that the result is within the integer range. Otherwise, it gives the Integer.MAX_VALUE. The answer can be derived using the formula n/k(n-k):

这个函数计算n和k的二项式系数。它确保结果在整数范围内。否则，它给出Integer.MAX_VALUE。答案可以用公式n/k(n-k)得出。

@Test
public void whenBinomialOnTwoInt_shouldReturnResultIfUnderInt() {
    int result = IntMath.binomial(6, 3);
 
    assertEquals(20, result);
}

@Test
public void whenBinomialOnTwoInt_shouldReturnIntMaxIfOVerflowInt() {
    int result = IntMath.binomial(Integer.MAX_VALUE, 3);
 
    assertEquals(Integer.MAX_VALUE, result);
}

2.2. ceilingPowerOfTwo(int x)

2.2.ceilingPowerOfTwo(int x)

This calculates the value of the smallest power of two which is greater than or equal to x. The result n is such that 2^(n-1) < x < 2 ^n:

这将计算大于或等于x的最小2次方的值，其结果n是这样的：2^(n-1) < x < 2 ^n:

@Test
public void whenCeilPowOfTwoInt_shouldReturnResult() {
  int result = IntMath.ceilingPowerOfTwo(20);
 
  assertEquals(32, result);
}

2.3. checkedAdd(int a, int b) and Others

2.3.checkedAdd(int a, int b) 和其他

This function calculates the sum of the two parameters. This one provides an additional check which Throws ArithmeticException if the result overflows:

这个函数计算两个参数的总和。这个函数提供了一个额外的检查，如果结果溢出，会抛出ArithmeticException。

@Test
public void whenAddTwoInt_shouldReturnTheSumIfNotOverflow() {
    int result = IntMath.checkedAdd(1, 2);
 
    assertEquals(3, result);
}

@Test(expected = ArithmeticException.class)
public void whenAddTwoInt_shouldThrowArithmeticExceptionIfOverflow() {
    IntMath.checkedAdd(Integer.MAX_VALUE, 100);
}

Guava has checked methods for three other operators which can overflow: checkedMultiply, checkedPow, and checkedSubtract.

Guava为其他三个可能溢出的运算符提供了检查方法。checkedMultiply, checkedPow, 和checkedSubtract。

2.4. divide(int p, int q, RoundingMode mode)

2.4.divide(int p, int q, RoundingMode mode)

This is a simple divide but allows us to define a rounding mode:

这是一个简单的除法，但允许我们定义一个四舍五入的模式。

@Test
public void whenDivideTwoInt_shouldReturnTheResultForCeilingRounding() {
    int result = IntMath.divide(10, 3, RoundingMode.CEILING);
 
    assertEquals(4, result);
}
    
@Test(expected = ArithmeticException.class)
public void whenDivideTwoInt_shouldThrowArithmeticExIfRoundNotDefinedButNeeded() {
    IntMath.divide(10, 3, RoundingMode.UNNECESSARY);
}

2.5. factorial(int n)

2.5.因子(int n)

Calculates the factorial value of n. i.e the product of the first n positive integers. Returns 1 if n = 0 and returns Integer.MAX_VALUE if the result does not fit in for int range. The result can be obtained by n x (n-1) x (n-2) x ….. x 2 x 1:

计算n的阶乘值，即前n个正整数的乘积。如果n=0则返回1，如果结果不符合int范围则返回Integer.MAX_VALUE。结果可以通过n x (n-1) x (n-2) x ….. x 2 x 1得到。

@Test
public void whenFactorialInt_shouldReturnTheResultIfInIntRange() {
    int result = IntMath.factorial(5);
 
    assertEquals(120, result);
}

@Test
public void whenFactorialInt_shouldReturnIntMaxIfNotInIntRange() {
    int result = IntMath.factorial(Integer.MAX_VALUE);
 
    assertEquals(Integer.MAX_VALUE, result);
}

2.6. floorPowerOfTwo(int x)

2.6.floorPowerOfTwo(int x)

Returns the largest power of two, of which the results is less than or equal to x. The result n is such that 2^n < x < 2 ^(n+1):

返回2的最大幂，其中的结果小于或等于x。结果n是这样的：2^n < x < 2 ^(n+1)。

@Test
public void whenFloorPowerOfInt_shouldReturnValue() {
    int result = IntMath.floorPowerOfTwo(30);
 
    assertEquals(16, result);
}

2.7. gcd(int a, int b)

2.7.gcd(int a, int b)

This function gives us the greatest common divisor of a and b:

这个函数给了我们a和b的最大公除数。

@Test
public void whenGcdOfTwoInt_shouldReturnValue() {
    int result = IntMath.gcd(30, 40);
    assertEquals(10, result);
}

2.8. isPowerOfTwo(int x)

2.8.isPowerOfTwo(int x)

Returns whether x is a power of two or not. Returns true if the value is a power of two and false otherwise:

返回x是否为2的幂。如果该值是2的幂，则返回true，否则返回false。

@Test
public void givenIntOfPowerTwo_whenIsPowOfTwo_shouldReturnTrue() {
    boolean result = IntMath.isPowerOfTwo(16);
 
    assertTrue(result);
}

@Test
public void givenIntNotOfPowerTwo_whenIsPowOfTwo_shouldReturnFalse() {
    boolean result = IntMath.isPowerOfTwo(20);
 
    assertFalse(result);
}

2.9. isPrime(int n)

2.9.isPrime(int n)

This function will tell us if the number passed is prime or not:

这个函数将告诉我们所传递的数字是否是质数。

@Test
public void givenNonPrimeInt_whenIsPrime_shouldReturnFalse() {
    boolean result = IntMath.isPrime(20);
 
    assertFalse(result);
}

2.10. log10(int x, RoundingMode mode)

2.10.log10(int x, RoundingMode mode)

This API calculates the base-10 logarithm of the given number. The result is rounded using the provided rounding mode:

这个API计算给定数字的10进制对数。计算结果将使用所提供的四舍五入模式。

@Test
public void whenLog10Int_shouldReturnTheResultForCeilingRounding() {
    int result = IntMath.log10(30, RoundingMode.CEILING);
 
    assertEquals(2, result);
}

@Test(expected = ArithmeticException.class)
public void whenLog10Int_shouldThrowArithmeticExIfRoundNotDefinedButNeeded() {
    IntMath.log10(30, RoundingMode.UNNECESSARY);
}

2.11. log2(int x, RoundingMode mode)

2.11.log2(int x, RoundingMode mode)

Returns the base-2 logarithm of the given number. The result is rounded using the provided rounding mode:

返回给定数字的以2为基数的对数。结果是使用所提供的四舍五入模式进行四舍五入。

@Test
public void whenLog2Int_shouldReturnTheResultForCeilingRounding() {
    int result = IntMath.log2(30, RoundingMode.CEILING);
 
    assertEquals(5, result);
}

@Test(expected = ArithmeticException.class)
public void whenLog2Int_shouldThrowArithmeticExIfRoundNotDefinedButNeeded() {
    IntMath.log2(30, RoundingMode.UNNECESSARY);
}

2.12. mean(int x, int y)

2.12.mean（int x，int y）

With this function we can calculate the mean of two values:

通过这个函数，我们可以计算出两个值的平均值。

@Test
public void whenMeanTwoInt_shouldReturnTheResult() {
    int result = IntMath.mean(30, 20);
 
    assertEquals(25, result);
}

2.13. mod(int x, int m)

2.13.mod(int x, int m)

Returns the remainder of integer division of one number by the other:

返回一个数字除以另一个数字的整数余数。

@Test
public void whenModTwoInt_shouldReturnTheResult() {
    int result = IntMath.mod(30, 4);
    assertEquals(2, result);
}

2.14. pow(int b, int k)

2.14.pow(int b, int k)

Returns the value of b to the power of k:

返回b的值到k的幂。

@Test
public void whenPowTwoInt_shouldReturnTheResult() {
    int result = IntMath.pow(6, 4);
 
    assertEquals(1296, result);
}

2.15. saturatedAdd(int a, int b) and Others

2.15.saturatedAdd(int a, int b)和其他

A sum function with the benefit of controlling any overflows or underflows by returning the value Integer.MAX_VALUE or Integer.MIN_VALUE respectively when it occurs:

一个和函数，其好处是在发生溢出或溢出时分别返回Integer.MAX_VALUE或Integer.MIN_VALUE的值来控制任何溢出或溢出不足。

@Test:
public void whenSaturatedAddTwoInt_shouldReturnTheResult() {
    int result = IntMath.saturatedAdd(6, 4);
 
    assertEquals(10, result);
}

@Test
public void whenSaturatedAddTwoInt_shouldReturnIntMaxIfOverflow() {
    int result = IntMath.saturatedAdd(Integer.MAX_VALUE, 1000);
 
    assertEquals(Integer.MAX_VALUE, result);
}

There are three other saturated APIs: saturatedMultiply, saturatedPow and saturatedSubtract.

还有三个饱和的API。saturatedMultiply, saturatedPow和saturatedSubtract。

2.16. sqrt(int x, RoundingMode mode)

2.16.sqrt(int x, RoundingMode mode)

Returns the square root of the given number. The result is rounded using the provided rounding mode:

返回给定数字的平方根。结果是使用所提供的四舍五入模式进行四舍五入。

@Test
public void whenSqrtInt_shouldReturnTheResultForCeilingRounding() {
    int result = IntMath.sqrt(30, RoundingMode.CEILING);
 
    assertEquals(6, result);
}

@Test(expected = ArithmeticException.class)
public void whenSqrtInt_shouldThrowArithmeticExIfRoundNotDefinedButNeded() {
    IntMath.sqrt(30, RoundingMode.UNNECESSARY);
}

3. LongMath Utility

3.LongMath实用程序

LongMath has utilities for Long values. Most operations are similar to the IntMath utility, with an exceptional few described here.

LongMath有用于Long值的实用程序。大多数操作与IntMath实用程序相似，只有少数例外的操作在此描述。

3.1. mod(long x, int m) and mod(long x, long m)

3.1.mod(long x, int m)和mod(long x, long m)

Returns the x mod m. The remainder of integer division of x by m:

返回x mod m.的余数，即x除以m的整数。

@Test
public void whenModLongAndInt_shouldModThemAndReturnTheResult() {
    int result = LongMath.mod(30L, 4);
 
    assertEquals(2, result);
}

@Test
public void whenModTwoLongValues_shouldModThemAndReturnTheResult() {
    long result = LongMath.mod(30L, 4L);
 
    assertEquals(2L, result);
}

4. BigIntegerMath Utility

4.BigIntegerMath实用程序

BigIntegerMath is used to perform mathematical operations on type BigInteger.

BigIntegerMath用于对BigInteger类型执行数学运算。

This utility has some methods similar to the IntMath.

这个工具有一些与IntMath.类似的方法。

5. DoubleMath Utility

5.DoubleMath实用程序

DoubleMath utility is used to perform an operation on double values.

DoubleMath工具用于对双倍值进行操作。

Similar to the BigInteger utility, the number of available operations is limited and share similarity with IntMath utility. We will list some exceptional functions available only to this utility class.

与BigInteger工具类似，可用的操作数量有限，与IntMath工具有相似之处。我们将列出一些只有这个实用程序类才有的特殊功能。

5.1. isMathematicalInteger(double x)

5.1.isMathematicalInteger(double x)

Returns whether x is a mathematical integer. It checks if the number can be represented as an integer without a data loss:

返回x是否是一个数学上的整数。它检查该数字是否可以被表示为一个整数而没有数据损失。

@Test
public void givenInt_whenMathematicalDouble_shouldReturnTrue() {
    boolean result = DoubleMath.isMathematicalInteger(5);
 
    assertTrue(result);
}

@Test
public void givenDouble_whenMathematicalInt_shouldReturnFalse() {
    boolean result = DoubleMath.isMathematicalInteger(5.2);
 
    assertFalse(result);
}

5.2. log2(double x)

5.2.log2(double x)

Calculates the base-2 logarithm of x:

计算x的以2为底的对数。

@Test
public void whenLog2Double_shouldReturnResult() {
    double result = DoubleMath.log2(4);
 
    assertEquals(2, result, 0);
}

6. Conclusion

6.结论

In this quick tutorial, we explored some useful Guava maths utility functions.

在这个快速教程中，我们探讨了一些有用的Guava数学实用函数。

As always, the source code can be found over on GitHub.

一如既往，源代码可以在GitHub上找到over。