@GwtCompatible(emulated=true) public final class Chars extends Object
char
primitives, that are not already found in
either Character
or Arrays
.
All the operations in this class treat char
values strictly numerically; they are
neither Unicode-aware nor locale-dependent.
See the Guava User Guide article on primitive utilities.
Modifier and Type | Field and Description |
---|---|
static int |
BYTES
The number of bytes required to represent a primitive
char value. |
Modifier and Type | Method and Description |
---|---|
static List<Character> |
asList(char... backingArray)
Returns a fixed-size list backed by the specified array, similar to
Arrays.asList(Object[]) . |
static char |
checkedCast(long value)
Returns the
char value that is equal to value , if possible. |
static int |
compare(char a,
char b)
Compares the two specified
char values. |
static char[] |
concat(char[]... arrays)
Returns the values from each provided array combined into a single array.
|
static char |
constrainToRange(char value,
char min,
char max)
Returns the value nearest to
value which is within the closed range [min..max] . |
static boolean |
contains(char[] array,
char target)
Returns
true if target is present as an element anywhere in array . |
static char[] |
ensureCapacity(char[] array,
int minLength,
int padding)
Returns an array containing the same values as
array , but guaranteed to be of a
specified minimum length. |
static char |
fromByteArray(byte[] bytes)
Returns the
char value whose big-endian representation is stored in the first 2 bytes
of bytes ; equivalent to ByteBuffer.wrap(bytes).getChar() . |
static char |
fromBytes(byte b1,
byte b2)
Returns the
char value whose byte representation is the given 2 bytes, in big-endian
order; equivalent to Chars.fromByteArray(new byte[] {b1, b2}) . |
static int |
hashCode(char value)
Returns a hash code for
value ; equal to the result of invoking
((Character) value).hashCode() . |
static int |
indexOf(char[] array,
char target)
Returns the index of the first appearance of the value
target in array . |
static int |
indexOf(char[] array,
char[] target)
Returns the start position of the first occurrence of the specified
target within array , or -1 if there is no such occurrence. |
static String |
join(String separator,
char... array)
Returns a string containing the supplied
char values separated by separator . |
static int |
lastIndexOf(char[] array,
char target)
Returns the index of the last appearance of the value
target in array . |
static Comparator<char[]> |
lexicographicalComparator()
Returns a comparator that compares two
char arrays lexicographically. |
static char |
max(char... array)
Returns the greatest value present in
array . |
static char |
min(char... array)
Returns the least value present in
array . |
static char |
saturatedCast(long value)
Returns the
char nearest in value to value . |
static char[] |
toArray(Collection<Character> collection)
Copies a collection of
Character instances into a new array of primitive char
values. |
static byte[] |
toByteArray(char value)
Returns a big-endian representation of
value in a 2-element byte array; equivalent to
ByteBuffer.allocate(2).putChar(value).array() . |
public static final int BYTES
char
value.
Java 8 users: use Character.BYTES
instead.
public static int hashCode(char value)
value
; equal to the result of invoking
((Character) value).hashCode()
.
Java 8 users: use Character.hashCode(char)
instead.
value
- a primitive char
valuepublic static char checkedCast(long value)
char
value that is equal to value
, if possible.value
- any value in the range of the char
typechar
value that equals value
IllegalArgumentException
- if value
is greater than Character.MAX_VALUE
or less than Character.MIN_VALUE
public static char saturatedCast(long value)
char
nearest in value to value
.value
- any long
valuechar
if it is in the range of the char
type,
Character.MAX_VALUE
if it is too large, or Character.MIN_VALUE
if it is too
smallpublic static int compare(char a, char b)
char
values. The sign of the value returned is the same as
that of ((Character) a).compareTo(b)
.
Note for Java 7 and later: this method should be treated as deprecated; use the
equivalent Character.compare(char, char)
method instead.
a
- the first char
to compareb
- the second char
to comparea
is less than b
; a positive value if a
is
greater than b
; or zero if they are equalpublic static boolean contains(char[] array, char target)
true
if target
is present as an element anywhere in array
.array
- an array of char
values, possibly emptytarget
- a primitive char
valuetrue
if array[i] == target
for some value of i
public static int indexOf(char[] array, char target)
target
in array
.array
- an array of char
values, possibly emptytarget
- a primitive char
valuei
for which array[i] == target
, or -1
if no
such index exists.public static int indexOf(char[] array, char[] target)
target
within array
, or -1
if there is no such occurrence.
More formally, returns the lowest index i
such that
Arrays.copyOfRange(array, i, i + target.length)
contains exactly the same elements as
target
.
array
- the array to search for the sequence target
target
- the array to search for as a sub-sequence of array
public static int lastIndexOf(char[] array, char target)
target
in array
.array
- an array of char
values, possibly emptytarget
- a primitive char
valuei
for which array[i] == target
, or -1
if no
such index exists.public static char min(char... array)
array
.array
- a nonempty array of char
valuesarray
that is less than or equal to every other value in
the arrayIllegalArgumentException
- if array
is emptypublic static char max(char... array)
array
.array
- a nonempty array of char
valuesarray
that is greater than or equal to every other value
in the arrayIllegalArgumentException
- if array
is empty@Beta public static char constrainToRange(char value, char min, char max)
value
which is within the closed range [min..max]
.
If value
is within the range [min..max]
, value
is returned
unchanged. If value
is less than min
, min
is returned, and if
value
is greater than max
, max
is returned.
value
- the char
value to constrainmin
- the lower bound (inclusive) of the range to constrain value
tomax
- the upper bound (inclusive) of the range to constrain value
toIllegalArgumentException
- if min > max
public static char[] concat(char[]... arrays)
concat(new char[] {a, b}, new char[] {}, new char[] {c}
returns the array
{a, b, c}
.arrays
- zero or more char
arrays@GwtIncompatible public static byte[] toByteArray(char value)
value
in a 2-element byte array; equivalent to
ByteBuffer.allocate(2).putChar(value).array()
. For example, the input value
'\\u5432'
would yield the byte array {0x54, 0x32}
.
If you need to convert and concatenate several values (possibly even of different types),
use a shared ByteBuffer
instance, or use
ByteStreams.newDataOutput()
to get a growable buffer.
@GwtIncompatible public static char fromByteArray(byte[] bytes)
char
value whose big-endian representation is stored in the first 2 bytes
of bytes
; equivalent to ByteBuffer.wrap(bytes).getChar()
. For example, the
input byte array {0x54, 0x32}
would yield the char
value '\\u5432'
.
Arguably, it's preferable to use ByteBuffer
; that library exposes much more
flexibility at little cost in readability.
IllegalArgumentException
- if bytes
has fewer than 2 elements@GwtIncompatible public static char fromBytes(byte b1, byte b2)
char
value whose byte representation is the given 2 bytes, in big-endian
order; equivalent to Chars.fromByteArray(new byte[] {b1, b2})
.public static char[] ensureCapacity(char[] array, int minLength, int padding)
array
, but guaranteed to be of a
specified minimum length. If array
already has a length of at least minLength
,
it is returned directly. Otherwise, a new array of size minLength + padding
is
returned, containing the values of array
, and zeroes in the remaining places.array
- the source arrayminLength
- the minimum length the returned array must guaranteepadding
- an extra amount to "grow" the array by if growth is necessaryarray
, with guaranteed minimum length
minLength
IllegalArgumentException
- if minLength
or padding
is negativepublic static String join(String separator, char... array)
char
values separated by separator
.
For example, join("-", '1', '2', '3')
returns the string "1-2-3"
.separator
- the text that should appear between consecutive values in the resulting string
(but not at the start or end)array
- an array of char
values, possibly emptypublic static Comparator<char[]> lexicographicalComparator()
char
arrays lexicographically. That is, it
compares, using compare(char, char)
), the first pair of values that follow any common
prefix, or when one array is a prefix of the other, treats the shorter array as the lesser. For
example, [] < ['a'] < ['a', 'b'] < ['b']
.
The returned comparator is inconsistent with Object.equals(Object)
(since arrays
support only identity equality), but it is consistent with
Arrays.equals(char[], char[])
.
public static char[] toArray(Collection<Character> collection)
Character
instances into a new array of primitive char
values.
Elements are copied from the argument collection as if by collection.toArray()
. Calling this method is as thread-safe as calling that method.
collection
- a collection of Character
objectscollection
, in the same order, converted
to primitivesNullPointerException
- if collection
or any of its elements is nullpublic static List<Character> asList(char... backingArray)
Arrays.asList(Object[])
. The list supports List.set(int, Object)
, but any
attempt to set a value to null
will result in a NullPointerException
.
The returned list maintains the values, but not the identities, of Character
objects
written to or read from it. For example, whether list.get(0) == list.get(0)
is true for
the returned list is unspecified.
backingArray
- the array to back the listCopyright © 2010-2017. All Rights Reserved.