it.unimi.dsi.util (dsiutil 2.3.3)

Interface Summary
Interface	Description
PrefixMap<S extends CharSequence>	A map from prefixes to string intervals (and possibly vice versa).
StringMap<S extends CharSequence>	A map from strings to numbers (and possibly vice versa).

Class Summary
Class	Description
AbstractPrefixMap	An abstract implementation of a prefix map.
BloomFilter<T>	A Bloom filter.
ByteBufferLongBigList	A bridge between byte buffers and long big lists.
CircularCharArrayBuffer	A circular char buffer that can be used to implement a sliding window over a text.
FrontCodedStringList	Compact storage of strings using front-coding compression (a.k.a. compression by prefix omission).
HyperLogLogCounterArray	An array of approximate sets each represented using a HyperLogLog counter.
ImmutableBinaryTrie<T>	An immutable implementation of binary tries.
ImmutableBinaryTrie.Node	A node in the trie.
ImmutableExternalPrefixMap	An immutable prefix map mostly stored in external memory.
Interval	An interval of integers.
Intervals	A class providing static methods and objects that do useful things with intervals.
KahanSummation	Kahan's summation algorithm encapsulated in an object.
LiterallySignedStringMap	A string map based on a function signed using the original list of strings.
LongInterval	An interval of longs.
LongIntervals	A class providing static methods and objects that do useful things with intervals.
PermutedFrontCodedStringList	A `FrontCodedStringList` whose indices are permuted.
Properties	An extension of `PropertiesConfiguration` providing setters for primitive types, a simpler way to save preferences and transparent handling of `Enum` lowercased keys.
SemiExternalGammaList	Provides semi-external random access to a list of γ-encoded integers.
ShiftAddXorSignedStringMap	A string map based on a function signed using Shift-Add-Xor hashes.
SplitMix64Random	A fast, top-quality, non-splittable version of the SplitMix pseudorandom number generator used by Java 8's `SplittableRandom`.
SplitMix64RandomGenerator	A fast, top-quality, non-splittable version of the SplitMix pseudorandom number generator used by Java 8's `SplittableRandom`.
StringMaps	A class providing static methods and objects that do useful things with string maps and prefix maps.
StringMaps.SynchronizedPrefixMap<S extends CharSequence>
StringMaps.SynchronizedStringMap<S extends CharSequence>
TernaryIntervalSearchTree	Ternary interval search trees.
TextPattern	QuickSearch matching against a constant string.
XoRoShiRo128PlusRandom	A fast, top-quality pseudorandom number generator that returns the sum of consecutive outputs of a handcrafted linear generator with 128 bits of state.
XoRoShiRo128PlusRandomGenerator	A fast, top-quality pseudorandom number generator that returns the sum of consecutive outputs of a handcrafted linear generator with 128 bits of state.
XorShift1024StarRandom	A fast, top-quality pseudorandom number generator that combines a long-period instance of George Marsaglia's Xorshift generators (described in “Xorshift RNGs”, Journal of Statistical Software, 8:1−6, 2003) with a multiplication.
XorShift1024StarRandomGenerator	A fast, top-quality pseudorandom number generator that combines a long-period instance of George Marsaglia's Xorshift generators (described in “Xorshift RNGs”, Journal of Statistical Software, 8:1−6, 2003) with a multiplication.
XorShift128PlusRandom	Deprecated Please use `XoRoShiRo128PlusRandom` instead.
XorShift128PlusRandomGenerator	Deprecated Please use `XoRoShiRo128PlusRandomGenerator` instead.
XorShift64StarRandom	Deprecated Use `SplitMix64Random` instead.
XorShift64StarRandomGenerator	Deprecated Use `SplitMix64RandomGenerator` instead.

Package it.unimi.dsi.util Description

Miscellaneaous utility classes.

Pseudorandom number generators

We provide a number of fast, high-quality PRNGs with different features.

xoroshiro128+ is a fast, top-quality generator. It has strong statistical properties and it is the fastest generator we provide. Its period (2¹²⁸ − 1) is sufficient for any application with a reasonable amount of parallelism. It is our suggestion for an all-purpose generator.
xorshift128+ is a fast, high-quality generator, but it has been superseded by xoroshiro128+, which is better under every respect. It is presently used in the JavaScript engines of Chrome, Firefox and Safari, and it is the default generator in Erlang.
SplitMix64 is a fast, top-quality generator, but it has a relatively short period (2⁶⁴) so it should not be used to generate very long sequences (the rule of thumb to have a period greater than the square of the length of the sequence you want to generate). It is a non-splittable version of Java 8's SplittableRandom, and thus conceptually identical to Java 8's ThreadLocalRandom (note that Java 7's version was identical to Random, instead). We use it to initialize the state of all other generators starting from a 64-bit seed.
xorshift1024* is fast, has good quality and provides a long period (2¹⁰²⁴ − 1) for massive parallel computations.

xoroshiro128+, xorshift128+ and xorshift1024* provide jump functions which make it possible to generate long non-overlapping sequences, and split functions in the spirit of SplittableRandom.

A table summarizing timings is provided below. Note that we test several different method parameters to highlight the different strategies used to generate numbers in a range, as the rejection-based algorithm used by all generators can be based on integer or long inputs, and the results are quite different. For example, on modern, 64-bit CPUs Java's strategy of applying rejection to 32-bit integers does not pay off (see the timings for nextInt(2³⁰ + 1)).

The timings are very different from previous versions, but they should be more reliable, as they are now obtained by means of JMH microbenchmarks. The JMH timings were decreased by 1ns, as using the low-level perfasm profiler the JMH overhead was estimated at ≈1ns per call.

	`Random`	`ThreadLocalRandom`	`SplittableRandom`	`SplitMix64`	`xoroshiro128+`	`xorshift128+`	`xorshift1024*`
nextInt()	8.272	1.860	1.999	1.896	1.936	2.007	3.127
nextLong()	17.549	1.886	2.123	2.054	1.994	2.012	3.106
nextDouble()	17.542	2.686	3.068	3.004	2.597	2.740	3.835
nextInt(100000)	8.285	3.163	3.769	3.713	3.070	3.264	4.753
nextInt(2²⁹+2²⁸)	12.634	7.939	8.574	4.130	3.347	3.586	5.152
nextInt(2³⁰)	8.269	1.886	2.148	2.226	1.978	2.580	3.229
nextInt(2³⁰ + 1)	22.152	15.645	16.483	3.837	3.244	3.528	5.004
nextInt(2³⁰ + 2²⁹)	12.581	7.923	8.578	4.092	3.344	3.572	5.138
nextLong(1000000000000)		3.482	4.060	3.923	3.304	3.604	5.064
nextLong(2⁶² + 1)		16.090	16.864	16.811	13.805	14.878	18.197

The quality of all generators we provide is very high: for instance, they perform better than WELL1024a or MT19937 (AKA the Mersenne Twister) in the TestU01 BigCrush test suite. More details can be found on the xoroshiro+/xorshift*/xorshift+ generators and the PRNG shootout page.

For each generator, we provide a version that extends Random, overriding (as usual) the next(int) method. Nonetheless, since the generators are all inherently 64-bit also nextInt(), nextFloat(), nextLong(), nextDouble(), nextBoolean() and nextBytes(byte[]) have been overridden for speed (preserving, of course, Random's semantics). In particular, nextDouble() and nextFloat() use a multiplication-free conversion.

If you do not need an instance of Random, or if you need a RandomGenerator to use with Commons Math, there is for each generator a corresponding RandomGenerator implementation, which indeed we suggest to use in general if you do not need a generator implementing Random.