Class BagArray

java.lang.Object
us.irdev.bedrock.bag.Bag
us.irdev.bedrock.bag.BagArray
All Implemented Interfaces:
Iterable<Object>, Selectable<BagArray>
public class BagArray extends Bag implements Selectable<BagArray>, Iterable<Object>
A collection of text-based values stored in a zero-based indexed array.

Note: the BagArray class, from a memory allocation standpoint, is not designed to work efficiently with dynamic storage of very large numbers of elements (more than 1,000s). It will work, but we have not chosen to focus on this as a potential use-case.

  • Constructor Details

    • BagArray

      public BagArray()
      Create a new BagArray with a default underlying storage size.

    • BagArray

      public BagArray(int size)
      Create a new BagArray with hint for the underlying storage size.
      Parameters:
      size - The expected number of elements in the BagArray, treated as a hint to optimize memory allocation. If additional elements are stored, the BagArray will revert to normal allocation behavior.

    • BagArray

      public BagArray(BagArray bagArray)
      Create a new BagArray as deep copy of another BagArray

  • Method Details

    • getCount

      public int getCount()
      Return the number of elements stored in the BagArray.
      Returns:
      the count of elements in the underlying store. This is distinct from the capacity of the underlying store.

    • insert

      public BagArray insert(int index, Object object)
      Inserts the element at the given index of the underlying array store. The underlying store is shifted to make space for the new element. The shift might cause the underlying store to be resized if there is insufficient room.

      Note that null values for the element ARE stored, as the underlying store is not a sparse array.

      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      object - The element to store.
      Returns:
      The BagArray, so that operations can be chained together.

    • add

      public BagArray add(Object object)
      Adds the element at the end of the underlying array store. The underlying store might be resized if there is insufficient room.

      Note that null values for the element ARE stored, as the underlying store is not a sparse array.

      Parameters:
      object - The element to store.
      Returns:
      The BagArray, so that operations can be chained together.

    • open

      public static BagArray open(Object object)
      Create a new BagArray and "add" the object.
      Parameters:
      object - The element to store.
      Returns:
      The newly created BagArray.

    • concat

      public static BagArray concat(BagArray left, BagArray right)
      Parameters:
      left -
      right -
      Returns:

    • replace

      public BagArray replace(int index, Object object)
      Replaces the element at the given index of the underlying array store. The underlying store is not shifted, and will not be resized.

      Note that null values for the element ARE stored, as the underlying store is not a sparse array.

      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      object - The element to store.
      Returns:
      The BagArray, so that operations can be chained together.

    • remove

      public BagArray remove(int index)
      Removes the element at the given index of the underlying array store. The underlying store is shifted to cover the removed item. The underlying store will not be resized. Using invalid indices is ignored.
      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      Returns:
      The BagArray, so that operations can be chained together.

    • getObject

      public Object getObject(int index)

    • getAndRemove

      public Object getAndRemove(int index)
      Parameters:
      index -
      Returns:

    • pop

      public Object pop()
      Returns:

    • dequeue

      public Object dequeue()
      Returns:

    • getObject

      public Object getObject(String key)
      Return an object stored at the requested key value. The key may be a simple number, or a special keyword indicating the #first or #last element in the array, #add for putting at the end of the array, or it may be a path (with keys separated by "/") to create a hierarchical "bedrock-of-bags" that is indexed recursively.

      Specified by:
      getObject in class Bag
      Parameters:
      key - A string value used to index the element, using "/" as separators, for example: "12/com/brettonw" or "#last/completed"
      Returns:
      The indexed element (if found), or null

    • getString

      public String getString(int index)
      Retrieve an indexed element and return it as a String.
      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      Returns:
      The element as a string, or null if the element is not found (or not a String).

    • getBoolean

      public Boolean getBoolean(int index)
      Retrieve an indexed element and return it as a Boolean.
      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      Returns:
      The element as a Boolean, or null if the element is not found.

    • getLong

      public Long getLong(int index)
      Retrieve an indexed element and return it as a Long.
      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      Returns:
      The element as a Long, or null if the element is not found.

    • getInteger

      public Integer getInteger(int index)
      Retrieve an indexed element and return it as an Integer.
      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      Returns:
      The element as an Integer, or null if the element is not found.

    • getDouble

      public Double getDouble(int index)
      Retrieve an indexed element and return it as a Double.
      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      Returns:
      The element as a Double, or null if the element is not found.

    • getFloat

      public Float getFloat(int index)
      Retrieve an indexed element and return it as a Float.
      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      Returns:
      The element as a Float, or null if the element is not found.

    • getBagObject

      public BagObject getBagObject(int index)
      Retrieve an indexed element and return it as a BagObject.
      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      Returns:
      The element as a BagObject, or null if the element is not found.

    • getBagArray

      public BagArray getBagArray(int index)
      Retrieve an indexed element and return it as a BagArray.
      Parameters:
      index - An integer value specifying the offset from the beginning of the array.
      Returns:
      The element as a BagArray, or null if the element is not found.

    • toString

      public String toString(String format)
      Specified by:
      toString in class Bag
      Parameters:
      format -
      Returns:

    • map

      public BagArray map(Function<Object,Object> function)
      Parameters:
      function -
      Returns:

    • filter

      public BagArray filter(Predicate<Object> predicate)

    • iterator

      public Iterator<Object> iterator()
      Specified by:
      iterator in interface Iterable<Object>

    • select

      public BagArray select(SelectKey selectKey)
      Specified by:
      select in interface Selectable<BagArray>
      Parameters:
      selectKey -
      Returns:

    • sort

      public BagArray sort(SortKey... keys)
      Parameters:
      keys - array of SortKey
      Returns:

    • query

      public BagArray query(BooleanExpr match, SelectKey selectKey)
      Parameters:
      match - a BooleanExpr describing the match criteria
      selectKey - a SelectKey with the values to extract
      Returns:
      array of elements matching the query

    • query

      public BagArray query(BooleanExpr match)
      Parameters:
      match - a BooleanExpr describing the match criteria
      Returns:
      array of elements matching the query

    • queryTree

      public BagArray queryTree(BooleanExpr match, SelectKey selectKey, String childrenName)
      query a tree, assuming a structure of a BagArray of BagObjects where the objects might have children in a named field.
      Parameters:
      match - a BooleanExpr describing the match criteria
      selectKey - a SelectKey with the values to extract
      childrenName - name of a field in found objects that will contain a child or list of children to query
      Returns:
      array of elements matching the query throughout the tree

    • queryTree

      public BagArray queryTree(BooleanExpr match, String childrenName)

    • subset

      public BagArray subset(int start, int count)

    • subset

      public BagArray subset(int start)
      trim only from the end

    • toArray

      public <Type> Type[] toArray(Class<Type> type)