com.google.common.hash.HashCode Maven / Gradle / Ivy
Show all versions of aem-sdk-api Show documentation
/*
* Copyright (C) 2011 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
* in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.common.hash;
import static com.google.common.base.Preconditions.checkArgument;
import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.base.Preconditions.checkState;
import com.google.common.annotations.Beta;
import com.google.common.base.Preconditions;
import com.google.common.primitives.Ints;
import com.google.common.primitives.UnsignedInts;
import java.io.Serializable;
import java.security.MessageDigest;
import javax.annotation.Nullable;
/**
* An immutable hash code of arbitrary bit length.
*
* @author Dimitris Andreou
* @author Kurt Alfred Kluever
* @since 11.0
*
* @deprecated The Google Guava Core Libraries are deprecated and will not be part of the AEM SDK after April 2023
*/
@Beta
@Deprecated(since = "2022-12-01")
public abstract class HashCode {
HashCode() {
}
/**
* Returns the first four bytes of {@linkplain #asBytes() this hashcode's bytes}, converted to
* an {@code int} value in little-endian order.
*
* @throws IllegalStateException if {@code bits() < 32}
*/
public abstract int asInt();
/**
* Returns the first eight bytes of {@linkplain #asBytes() this hashcode's bytes}, converted to
* a {@code long} value in little-endian order.
*
* @throws IllegalStateException if {@code bits() < 64}
*/
public abstract long asLong();
/**
* If this hashcode has enough bits, returns {@code asLong()}, otherwise returns a {@code long}
* value with {@code asBytes()} as the least-significant bytes and {@code 0x00} as the remaining
* most-significant bytes.
*
* @since 14.0 (since 11.0 as {@code Hashing.padToLong(HashCode)})
*/
public abstract long padToLong();
/**
* Returns the value of this hash code as a byte array. The caller may modify the byte array;
* changes to it will not be reflected in this {@code HashCode} object or any other arrays
* returned by this method.
*/
// TODO(user): consider ByteString here, when that is available
public abstract byte[] asBytes();
/**
* Creates a 32-bit {@code HashCode} representation of the given int value. The underlying bytes
* are interpreted in little endian order.
*
* @since 15.0 (since 12.0 in HashCodes)
*/
public static HashCode fromInt(int hash) {
return new IntHashCode(hash);
}
// @deprecated The Google Guava Core Libraries are deprecated and will not be part of the AEM SDK after April 2023
@Deprecated(since = "2022-12-01")
private static final class IntHashCode extends HashCode implements Serializable {
final int hash;
IntHashCode(int hash) {
this.hash = hash;
}
@Override
public int bits() {
return 32;
}
@Override
public byte[] asBytes() {
return new byte[] { (byte) hash, (byte) (hash >> 8), (byte) (hash >> 16), (byte) (hash >> 24) };
}
@Override
public int asInt() {
return hash;
}
@Override
public long asLong() {
throw new IllegalStateException("this HashCode only has 32 bits; cannot create a long");
}
@Override
public long padToLong() {
return UnsignedInts.toLong(hash);
}
private static final long serialVersionUID = 0;
}
/**
* Creates a 64-bit {@code HashCode} representation of the given long value. The underlying bytes
* are interpreted in little endian order.
*
* @since 15.0 (since 12.0 in HashCodes)
*/
public static HashCode fromLong(long hash) {
return new LongHashCode(hash);
}
// @deprecated The Google Guava Core Libraries are deprecated and will not be part of the AEM SDK after April 2023
@Deprecated(since = "2022-12-01")
private static final class LongHashCode extends HashCode implements Serializable {
final long hash;
LongHashCode(long hash) {
this.hash = hash;
}
@Override
public int bits() {
return 64;
}
@Override
public byte[] asBytes() {
return new byte[] { (byte) hash, (byte) (hash >> 8), (byte) (hash >> 16), (byte) (hash >> 24), (byte) (hash >> 32), (byte) (hash >> 40), (byte) (hash >> 48), (byte) (hash >> 56) };
}
@Override
public int asInt() {
return (int) hash;
}
@Override
public long asLong() {
return hash;
}
@Override
public long padToLong() {
return hash;
}
private static final long serialVersionUID = 0;
}
/**
* Creates a {@code HashCode} from a byte array. The array is defensively copied to preserve
* the immutability contract of {@code HashCode}. The array cannot be empty.
*
* @since 15.0 (since 12.0 in HashCodes)
*/
public static HashCode fromBytes(byte[] bytes) {
checkArgument(bytes.length >= 1, "A HashCode must contain at least 1 byte.");
return fromBytesNoCopy(bytes.clone());
}
/**
* Creates a {@code HashCode} from a byte array. The array is not copied defensively,
* so it must be handed-off so as to preserve the immutability contract of {@code HashCode}.
*/
static HashCode fromBytesNoCopy(byte[] bytes) {
return new BytesHashCode(bytes);
}
// @deprecated The Google Guava Core Libraries are deprecated and will not be part of the AEM SDK after April 2023
@Deprecated(since = "2022-12-01")
private static final class BytesHashCode extends HashCode implements Serializable {
final byte[] bytes;
BytesHashCode(byte[] bytes) {
this.bytes = checkNotNull(bytes);
}
@Override
public int bits() {
return bytes.length * 8;
}
@Override
public byte[] asBytes() {
return bytes.clone();
}
@Override
public int asInt() {
checkState(bytes.length >= 4, "HashCode#asInt() requires >= 4 bytes (it only has %s bytes).", bytes.length);
return (bytes[0] & 0xFF) | ((bytes[1] & 0xFF) << 8) | ((bytes[2] & 0xFF) << 16) | ((bytes[3] & 0xFF) << 24);
}
@Override
public long asLong() {
checkState(bytes.length >= 8, "HashCode#asLong() requires >= 8 bytes (it only has %s bytes).", bytes.length);
return padToLong();
}
@Override
public long padToLong() {
long retVal = (bytes[0] & 0xFF);
for (int i = 1; i < Math.min(bytes.length, 8); i++) {
retVal |= (bytes[i] & 0xFFL) << (i * 8);
}
return retVal;
}
private static final long serialVersionUID = 0;
}
/**
* Returns the number of bits in this hash code; a positive multiple of 8.
*/
public abstract int bits();
/**
* Creates a {@code HashCode} from a hexadecimal ({@code base 16}) encoded string. The string must
* be at least 2 characters long, and contain only valid, lower-cased hexadecimal characters.
*
* This method accepts the exact format generated by {@link #toString}. If you require more
* lenient {@code base 16} decoding, please use
* {@link com.google.common.io.BaseEncoding#decode} (and pass the result to {@link #fromBytes}).
*
* @since 15.0
*/
public static HashCode fromString(String string) {
checkArgument(string.length() >= 2, "input string (%s) must have at least 2 characters", string);
checkArgument(string.length() % 2 == 0, "input string (%s) must have an even number of characters", string);
byte[] bytes = new byte[string.length() / 2];
for (int i = 0; i < string.length(); i += 2) {
int ch1 = decode(string.charAt(i)) << 4;
int ch2 = decode(string.charAt(i + 1));
bytes[i / 2] = (byte) (ch1 + ch2);
}
return fromBytesNoCopy(bytes);
}
private static int decode(char ch) {
if (ch >= '0' && ch <= '9') {
return ch - '0';
}
if (ch >= 'a' && ch <= 'f') {
return ch - 'a' + 10;
}
throw new IllegalArgumentException("Illegal hexadecimal character: " + ch);
}
/**
* Copies bytes from this hash code into {@code dest}.
*
* @param dest the byte array into which the hash code will be written
* @param offset the start offset in the data
* @param maxLength the maximum number of bytes to write
* @return the number of bytes written to {@code dest}
* @throws IndexOutOfBoundsException if there is not enough room in {@code dest}
*/
public final int writeBytesTo(byte[] dest, int offset, int maxLength) {
maxLength = Ints.min(maxLength, bits() / 8);
Preconditions.checkPositionIndexes(offset, offset + maxLength, dest.length);
// TODO(user): Consider avoiding the array creation in asBytes() by stepping through
// the bytes individually.
byte[] hash = asBytes();
System.arraycopy(hash, 0, dest, offset, maxLength);
return maxLength;
}
@Override
public final boolean equals(@Nullable Object object) {
if (object instanceof HashCode) {
HashCode that = (HashCode) object;
// Undocumented: this is a non-short-circuiting equals(), in case this is a cryptographic
// hash code, in which case we don't want to leak timing information
return MessageDigest.isEqual(this.asBytes(), that.asBytes());
}
return false;
}
/**
* Returns a "Java hash code" for this {@code HashCode} instance; this is well-defined
* (so, for example, you can safely put {@code HashCode} instances into a {@code
* HashSet}) but is otherwise probably not what you want to use.
*/
@Override
public final int hashCode() {
// If we have at least 4 bytes (32 bits), just take the first 4 bytes. Since this is
// already a (presumably) high-quality hash code, any four bytes of it will do.
if (bits() >= 32) {
return asInt();
}
// If we have less than 4 bytes, use them all.
byte[] bytes = asBytes();
int val = (bytes[0] & 0xFF);
for (int i = 1; i < bytes.length; i++) {
val |= ((bytes[i] & 0xFF) << (i * 8));
}
return val;
}
/**
* Returns a string containing each byte of {@link #asBytes}, in order, as a two-digit unsigned
* hexadecimal number in lower case.
*
*
Note that if the output is considered to be a single hexadecimal number, this hash code's
* bytes are the big-endian representation of that number. This may be surprising since
* everything else in the hashing API uniformly treats multibyte values as little-endian. But
* this format conveniently matches that of utilities such as the UNIX {@code md5sum} command.
*
*
To create a {@code HashCode} from its string representation, see {@link #fromString}.
*/
@Override
public final String toString() {
byte[] bytes = asBytes();
StringBuilder sb = new StringBuilder(2 * bytes.length);
for (byte b : bytes) {
sb.append(hexDigits[(b >> 4) & 0xf]).append(hexDigits[b & 0xf]);
}
return sb.toString();
}
private static final char[] hexDigits = "0123456789abcdef".toCharArray();
}