Module org.klojang.util
Package org.klojang.util

Enum Class ResizeMethod

java.lang.Object
java.lang.Enum<ResizeMethod>
org.klojang.util.ResizeMethod
All Implemented Interfaces:
Serializable, Comparable<ResizeMethod>, Constable
public enum ResizeMethod extends Enum<ResizeMethod>
Defines ways to increase the capacity of backing arrays and other types of internally managed buffers and caches. Can be used if you want to leave it to clients of your class to decide upon a proper resizing strategy. If you use the resize methods to calculate a new size for the cache, buffer or backing array, the increase in size will max out at MAX_INCREASE for the MULTIPLY and PERCENTAGE resize methods. After that, they will behave like the ADD method, adding MAX_INCREASE to the backing array's current capacity each time it needs to be resized. In addition, the resize method will also take care of trapping buffer overflows (the backing array's length reaching or exceeding Integer.MAX_VALUE).

The following example illustrates how to use ResizeMethod: 


 public class DIYArrayList<E> extends AbstractList<E> {

  private final ResizeMethod resizeMethod;
  private final double resizeAmount;

  private Object[] buf;
  private int size;

  public DIYArrayList(int initialCapacity, ResizeMethod resizeMethod, double resizeAmount) {
    this.buf = new Object[initialCapacity];
    this.resizeMethod = resizeMethod;
    this.resizeAmount = resizeAmount;
  }

  @Override
  public boolean addAll(Collection<?> c) {
    int minIncrease = ResizeMethod.getMinIncrease(buf.length, size, c.size());
    if(minIncrease > 0) {
      increaseCapacity(minIncrease);
    }
    // append the collection ...
  }

  private void increaseCapacity(int minIncrease) {
    int newCap = resizeMethod.resize(buf.length, resizeAmount, minIncrease);
    Object[] newBuf = new Object[newCap];
    System.arraycopy(buf, 0, newBuf, 0, size);
    buf = newBuf;
  }

 }
See Also:

  • Nested Class Summary

    Nested classes/interfaces inherited from class java.lang.Enum

    Enum.EnumDesc<E extends Enum<E>>

  • Enum Constant Summary

    Enum Constants
    Enum Constant
    Description
    ADD
    Increase the capacity by a fixed amount each time the buffer reaches full capacity.
    MULTIPLY
    Increase the capacity by multiplying the current capacity by a fixed amount.
    PERCENTAGE
    Increase the capacity by adding a fixed percentage of the current capacity to the current capacity.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    MAX_INCREASE
    The maximum increase in size allowed by the MULTIPLY and PERCENTAGE resize methods: 8 * 1024 * 1024.

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    getMinIncrease(int curCapacity, int curSize, int itemCount)
    Calculates the extra capacity required to add itemCount items to an internally managed buffer, cache or backing array.
    int
    resize(int curCapacity, double amount)
    Calculates the new capacity for a buffer, cache or backing array using this ResizeMethod and the specified resize amount (c.q. factor c.q. percentage) The capacity will increase by at least 1.
    int
    resize(int curCapacity, double amount, int minIncrease)
    Calculates the new capacity for a buffer, cache or backing array using this ResizeMethod.
    static ResizeMethod
    valueOf(String name)
    Returns the enum constant of this class with the specified name.
    static ResizeMethod[]
    values()
    Returns an array containing the constants of this enum class, in the order they are declared.

    Methods inherited from class java.lang.Enum

    clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Enum Constant Details

    • ADD

      public static final ResizeMethod ADD
      Increase the capacity by a fixed amount each time the buffer reaches full capacity.

    • MULTIPLY

      public static final ResizeMethod MULTIPLY
      Increase the capacity by multiplying the current capacity by a fixed amount. Using this resize method with a resize factor of 2 is the "classic" way of resizing a backing array.

    • PERCENTAGE

      public static final ResizeMethod PERCENTAGE
      Increase the capacity by adding a fixed percentage of the current capacity to the current capacity.

  • Field Details

  • Method Details

    • values

      public static ResizeMethod[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static ResizeMethod valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • getMinIncrease

      public static int getMinIncrease(int curCapacity, int curSize, int itemCount)
      Calculates the extra capacity required to add itemCount items to an internally managed buffer, cache or backing array. If the result is zero or negative, no resizing is necessary. The return value of this method can be used as the minIncrease argument for the resize method.
      Parameters:
      curCapacity - The current length or size of the buffer, cache or backing array
      curSize - The number of items already in the buffer, cache or backing array
      itemCount - The number of items to be added to the buffer, cache or backing array
      Returns:
      If positive, the extra capacity required for the new items, else the remaining capacity once the new items have been added

    • resize

      public int resize(int curCapacity, double amount)
      Calculates the new capacity for a buffer, cache or backing array using this ResizeMethod and the specified resize amount (c.q. factor c.q. percentage) The capacity will increase by at least 1.
      Parameters:
      curCapacity - The current capacity
      amount - The amount, factor or percentage by which to increase the current capacity. This would typically be the value of a (final) instance variable in the class managing the backing array, and it would typically be passed in through the constructor, along with the resize method.
      Returns:
      The value to be used as the length for the new backing array

    • resize

      public int resize(int curCapacity, double amount, int minIncrease)
      Calculates the new capacity for a buffer, cache or backing array using this ResizeMethod. The capacity will increase by at least minIncrease. A BufferOverflowException is thrown if the current capacity is Integer.MAX_VALUE, or if curCapacity + minIncrease is greater than Integer.MAX_VALUE.
      Parameters:
      curCapacity - The current capacity. It is allowed to start off with zero initial capacity. When resizing using the MULTIPLY or PERCENTAGE method, the initial capacity will first be tacitly increased to 1.
      amount - The amount, factor or percentage by which to increase the current capacity. This would typically be the value of a (final) instance variable in the class managing the backing array, and it would typically be passed in through the constructor, along with the resize method.
      minIncrease - The minimum amount by which to increase current capacity. This would typically be the size of an incoming block of data that necessitated the resizing of the backing array. The provided value will override MAX_INCREASE and it must be at least 1.
      Returns:
      The value to be used as the length for the new backing array