Package org.apache.commons.lang3

Class CachedRandomBits

java.lang.Object
org.apache.commons.lang3.CachedRandomBits
final class CachedRandomBits extends Object
Generates random integers of specific bit length.

It is more efficient than calling Random.nextInt(1 invalid input: '<'invalid input: '<' 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

    Fields
    Modifier and Type
    Field
    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

    Constructors
    Constructor
    Description
    CachedRandomBits(int cacheSize, Random random)
    Creates a new instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    nextBits(int bits)
    Generates a random integer with the specified number of bits.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • MAX_CACHE_SIZE

      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.

      See Also:

    • MAX_BITS

      private static final int MAX_BITS
      Maximum number of bits that can be generated (size of an int)
      See Also:

    • BIT_INDEX_MASK

      private static final int BIT_INDEX_MASK
      Mask to extract the bit offset within a byte (0-7)
      See Also:

    • BITS_PER_BYTE

      private static final int BITS_PER_BYTE
      Number of bits in a byte
      See Also:

    • random

      private final Random random

    • cache

      private final byte[] cache

    • bitIndex

      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.

  • Constructor Details

    • CachedRandomBits

      CachedRandomBits(int cacheSize, Random random)
      Creates a new instance.
      Parameters:
      cacheSize - number of bytes cached (only affects performance)
      random - random source

  • Method Details

    • nextBits

      public int nextBits(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 - number of bits to generate, MUST be between 1 and 32 (inclusive)
      Returns:
      random integer containing exactly the requested number of random bits
      Throws:
      IllegalArgumentException - if bits is not between 1 and 32