Package com.github.tommyettinger.digital
Class Hasher
java.lang.Object
com.github.tommyettinger.digital.Hasher
64-bit and 32-bit hashing functions that we can rely on staying the same cross-platform.
This uses a family of algorithms all based on Wang Yi's wyhash, but using at most 64-bit
math. Wyhash was designed foremost for speed and also general-purpose usability, but not
cryptographic security. The functions here pass the stringent SMHasher test battery,
including the "bad seeds" test that wyhash itself fails. This is based on an early version
of wyhash,
source here,
but has diverged significantly.
This provides an object-based API and a static API, where a Hasher object is instantiated with a seed, and the static methods take a seed as their first argument. The hashes this returns are always 0 when given null to hash. Arrays with identical elements of identical types will hash identically. Arrays with identical numerical values but different types will sometimes hash differently. This class always provides 64-bit hashes via hash64() and 32-bit hashes via hash(). The hash64() and hash() methods use 64-bit math even when producing 32-bit hashes, for GWT reasons. GWT doesn't have the same behavior as desktop and Android applications when using ints because it treats ints mostly like doubles, sometimes, due to it using JavaScript. If we use mainly longs, though, GWT emulates the longs with a more complex technique behind-the-scenes, that behaves the same on the web as it does on desktop or on a phone. Since Hasher is supposed to be stable cross-platform, this is the way we need to go, despite it being slightly slower.
This class also provides static
There are also 192 predefined instances of Hasher that you can either select from the array
This provides an object-based API and a static API, where a Hasher object is instantiated with a seed, and the static methods take a seed as their first argument. The hashes this returns are always 0 when given null to hash. Arrays with identical elements of identical types will hash identically. Arrays with identical numerical values but different types will sometimes hash differently. This class always provides 64-bit hashes via hash64() and 32-bit hashes via hash(). The hash64() and hash() methods use 64-bit math even when producing 32-bit hashes, for GWT reasons. GWT doesn't have the same behavior as desktop and Android applications when using ints because it treats ints mostly like doubles, sometimes, due to it using JavaScript. If we use mainly longs, though, GWT emulates the longs with a more complex technique behind-the-scenes, that behaves the same on the web as it does on desktop or on a phone. Since Hasher is supposed to be stable cross-platform, this is the way we need to go, despite it being slightly slower.
This class also provides static
randomize1(long)
, randomize2(long)
, and
randomize3(long)
methods, which are unary hashes (hashes of one item, a number) with variants such as
randomize1Bounded(long, int)
and randomize2Float(long)
. The randomize1()
methods are faster but more sensitive to patterns in their input; they are meant to
work well on sequential inputs, like 1, 2, 3, etc. with relatively-short sequences
(ideally under a million, but if statistical quality isn't a concern, they can handle any
length). The randomize2() methods are more-involved, but should be able to handle most
kinds of input pattern across even rather-large sequences (billions) while returning
random results. The randomize3() methods are likely complete overkill for many cases, but
provide extremely strong randomization for any possible input pattern, using the MX3 unary
hash with an extra XOR at the beginning to prevent a fixed point at 0.
There are also 192 predefined instances of Hasher that you can either select from the array
predefined
or select by hand, such as omega
.
The predefined instances are named after the 24 greek letters, then the same letters
with a trailing underscore, then
72 names of demons from the Ars Goetia,
then the names of those demons with trailing underscores. The greek letters are traditional,
and the demons are perfectly fitting for video games.-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final long
Big constant 0.static final long
Big constant 1.static final long
Big constant 2.static final long
Big constant 3.static final long
Big constant 4.static final long
Big constant 5.static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher[]
Has a length of 192, which may be relevant if automatically choosing a predefined hash functor.static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
final long
The seed used by all non-static hash() and hash64() methods in this class (the methods that don't take a seed).static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
static final Hasher
-
Constructor Summary
ConstructorsConstructorDescriptionHasher()
Creates a new Hasher seeded, arbitrarily, with the constant 0xC4CEB9FE1A85EC53L, or -4265267296055464877L .Hasher
(long seed) Initializes this Hasher with the given seed, verbatim; it is recommended to userandomize3(long)
on the seed if you don't know if it is adequately-random.Hasher
(CharSequence seed) Constructs a Hasher by hashingseed
withhash64(long, CharSequence)
, and then running the result throughrandomize2(long)
. -
Method Summary
Modifier and TypeMethodDescriptionint
hash
(boolean[] data) int
hash
(byte[] data) int
hash
(byte[][] data) int
hash
(char[] data) int
hash
(char[][] data) int
hash
(char[] data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).int
hash
(double[] data) int
hash
(double[][] data) int
hash
(float[] data) int
hash
(float[][] data) int
hash
(int[] data) int
hash
(int[][] data) int
hash
(int[] data, int length) int
hash
(long[] data) int
hash
(long[][] data) static int
hash
(long seed, boolean[] data) static int
hash
(long seed, byte[] data) static int
hash
(long seed, byte[][] data) static int
hash
(long seed, char[] data) static int
hash
(long seed, char[][] data) static int
hash
(long seed, char[] data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).static int
hash
(long seed, double[] data) static int
hash
(long seed, double[][] data) static int
hash
(long seed, float[] data) static int
hash
(long seed, float[][] data) static int
hash
(long seed, int[] data) static int
hash
(long seed, int[][] data) static int
hash
(long seed, int[] data, int length) static int
hash
(long seed, long[] data) static int
hash
(long seed, long[][] data) static int
hash
(long seed, short[] data) static int
hash
(long seed, CharSequence data) static int
hash
(long seed, CharSequence[] data) static int
hash
(long seed, CharSequence[]... data) static int
hash
(long seed, CharSequence data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).static int
hash
(long seed, Iterable<? extends CharSequence> data) static int
static int
static int
hash
(long seed, List<? extends CharSequence> data) int
hash
(short[] data) int
hash
(CharSequence data) int
hash
(CharSequence[] data) int
hash
(CharSequence[]... data) int
hash
(CharSequence data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).int
hash
(Iterable<? extends CharSequence> data) int
int
int
hash
(List<? extends CharSequence> data) long
hash64
(boolean[] data) long
hash64
(byte[] data) long
hash64
(byte[][] data) long
hash64
(char[] data) long
hash64
(char[][] data) long
hash64
(char[] data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).long
hash64
(double[] data) long
hash64
(double[][] data) long
hash64
(float[] data) long
hash64
(float[][] data) long
hash64
(int[] data) long
hash64
(int[][] data) long
hash64
(int[] data, int length) long
hash64
(long[] data) long
hash64
(long[][] data) static long
hash64
(long seed, boolean[] data) static long
hash64
(long seed, byte[] data) static long
hash64
(long seed, byte[][] data) static long
hash64
(long seed, char[] data) static long
hash64
(long seed, char[][] data) static long
hash64
(long seed, char[] data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).static long
hash64
(long seed, double[] data) static long
hash64
(long seed, double[][] data) static long
hash64
(long seed, float[] data) static long
hash64
(long seed, float[][] data) static long
hash64
(long seed, int[] data) static long
hash64
(long seed, int[][] data) static long
hash64
(long seed, int[] data, int length) static long
hash64
(long seed, long[] data) static long
hash64
(long seed, long[][] data) static long
hash64
(long seed, short[] data) static long
hash64
(long seed, CharSequence data) static long
hash64
(long seed, CharSequence[] data) static long
hash64
(long seed, CharSequence[]... data) static long
hash64
(long seed, CharSequence data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).static long
hash64
(long seed, Iterable<? extends CharSequence> data) static long
static long
static long
hash64
(long seed, List<? extends CharSequence> data) long
hash64
(short[] data) long
hash64
(CharSequence data) long
hash64
(CharSequence[] data) long
hash64
(CharSequence[]... data) long
hash64
(CharSequence data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).long
hash64
(Iterable<? extends CharSequence> data) long
long
long
hash64
(List<? extends CharSequence> data) static long
mum
(long a, long b) Takes two arguments that are technically longs, and should be very different, and uses them to get a result that is technically a long and mixes the bits of the inputs.static long
randomize1
(long state) Fast static randomizing method that takes its state as a parameter; state is expected to change between calls to this.static int
randomize1Bounded
(long state, int bound) Fast static randomizing method that takes its state as a parameter and limits output to an int between 0 (inclusive) and bound (exclusive); state is expected to change between calls to this.static double
randomize1Double
(long state) Returns a random double that is deterministic based on state; if state is the same on two calls to this, this will return the same float.static float
randomize1Float
(long state) Returns a random float that is deterministic based on state; if state is the same on two calls to this, this will return the same float.static long
randomize2
(long state) Mid-quality static randomizing method that takes its state as a parameter; state is expected to change between calls to this.static int
randomize2Bounded
(long state, int bound) Mid-quality static randomizing method that takes its state as a parameter and limits output to an int between 0 (inclusive) and bound (exclusive); state is expected to change between calls to this.static double
randomize2Double
(long state) Returns a random double that is deterministic based on state; if state is the same on two calls to this, this will return the same float.static float
randomize2Float
(long state) Returns a random float that is deterministic based on state; if state is the same on two calls to this, this will return the same float.static long
randomize3
(long state) Very thorough static randomizing method that takes its state as a parameter; state is expected to change between calls to this.static int
randomize3Bounded
(long state, int bound) Very thorough static randomizing method that takes its state as a parameter and limits output to an int between 0 (inclusive) and bound (exclusive); state is expected to change between calls to this.static double
randomize3Double
(long state) Returns a random double that is deterministic based on state; if state is the same on two calls to this, this will return the same float.static float
randomize3Float
(long state) Returns a random float that is deterministic based on state; if state is the same on two calls to this, this will return the same float.static long
wow
(long a, long b) A slower but higher-quality variant onmum(long, long)
that can take two arbitrary longs (with any of their 64 bits containing relevant data) instead of mum's 32-bit sections of its inputs, and outputs a 64-bit result that can have any of its bits used.
-
Field Details
-
seed
public final long seedThe seed used by all non-static hash() and hash64() methods in this class (the methods that don't take a seed). You can create many different Hasher objects, all with different seeds, and get very different hashes as a result of any calls on them. Because making this field hidden in some way doesn't meaningfully contribute to security, and only makes it harder to use this class,seed
is public (and final, so it can't be accidentally modified, but still can if needed via reflection). -
b0
public static final long b0Big constant 0.- See Also:
-
b1
public static final long b1Big constant 1.- See Also:
-
b2
public static final long b2Big constant 2.- See Also:
-
b3
public static final long b3Big constant 3.- See Also:
-
b4
public static final long b4Big constant 4.- See Also:
-
b5
public static final long b5Big constant 5.- See Also:
-
alpha
-
beta
-
gamma
-
delta
-
epsilon
-
zeta
-
eta
-
theta
-
iota
-
kappa
-
lambda
-
mu
-
nu
-
xi
-
omicron
-
pi
-
rho
-
sigma
-
tau
-
upsilon
-
phi
-
chi
-
psi
-
omega
-
alpha_
-
beta_
-
gamma_
-
delta_
-
epsilon_
-
zeta_
-
eta_
-
theta_
-
iota_
-
kappa_
-
lambda_
-
mu_
-
nu_
-
xi_
-
omicron_
-
pi_
-
rho_
-
sigma_
-
tau_
-
upsilon_
-
phi_
-
chi_
-
psi_
-
omega_
-
baal
-
agares
-
vassago
-
samigina
-
marbas
-
valefor
-
amon
-
barbatos
-
paimon
-
buer
-
gusion
-
sitri
-
beleth
-
leraje
-
eligos
-
zepar
-
botis
-
bathin
-
sallos
-
purson
-
marax
-
ipos
-
aim
-
naberius
-
glasya_labolas
-
bune
-
ronove
-
berith
-
astaroth
-
forneus
-
foras
-
asmoday
-
gaap
-
furfur
-
marchosias
-
stolas
-
phenex
-
halphas
-
malphas
-
raum
-
focalor
-
vepar
-
sabnock
-
shax
-
vine
-
bifrons
-
vual
-
haagenti
-
crocell
-
furcas
-
balam
-
alloces
-
caim
-
murmur
-
orobas
-
gremory
-
ose
-
amy
-
orias
-
vapula
-
zagan
-
valac
-
andras
-
flauros
-
andrealphus
-
kimaris
-
amdusias
-
belial
-
decarabia
-
seere
-
dantalion
-
andromalius
-
baal_
-
agares_
-
vassago_
-
samigina_
-
marbas_
-
valefor_
-
amon_
-
barbatos_
-
paimon_
-
buer_
-
gusion_
-
sitri_
-
beleth_
-
leraje_
-
eligos_
-
zepar_
-
botis_
-
bathin_
-
sallos_
-
purson_
-
marax_
-
ipos_
-
aim_
-
naberius_
-
glasya_labolas_
-
bune_
-
ronove_
-
berith_
-
astaroth_
-
forneus_
-
foras_
-
asmoday_
-
gaap_
-
furfur_
-
marchosias_
-
stolas_
-
phenex_
-
halphas_
-
malphas_
-
raum_
-
focalor_
-
vepar_
-
sabnock_
-
shax_
-
vine_
-
bifrons_
-
vual_
-
haagenti_
-
crocell_
-
furcas_
-
balam_
-
alloces_
-
caim_
-
murmur_
-
orobas_
-
gremory_
-
ose_
-
amy_
-
orias_
-
vapula_
-
zagan_
-
valac_
-
andras_
-
flauros_
-
andrealphus_
-
kimaris_
-
amdusias_
-
belial_
-
decarabia_
-
seere_
-
dantalion_
-
andromalius_
-
predefined
Has a length of 192, which may be relevant if automatically choosing a predefined hash functor.
-
-
Constructor Details
-
Hasher
public Hasher()Creates a new Hasher seeded, arbitrarily, with the constant 0xC4CEB9FE1A85EC53L, or -4265267296055464877L . -
Hasher
public Hasher(long seed) Initializes this Hasher with the given seed, verbatim; it is recommended to userandomize3(long)
on the seed if you don't know if it is adequately-random. If the seed is the same for two different Hasher instances and they are given the same inputs, they will produce the same results. If the seed is even slightly different, the results of the two Hashers given the same input should be significantly different.- Parameters:
seed
- a long that will be used to change the output of hash() and hash64() methods on the new Hasher
-
Hasher
Constructs a Hasher by hashingseed
withhash64(long, CharSequence)
, and then running the result throughrandomize2(long)
. This is the same as calling the constructorHasher(long)
and passing itrandomize2(hash64(1L, seed))
.- Parameters:
seed
- a CharSequence, such as a String, that will be used to seed the Hasher.
-
-
Method Details
-
randomize1
public static long randomize1(long state) Fast static randomizing method that takes its state as a parameter; state is expected to change between calls to this. It is recommended that you userandomize1(++state)
orrandomize1(--state)
to produce a sequence of different numbers, and you may have slightly worse quality with increments or decrements other than 1. All longs are accepted by this method, and all longs can be produced. Passing 0 here does not cause this to return 0.
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- any long; subsequent calls should change by an odd number, such as with++state
- Returns:
- any long
-
randomize2
public static long randomize2(long state) Mid-quality static randomizing method that takes its state as a parameter; state is expected to change between calls to this. It is suggested that you useDiverRNG.randomize(++state)
orDiverRNG.randomize(--state)
to produce a sequence of different numbers, but any increments are allowed (even-number increments won't be able to produce all outputs, but their quality will be fine for the numbers they can produce). All longs are accepted by this method, and all longs can be produced. Passing 0 here does not cause this to return 0.
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- any long; subsequent calls should change by an odd number, such as with++state
- Returns:
- any long
-
randomize3
public static long randomize3(long state) Very thorough static randomizing method that takes its state as a parameter; state is expected to change between calls to this. It is suggested that you userandomize3(++state)
orrandomize3(--state)
to produce a sequence of different numbers, but any odd-number increment should work well, as could another source of different longs, such as a flawed random number generator. All longs are accepted by this method, and all longs can be produced. Passing 0 here does not cause this to return 0.
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- any long; subsequent calls should change by an odd number, such as with++state
- Returns:
- any long
-
randomize1Bounded
public static int randomize1Bounded(long state, int bound) Fast static randomizing method that takes its state as a parameter and limits output to an int between 0 (inclusive) and bound (exclusive); state is expected to change between calls to this. It is recommended that you userandomize1Bounded(++state, bound)
orrandomize1Bounded(--state, bound)
to produce a sequence of different numbers. All longs are accepted by this method, but not all ints between 0 and bound are guaranteed to be produced with equal likelihood (for any odd-number values for bound, this isn't possible for most generators). The bound can be negative.
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- any long; subsequent calls should change by an odd number, such as with++state
bound
- the outer exclusive bound, as an int- Returns:
- an int between 0 (inclusive) and bound (exclusive)
-
randomize2Bounded
public static int randomize2Bounded(long state, int bound) Mid-quality static randomizing method that takes its state as a parameter and limits output to an int between 0 (inclusive) and bound (exclusive); state is expected to change between calls to this. It is suggested that you userandomize2Bounded(++state)
orrandomize2Bounded(--state)
to produce a sequence of different numbers, but any increments are allowed (even-number increments won't be able to produce all outputs, but their quality will be fine for the numbers they can produce). All longs are accepted by this method, but not all ints between 0 and bound are guaranteed to be produced with equal likelihood (for any odd-number values for bound, this isn't possible for most generators). The bound can be negative.
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- any long; subsequent calls should change by an odd number, such as with++state
bound
- the outer exclusive bound, as an int- Returns:
- an int between 0 (inclusive) and bound (exclusive)
-
randomize3Bounded
public static int randomize3Bounded(long state, int bound) Very thorough static randomizing method that takes its state as a parameter and limits output to an int between 0 (inclusive) and bound (exclusive); state is expected to change between calls to this. It is suggested that you userandomize3Bounded(++state)
orrandomize3(--state)
to produce a sequence of different numbers, but any increments are allowed (even-number increments won't be able to produce all outputs, but their quality will be fine for the numbers they can produce). All longs are accepted by this method, but not all ints between 0 and bound are guaranteed to be produced with equal likelihood (for any odd-number values for bound, this isn't possible for most generators). The bound can be negative.
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- any long; subsequent calls should change by an odd number, such as with++state
bound
- the outer exclusive bound, as an int- Returns:
- an int between 0 (inclusive) and bound (exclusive)
-
randomize1Float
public static float randomize1Float(long state) Returns a random float that is deterministic based on state; if state is the same on two calls to this, this will return the same float. This is expected to be called with a changing variable, e.g.randomize1Float(++state)
, where the increment for state should generally be 1. The period is 2 to the 64 if you increment or decrement by 1, but there are only 2 to the 30 possible floats between 0 and 1, and this can only return 2 to the 24 of them (a requirement for the returned values to be uniform).
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- a variable that should be different every time you want a different random result; usingrandomize1Float(++state)
is recommended to go forwards orrandomize1Float(--state)
to generate numbers in reverse order- Returns:
- a pseudo-random float between 0f (inclusive) and 1f (exclusive), determined by
state
-
randomize2Float
public static float randomize2Float(long state) Returns a random float that is deterministic based on state; if state is the same on two calls to this, this will return the same float. This is expected to be called with a changing variable, e.g.randomize2Float(++state)
, where the increment for state can be any value and should usually be odd (even-number increments reduce the period). The period is 2 to the 64 if you increment or decrement by any odd number, but there are only 2 to the 30 possible floats between 0 and 1, and this can only return 2 to the 24 of them (a requirement for the returned values to be uniform).
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- a variable that should be different every time you want a different random result; usingrandomize2Float(++state)
is recommended to go forwards orrandomize2Float(--state)
to generate numbers in reverse order- Returns:
- a pseudo-random float between 0f (inclusive) and 1f (exclusive), determined by
state
-
randomize3Float
public static float randomize3Float(long state) Returns a random float that is deterministic based on state; if state is the same on two calls to this, this will return the same float. This is expected to be called with a changing variable, e.g.randomize3Float(++state)
, where the increment for state can be any value and should usually be odd (even-number increments reduce the period). The period is 2 to the 64 if you increment or decrement by any odd number, but there are only 2 to the 30 possible floats between 0 and 1, and this can only return 2 to the 24 of them (a requirement for the returned values to be uniform).
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- a variable that should be different every time you want a different random result; usingrandomize3Float(++state)
is recommended to go forwards orrandomize3Float(--state)
to generate numbers in reverse order- Returns:
- a pseudo-random float between 0f (inclusive) and 1f (exclusive), determined by
state
-
randomize1Double
public static double randomize1Double(long state) Returns a random double that is deterministic based on state; if state is the same on two calls to this, this will return the same float. This is expected to be called with a changing variable, e.g.randomize1Double(++state)
, where the increment for state should generally be 1. The period is 2 to the 64 if you increment or decrement by 1, but there are only 2 to the 62 possible doubles between 0 and 1.
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- a variable that should be different every time you want a different random result; usingrandomize1Double(++state)
is recommended to go forwards orrandomize1Double(--state)
to generate numbers in reverse order- Returns:
- a pseudo-random double between 0.0 (inclusive) and 1.0 (exclusive), determined by
state
-
randomize2Double
public static double randomize2Double(long state) Returns a random double that is deterministic based on state; if state is the same on two calls to this, this will return the same float. This is expected to be called with a changing variable, e.g.randomize2Double(++state)
, where the increment for state can be any number but should usually be odd (even-number increments reduce the period). The period is 2 to the 64 if you increment or decrement by 1, but there are only 2 to the 62 possible doubles between 0 and 1.
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- a variable that should be different every time you want a different random result; usingrandomizeDouble(++state)
is recommended to go forwards orrandomizeDouble(--state)
to generate numbers in reverse order- Returns:
- a pseudo-random double between 0.0 (inclusive) and 1.0 (exclusive), determined by
state
-
randomize3Double
public static double randomize3Double(long state) Returns a random double that is deterministic based on state; if state is the same on two calls to this, this will return the same float. This is expected to be called with a changing variable, e.g.randomize3Double(++state)
, where the increment for state can be any number but should usually be odd (even-number increments reduce the period). The period is 2 to the 64 if you increment or decrement by 1, but there are only 2 to the 62 possible doubles between 0 and 1.
You have a choice between different randomize strengths in this class.randomize1()
is simpler, and will behave well when the inputs are sequential, whilerandomize2()
is a completely different algorithm, Pelle Evensen's xNASAM; it will have excellent quality for most patterns in input but will be about 30% slower thanrandomize1()
, though this is rarely detectable.randomize3()
is the slowest and most robust; it uses MX3 by Jon Maiga, which the aforementioned author of xNASAM now recommends for any unary hashing. All randomizeN methods will produce all long outputs if given all possible longs as input. Technically-speaking,randomize1(long)
,randomize2(long)
, andrandomize3(long)
are bijective functions, which means they are reversible; it is, however, somewhat harder to reverse the xor-rotate-xor-rotate stage used in randomize2() (reversing randomize3() is easy, but takes more steps), and the methods that produce any output other than a full-range long are not reversible (such asrandomize1Bounded(long, int)
andrandomize2Double(long)
).- Parameters:
state
- a variable that should be different every time you want a different random result; usingrandomize3Double(++state)
is recommended to go forwards orrandomize3Double(--state)
to generate numbers in reverse order- Returns:
- a pseudo-random double between 0.0 (inclusive) and 1.0 (exclusive), determined by
state
-
mum
public static long mum(long a, long b) Takes two arguments that are technically longs, and should be very different, and uses them to get a result that is technically a long and mixes the bits of the inputs. The arguments and result are only technically longs because their lower 32 bits matter much more than their upper 32, and giving just any long won't work.
This is very similar to wyhash's mum function, but doesn't use 128-bit math because it expects that its arguments are only relevant in their lower 32 bits (allowing their product to fit in 64 bits).- Parameters:
a
- a long that should probably only hold an int's worth of datab
- a long that should probably only hold an int's worth of data- Returns:
- a sort-of randomized output dependent on both inputs
-
wow
public static long wow(long a, long b) A slower but higher-quality variant onmum(long, long)
that can take two arbitrary longs (with any of their 64 bits containing relevant data) instead of mum's 32-bit sections of its inputs, and outputs a 64-bit result that can have any of its bits used.
This was changed so that it distributes bits from both inputs a little better on July 6, 2019.- Parameters:
a
- any longb
- any long- Returns:
- a sort-of randomized output dependent on both inputs
-
hash64
public long hash64(boolean[] data) -
hash64
public long hash64(byte[] data) -
hash64
public long hash64(short[] data) -
hash64
public long hash64(char[] data) -
hash64
-
hash64
public long hash64(int[] data) -
hash64
public long hash64(int[] data, int length) -
hash64
public long hash64(long[] data) -
hash64
public long hash64(float[] data) -
hash64
public long hash64(double[] data) -
hash64
public long hash64(char[] data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).- Parameters:
data
- the char array to hashstart
- the start of the section to hash (inclusive)end
- the end of the section to hash (exclusive)- Returns:
- a 64-bit hash code for the requested section of data
-
hash64
Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).- Parameters:
data
- the String or other CharSequence to hashstart
- the start of the section to hash (inclusive)end
- the end of the section to hash (exclusive)- Returns:
- a 64-bit hash code for the requested section of data
-
hash64
public long hash64(byte[][] data) -
hash64
public long hash64(char[][] data) -
hash64
public long hash64(float[][] data) -
hash64
public long hash64(double[][] data) -
hash64
public long hash64(int[][] data) -
hash64
public long hash64(long[][] data) -
hash64
-
hash64
-
hash64
-
hash64
-
hash64
-
hash64
-
hash
public int hash(boolean[] data) -
hash
public int hash(byte[] data) -
hash
public int hash(short[] data) -
hash
public int hash(char[] data) -
hash
-
hash
public int hash(int[] data) -
hash
public int hash(int[] data, int length) -
hash
public int hash(long[] data) -
hash
public int hash(float[] data) -
hash
public int hash(double[] data) -
hash
public int hash(char[] data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).- Parameters:
data
- the char array to hashstart
- the start of the section to hash (inclusive)end
- the end of the section to hash (exclusive)- Returns:
- a 32-bit hash code for the requested section of data
-
hash
Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).- Parameters:
data
- the String or other CharSequence to hashstart
- the start of the section to hash (inclusive)end
- the end of the section to hash (exclusive)- Returns:
- a 32-bit hash code for the requested section of data
-
hash
public int hash(byte[][] data) -
hash
public int hash(char[][] data) -
hash
public int hash(float[][] data) -
hash
public int hash(double[][] data) -
hash
public int hash(int[][] data) -
hash
public int hash(long[][] data) -
hash
-
hash
-
hash
-
hash
-
hash
-
hash
-
hash64
public static long hash64(long seed, boolean[] data) -
hash64
public static long hash64(long seed, byte[] data) -
hash64
public static long hash64(long seed, short[] data) -
hash64
public static long hash64(long seed, char[] data) -
hash64
-
hash64
public static long hash64(long seed, int[] data) -
hash64
public static long hash64(long seed, int[] data, int length) -
hash64
public static long hash64(long seed, long[] data) -
hash64
public static long hash64(long seed, float[] data) -
hash64
public static long hash64(long seed, double[] data) -
hash64
public static long hash64(long seed, char[] data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).- Parameters:
data
- the char array to hashstart
- the start of the section to hash (inclusive)end
- the end of the section to hash (exclusive)- Returns:
- a 32-bit hash code for the requested section of data
-
hash64
Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).- Parameters:
data
- the String or other CharSequence to hashstart
- the start of the section to hash (inclusive)end
- the end of the section to hash (exclusive)- Returns:
- a 32-bit hash code for the requested section of data
-
hash64
public static long hash64(long seed, byte[][] data) -
hash64
public static long hash64(long seed, char[][] data) -
hash64
public static long hash64(long seed, float[][] data) -
hash64
public static long hash64(long seed, double[][] data) -
hash64
public static long hash64(long seed, int[][] data) -
hash64
public static long hash64(long seed, long[][] data) -
hash64
-
hash64
-
hash64
-
hash64
-
hash64
-
hash64
-
hash
public static int hash(long seed, boolean[] data) -
hash
public static int hash(long seed, byte[] data) -
hash
public static int hash(long seed, short[] data) -
hash
public static int hash(long seed, char[] data) -
hash
-
hash
public static int hash(long seed, int[] data) -
hash
public static int hash(long seed, int[] data, int length) -
hash
public static int hash(long seed, long[] data) -
hash
public static int hash(long seed, float[] data) -
hash
public static int hash(long seed, double[] data) -
hash
public static int hash(long seed, char[] data, int start, int end) Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).- Parameters:
data
- the char array to hashstart
- the start of the section to hash (inclusive)end
- the end of the section to hash (exclusive)- Returns:
- a 32-bit hash code for the requested section of data
-
hash
Hashes only a subsection of the given data, starting at start (inclusive) and ending before end (exclusive).- Parameters:
data
- the String or other CharSequence to hashstart
- the start of the section to hash (inclusive)end
- the end of the section to hash (exclusive)- Returns:
- a 32-bit hash code for the requested section of data
-
hash
public static int hash(long seed, byte[][] data) -
hash
public static int hash(long seed, char[][] data) -
hash
public static int hash(long seed, float[][] data) -
hash
public static int hash(long seed, double[][] data) -
hash
public static int hash(long seed, int[][] data) -
hash
public static int hash(long seed, long[][] data) -
hash
-
hash
-
hash
-
hash
-
hash
-
hash
-