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