Package org.apache.commons.lang3

Class CachedRandomBits

  • final class CachedRandomBits
extends java.lang.Object
    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

      Fields 
      Modifier and Type Field Description
      private static 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 int BITS_PER_BYTE
      Number of bits in a byte
      private byte[] cache  
      private static int MAX_BITS
      Maximum number of bits that can be generated (size of an int)
      private static int MAX_CACHE_SIZE
      The maximum size of the cache.
      private java.util.Random random  

    • Constructor Summary

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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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 Detail

      • 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:
        Constant Field Values

      • MAX_BITS

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

      • BIT_INDEX_MASK

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

      • BITS_PER_BYTE

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

      • random

        private final java.util.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 Detail

      • CachedRandomBits

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

    • Method Detail

      • 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:
        java.lang.IllegalArgumentException - if bits is not between 1 and 32