Google Guava与原生类型操作相关的类

Primitives：JDK未提供对基本类型（如int和char）的操作，包括某些类型的无符号变体。

1.概述

Java的原生类型是基本类型：byte、short、int、long、float、double、char、boolean。

在搜索Guava中的方法之前，你应该检查它是在Arrays数组中还是在对应的JDK包装器类型中，例如Integer 。

这些原生类型不能用作对象或泛型类型的类型参数，这意味着许多通用工具不能应用于它们。Guava提供了许多这样的通用工具，原生数组与集合API之间的接口方式、从类型到字节数组表示的转换以及对某些类型的无符号行为的支持。

原生类型	Guava工具(都在com.google.common.primitives包)
byte	Bytes, SignedBytes, UnsignedBytes
short	Shorts
int	Ints, UnsignedInteger, UnsignedInts
long	Longs, UnsignedLong, UnsignedLongs
float	Floats
double	Doubles
char	Chars
boolean	Booleans

对于有符号和无符号字节的行为不同的方法在Bytes中被完全跳过，但仅存在于SignedBytes和UnsignedBytes工具中，因为字节的有符号性比其他类型的有符号性更含糊。

在UnsignedInts和UnsignedLongs类中提供了int和long方法的无符号变体，但是由于这些类型的大多数用法都是有符号的，因此Ints和Longs类将其输入视为有符号的。

此外，Guava为无符号的int和long值提供了“包装器类型”UnsignedInteger和UnsignedLong，以帮助你使用类型系统在有符号和无符号值之间进行强制区分，以换取较低的性能成本。这些类直接支持BigInteger样式的简单算术运算。

所有方法签名都使用Wrapper引用相应的JDK包装器类型，并使用prim引用原生类型。（Prims，在适用的情况下是指相应的Guava工具类。）

2.原生数组工具

原生数组是聚合处理原生类型的最有效方法（在内存和性能方面）。 Guava提供了多种工具来使用这些方法。

方法签名	描述	类似集合	可用性
List asList(prim... backingArray)	将原生数组包装为相应包装器类型的List。	Arrays.asList	符号无关*
prim[] toArray(Collection collection)	将集合复制到新的prim[]中。此方法与collection.toArray()一样是线程安全的。	Collection.toArray()	符号无关
prim[] concat(prim[]... arrays)	连接多个原生数组。	Iterables.concat	符号无关
boolean contains(prim[] array, prim target)	确定指定的元素是否在指定的数组中。	Collection.contains	符号无关
int indexOf(prim[] array, prim target)	查找array中target值首次出现的索引，如果不存在该值，则返回-1。	List.indexOf	符号无关
int lastIndexOf(prim[] array, prim target)	查找array中target值最后一次出现的索引，如果不存在该值，则返回-1。	List.lastIndexOf	符号无关
prim min(prim... array)	返回数组的最小元素。	Collections.min	符号相关**
prim max(prim... array)	返回数组的最大元素。	Collections.max	符号相关
String join(String separator, prim... array)	构造一个包含array元素的字符串，用separator分隔。	Joiner.on(separator).join	符号相关
Comparator lexicographicalComparator()	按字典顺序比较原生数组的比较器。	Ordering.natural().lexicographical()	符号相关

*与符号无关的方法存在于：Bytes、Shorts、Ints、Longs、Floats、Doubles、Chars、Booleans。不包括UnsignedInts、UnsignedLongs、SignedBytes或UnsignedBytes。

**与符号相关的方法存在于： SignedBytes、UnsignedBytes、Shorts、Ints、Longs、Floats、Doubles、Chars、Booleans、UnsignedInts、UnsignedLongs。不包括Bytes。

3.通用工具方法

Guava提供了许多JDK 6都不包含的基本工具。然而，其中一些方法在JDK 7中可用。

方法签名	描述	可用性
int compare(prim a, prim b)	在原生类型上使用传统的Comparator.compare方法。从JDK 7开始在JDK包装器类中提供。	符号相关
prim checkedCast(long value)	将指定的值强制转换为prim，除非指定的值不符合prim，在这种情况下将抛出IllegalArgumentException。	仅与符号有关的整数类型*
prim saturatedCast(long value)	将指定的值强制转换为prim，除非指定的值不符合prim，在这种情况下使用最接近的prim值。	仅与符号有关的整数类型

*这里的整数类型包括byte，short，int，long。整数类型不包括char，boolean，float或double。

注意：com.google.common.math.DoubleMath提供了从double四舍五入的功能，并且支持多种四舍五入模式。有关详细信息，请参见MathExplained 。

4.字节转换方法

Guava提供了按大字节序顺序将原生类型与字节数组表示形式相互转换的方法。除了布尔值不提供这些方法外，所有方法均与符号无关。

方法签名	描述
int BYTES	表示prim值所需的字节数的常量表示。
prim fromByteArray(byte[] bytes)	返回大字节序表示的bytes数组中第一个Prims.BYTES字节的prim值。如果bytes.length <= Prims.BYTES则抛出IllegalArgumentException。
prim fromBytes(byte b1, ..., byte bk)	采用Prims.BYTES字节参数。返回prim值，其字节表示为按大字节序顺序指定的字节。
byte[] toByteArray(prim value)	返回包含大字节序表示形式的value值的数组。

5.无符号支持

UnsignedInts和UnsignedLongs工具类提供了Java在其包装类中的签名类型提供的一些通用工具。UnsignedInts和UnsignedLongs直接处理原生类型：由你来确保仅将无符号值传递给这些工具。

此外，对于int和long而言，Guava提供了“无符号”包装器类型（UnsignedInteger和UnsignedLong），以帮助你在类型系统中强制区分无符号和有符号值，以换取较低的性能成本。

5.1通用工具

这些方法的有符号形式类似提供在JDK的包装器类。

方法签名	说明
int UnsignedInts.parseUnsignedInt(String) long UnsignedLongs.parseUnsignedLong(String)	从以10为基数（进制）的字符串中解析无符号值。
int UnsignedInts.parseUnsignedInt(String string, int radix) long UnsignedLongs.parseUnsignedLong(String string, int radix)	从指定基数（进制）的字符串中解析无符号值。
String UnsignedInts.toString(int) String UnsignedLongs.toString(long)	返回以10为基数（进制）的无符号值的字符串表示形式。
String UnsignedInts.toString(int value, int radix) String UnsignedLongs.toString(long value, int radix)	返回指定基数（进制）的无符号值的字符串表示形式。

5.2包装器

所提供的无符号包装器类型包括许多方法，以使其更容易使用和转换。

方法签名	说明
UnsignedPrim plus(UnsignedPrim), minus, times, dividedBy, mod	简单的算术运算。
UnsignedPrim valueOf(BigInteger)	以UnsignedPrim的形式返回BigInteger的值，如果指定的BigInteger为负数或不匹配，则抛出IAE。
UnsignedPrim valueOf(long)	以UnsignedPrim的形式返回long的值，如果指定的long为负数或不匹配，则抛出IAE。
UnsignedPrim fromPrimBits(prim value)	将给定的值视为无符号的。例如，UnsignedInteger.fromIntBits(1 << 31)的值为231，即使1 << 31作为int是负数。
BigInteger bigIntegerValue()	以BigInteger的形式获取此UnsignedPrim的值。
toString(), toString(int radix)	返回此无符号值的字符串表示形式。

本文参考:
PrimitivesExplained
guava-tests-primitives