Top Description Fields Constructors Methods
org.apache.commons.lang3

pack-priv final Class CachedRandomBits

extends Object
Class Inheritance
Imports
java.util.Objects, .Random
Generates random integers of specific bit length.

It is more efficient than calling Random.nextInt(1 << nbBits). It uses a cache of cacheSize random bytes that it replenishes when it gets empty. This is especially beneficial for SecureRandom Drbg implementations, which incur a constant cost at each randomness generation.

Used internally by RandomStringUtils.

#NotThreadSafe#

Field Summary

Modifier and TypeField and Description
private static final int
BIT_INDEX_MASK

Mask to extract the bit offset within a byte (0-7)

private int
bitIndex

Index of the next bit in the cache to be used.

private static final int
BITS_PER_BYTE

Number of bits in a byte

private final byte[]
cache

private static final int
MAX_BITS

Maximum number of bits that can be generated (size of an int)

private static final int
MAX_CACHE_SIZE

The maximum size of the cache.

private final Random
random

Constructor Summary

AccessConstructor and Description
pack-priv
CachedRandomBits(final int
number of bytes cached (only affects performance)
cacheSize, final Random
random source
random)

Creates a new instance.

Method Summary

Modifier and TypeMethod and Description
public int

Returns:

random integer containing exactly the requested number of random bits
nextBits(final int
number of bits to generate, MUST be between 1 and 32 (inclusive)
bits)

Generates a random integer with the specified number of bits.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

BIT_INDEX_MASKback to summary
private static final int BIT_INDEX_MASK

Mask to extract the bit offset within a byte (0-7)

bitIndexback to summary
private int bitIndex

Index of the next bit in the cache to be used.

  • bitIndex=0 means the cache is fully random and none of the bits have been used yet.
  • bitIndex=1 means that only the LSB of cache[0] has been used and all other bits can be used.
  • bitIndex=8 means that only the 8 bits of cache[0] has been used.
BITS_PER_BYTEback to summary
private static final int BITS_PER_BYTE

Number of bits in a byte

cacheback to summary
private final byte[] cache
MAX_BITSback to summary
private static final int MAX_BITS

Maximum number of bits that can be generated (size of an int)

MAX_CACHE_SIZEback to summary
private static final int MAX_CACHE_SIZE

The maximum size of the cache.

This is to prevent the possibility of overflow in the if (bitIndex >> 3 >= cache.length) in the nextBits(int) method.

randomback to summary
private final Random random

Constructor Detail

CachedRandomBitsback to summary
pack-priv CachedRandomBits(final int cacheSize, final Random random)

Creates a new instance.

Parameters
cacheSize:int

number of bytes cached (only affects performance)

random:Random

random source

Method Detail

nextBitsback to summary
public int nextBits(final int bits)

Generates a random integer with the specified number of bits.

This method efficiently generates random bits by using a byte cache and bit manipulation:

  • Uses a byte array cache to avoid frequent calls to the underlying random number generator
  • Extracts bits from each byte using bit shifting and masking
  • Handles partial bytes to avoid wasting random bits
  • Accumulates bits until the requested number is reached

Parameters
bits:int

number of bits to generate, MUST be between 1 and 32 (inclusive)

Returns:int

random integer containing exactly the requested number of random bits

Exceptions
IllegalArgumentException:
if bits is not between 1 and 32