Package one.microstream

Class X

java.lang.Object
one.microstream.X
public final class X
extends Object
Central class for general utility methods regarding collections, arrays and some basic general functionality that is missing in Java like notNull(Object) or ints(int...).

This class uses the following sound extension of the java naming conventions:
Static methods that resemble a constructor, begin with an upper case letter. This is consistent with existing naming rules: method names begin with a lower case letter EXCEPT for constructor methods. This extension does nothing more than applying the same exception to constructur-like static methods. Resembling a constructor means: 1.) Indicating by name that a new instance is created. 2.) Always returning a new instance, without exception. No caching, no casting. For example: empty() or asX(List) are NOT constructor-like methods because they do not (always) create new instances.

  • Method Details

    • empty

      public static final <T> Empty<T> empty()

    • emptyTable

      public static final <K,​ V> EmptyTable<K,​V> emptyTable()

    • BREAK

      public static ThrowBreak BREAK()

    • checkArrayRange

      public static final int checkArrayRange​(long capacity) throws ArrayCapacityException
      Central validation point for Java's current technical limitation of max int as max array capacity. Note that because of dependencies of many types to arrays (e.g. toArray() methods, etc.), this limitation indirectly affects many other types, for example String, collections, ByteBuffers (which is extremely painful). It can be read that there are plans to overcome this outdated insufficiency for Java 9 or 10, so it's best to have one central point of validation that can later easily be refactored out.
      Parameters:
      capacity - the desired (array-dependent) capacity which may effectively be not greater than Integer.MAX_VALUE.
      Returns:
      the safely downcasted capacity as an int value.
      Throws:
      ArrayCapacityException - if the passed capacity is greater than Integer.MAX_VALUE

    • notNull

      public static final <T> T notNull​(T object) throws NullPointerException
      Transiently ensures the passed object to be not null by either returning it in case it is not null or throwing a NullPointerException otherwise.

      (Really, no idea why java.util.Objects.notNull got renamed to requireNotNull after some odd objection from some guy in the mailing list that the name would be misleading. Of course "notNull" means "the thing you pass has to be not null, otherwise you'll get an exception". What else could the meaning of a transient method named "notNull" be? If "requireNotNull" is needed to express this behavior, than what would "notNull" alone mean?
      In the end, "requireNotNull" is just additional clutter, hence not usable and is replaced by this, still properly named "notNull" method.)

      Type Parameters:
      T - the type of the object to be ensured to be not null.
      Parameters:
      object - the object to be ensured to be not null.
      Returns:
      the passed object, guaranteed to be not null.
      Throws:
      NullPointerException - if null was passed.

    • mayNull

      public static final <T> T mayNull​(T object)
      This method is a complete dummy, simply serving as a semantical counterpart to notNull(Object).
      The use is small, but still there:
      - the sourcecode is easier to read if the same structure is used next to a notNull(Object) call instead of missing method calls and comments (like "may be null" or "optional"). - the IDE can search for all occurances of this method, listing all places where something may be null.
      Type Parameters:
      T - the object's type
      Parameters:
      object - the passed reference.
      Returns:
      the passed reference without doing ANYTHING else.

    • isTrue

      public static final boolean isTrue​(Boolean b)
      Helper method to project ternary values to binary logic.
      Useful for checking "really true" (not false and not unknown).
      Parameters:
      b - a Boolean object.
      Returns:
      false if b is null or false

    • isFalse

      public static final boolean isFalse​(Boolean b)
      Helper method to project ternary values to binary logic.
      Useful for checking "really false" (not true and not unknown).
      Parameters:
      b - a Boolean object.
      Returns:
      false if b is null or true, otherwise true

    • isNotTrue

      public static final boolean isNotTrue​(Boolean b)
      Helper method to project ternary values to binary logic.
      Useful for checking "really not true" (either false or unknown).
      Parameters:
      b - a Boolean object.
      Returns:
      true if b is null or false, otherwise false

    • isNotFalse

      public static final boolean isNotFalse​(Boolean b)
      Helper method to project ternary values to binary logic.
      Useful for checking "really not false" (either true or unknown).
      Parameters:
      b - a Boolean object.
      Returns:
      true if b is null or true, otherwise false

    • isNull

      public static final boolean isNull​(Object reference)

    • isNotNull

      public static final boolean isNotNull​(Object reference)

    • coalesce

      public static final <T> T coalesce​(T firstElement, T secondElement)

    • coalesce

      @SafeVarargs public static final <T> T coalesce​(T... elements)

    • equal

      public static final <T> boolean equal​(T o1, T o2)

    • unbox

      public static final byte unbox​(Byte d)

    • unbox

      public static final byte unbox​(Byte d, byte nullSubstitute)

    • unbox

      public static final boolean unbox​(Boolean d)

    • unbox

      public static final boolean unbox​(Boolean d, boolean nullSubstitute)

    • unbox

      public static final short unbox​(Short d)

    • unbox

      public static final short unbox​(Short d, short nullSubstitute)

    • unbox

      public static final char unbox​(Character d)

    • unbox

      public static final int unbox​(Integer d)

    • unbox

      public static final int unbox​(Integer d, int nullSubstitute)

    • unbox

      public static final char unbox​(Character d, char nullSubstitute)

    • unbox

      public static final float unbox​(Float d)

    • unbox

      public static final float unbox​(Float d, float nullSubstitute)

    • unbox

      public static final long unbox​(Long d)

    • unbox

      public static final long unbox​(Long d, long nullSubstitute)

    • unbox

      public static final double unbox​(Double d)

    • unbox

      public static final double unbox​(Double d, double nullSubstitute)

    • box

      public static final Byte[] box​(byte... values)

    • box

      public static final Boolean[] box​(boolean... values)

    • box

      public static final Short[] box​(short... values)

    • box

      public static final Integer[] box​(int... values)

    • box

      public static final Character[] box​(char... values)

    • box

      public static final Float[] box​(float... values)

    • box

      public static final Long[] box​(long... values)

    • box

      public static final Double[] box​(double... values)

    • unbox

      public static final int[] unbox​(Integer[] array)

    • unbox

      public static final int[] unbox​(Integer[] array, int nullReplacement)

    • unbox

      public static final long[] unbox​(Long[] array)

    • unbox

      public static final long[] unbox​(Long[] array, long nullReplacement)

    • unbox

      public static final int[] unbox​(XGettingCollection<Integer> ints)

    • unbox

      public static final int[] unbox​(XGettingCollection<Integer> ints, int nullReplacement)

    • booleans

      public static boolean[] booleans​(boolean... elements)

    • bytes

      public static byte[] bytes​(byte... elements)

    • toBytes

      public static byte[] toBytes​(int value)

    • toBytes

      public static byte[] toBytes​(long value)

    • shorts

      public static short[] shorts​(short... elements)

    • ints

      public static int[] ints​(int... elements)

    • longs

      public static long[] longs​(long... elements)

    • floats

      public static float[] floats​(float... elements)

    • doubles

      public static double[] doubles​(double... elements)

    • chars

      public static char[] chars​(char... elements)

    • array

      @SafeVarargs public static <T> T[] array​(T... elements)

    • objects

      public static Object[] objects​(Object... elements)

    • strings

      public static String[] strings​(String... elements)

    • times

      public static XList<Integer> times​(int n)
      Utility method to create a list of integers from 1 to the passed n value. Useful for executing a logic via XList.iterate(Consumer) exactely n times.
      Parameters:
      n - the amount of integers
      Returns:
      a list of integers from 1 to n

    • range

      public static XList<Integer> range​(int firstValue, int lastValue)
      Utility method to create a list of integers from firstValue to lastValue.
      Parameters:
      firstValue - the lower limit
      lastValue - the upper limit
      Returns:
      a list of integers from firstValue to lastValue

    • List

      @SafeVarargs public static <E> XList<E> List​(E... elements)

    • List

      public static <E> XList<E> List​(Iterable<? extends E> elements)

    • ConstList

      @SafeVarargs public static <E> ConstList<E> ConstList​(E... elements) throws NullPointerException
      Throws:
      NullPointerException

    • ArrayView

      @SafeVarargs public static <E> ArrayView<E> ArrayView​(E... elements)

    • Singleton

      public static <E> Singleton<E> Singleton​(E element)

    • Constant

      public static <E> Constant<E> Constant​(E element)

    • Enum

      @SafeVarargs public static <E> HashEnum<E> Enum​(E... elements)

    • Enum

      public static <E> HashEnum<E> Enum​(Iterable<? extends E> elements)

    • ConstEnum

      @SafeVarargs public static <E> ConstHashEnum<E> ConstEnum​(E... elements) throws NullPointerException
      Throws:
      NullPointerException

    • Table

      public static <K,​ V> HashTable<K,​V> Table​(K key, V value)

    • Table

      @SafeVarargs public static <K,​ V> HashTable<K,​V> Table​(KeyValue<? extends K,​? extends V>... elements)

    • Reference

      public static <T> XReference<T> Reference​(T object)

    • Iterable

      public static Iterable<?> Iterable​(Object array)

    • ArrayForElementType

      public static final <T> T[] ArrayForElementType​(T sampleInstance, int length)

    • ArrayOfSameType

      public static <E> E[] ArrayOfSameType​(E[] sampleArray, int length)

    • ArrayOfSameType

      public static final <E> E[] ArrayOfSameType​(E[] sampleArray)

    • Array

      public static <E> E[] Array​(E element)

    • Array

      public static <E> E[] Array​(int length, E element)

    • Array

      public static <E> E[] Array​(Class<E> componentType, E element)

    • Array

      public static <E> E[] Array​(Class<E> componentType, E element, int length)

    • Array

      public static <E> E[] Array​(Class<E> componentType, int length)

    • Array

      public static <T,​ E extends T> T[] Array​(Class<T> type, XGettingCollection<E> collection)
      Static workaround for the Java typing deficiency that it is not possible to define public <T super E> T[] toArray(Class<T> type).
      Type Parameters:
      E - the collection's element type.
      T - the component type used to create the array, possibly a super type of E
      Parameters:
      collection - the collection whose elements shall be copied to the array.
      type - the Class representing type T at runtime.
      Returns:
      a new array instance of component type T containing all elements of the passed collection.

    • Array

      public static <E> E[] Array​(Class<E> componentType, int length, Supplier<E> supplier)
      Instantiaties a new array instance that has a compent type defined by the passed Class componentType, a length as defined by the passed length value and that is filled in order with elements supplied by the passed Supplier instance.
      Type Parameters:
      E - the component type
      Parameters:
      length - the length of the array to be created.
      componentType - the component type of the array to be created.
      supplier - the function supplying the instances that make up the array's elements.
      Returns:
      a new array instance filled with elements provided by the passed supplier.
      See Also:
      Array(Class, int, Supplier)

    • Array

      public static <E> E[] Array​(Class<E> componentType, int length, _intIndexedSupplier<E> supplier)

    • WeakReference

      public static <T> WeakReference<T> WeakReference​(T referent)

    • WeakReferences

      public static <T> WeakReference<T>[] WeakReferences​(int length)

    • WeakReferences

      @SafeVarargs public static <T> WeakReference<T>[] WeakReferences​(T... referents)

    • consolidateWeakReferences

      public static <T> WeakReference<T>[] consolidateWeakReferences​(WeakReference<T>[] array)
      Removes all null entries and entries with null-referents.
      Type Parameters:
      T - the component type
      Parameters:
      array - the array to consolidate
      Returns:
      the consolidated array with non-null values

    • asX

      public static <E> XList<E> asX​(List<E> oldList)

    • asX

      public static <E> XSet<E> asX​(Set<E> oldSet)

    • asX

      public static <K,​ V> XMap<K,​V> asX​(Map<K,​V> oldMap)

    • hasNoContent

      public static boolean hasNoContent​(XGettingCollection<?> collection)

    • notEmpty

      public static final <S extends Sized> S notEmpty​(S sized)

    • notEmpty

      public static final <E> E[] notEmpty​(E[] array)

    • toKeyValue

      public static <T,​ K,​ V> KeyValue<K,​V> toKeyValue​(T instance, Function<? super T,​KeyValue<K,​V>> mapper)

    • KeyValue

      public static <K,​ V> KeyValue<K,​V> KeyValue​(K key, V value)

    • _longKeyValue

      public static _longKeyValue _longKeyValue​(long key, long value)

    • toString

      public static String toString​(XGettingCollection<?> collection)

    • assembleString

      public static VarString assembleString​(VarString vs, XGettingCollection<?> collection)

    • synchronize

      public static <E> XList<E> synchronize​(XList<E> list)
      Ensures that the returned XList instance based on the passed list is thread safe to use.
      This normally means wrapping the passed list in a SynchList, making it effectively synchronized.
      If the passed list already is thread safe (indicated by the marker interface ThreadSafe), then the list itself is returned without further actions. This automatically ensures that a SynchList is not redundantly wrapped again in another SynchList.
      Type Parameters:
      E - the element type.
      Parameters:
      list - the XList instance to be synchronized.
      Returns:
      a thread safe XList using the passed list.

    • synchronize

      public static <E> XSet<E> synchronize​(XSet<E> set)
      Ensures that the returned XSet instance based on the passed set is thread safe to use.
      This normally means wrapping the passed set in a SynchSet, making it effectively synchronized.
      If the passed set already is thread safe (indicated by the marker interface ThreadSafe), then the set itself is returned without further actions. This automatically ensures that a SynchSet is not redundantly wrapped again in another SynchSet.
      Type Parameters:
      E - the element type.
      Parameters:
      set - the XSet instance to be synchronized.
      Returns:
      a thread safe XSet using the passed set.

    • synchronize

      public static <E> XCollection<E> synchronize​(XCollection<E> collection)
      Ensures that the returned XCollection instance based on the passed collection is thread safe to use.
      This normally means wrapping the passed collection in a SynchCollection, making it effectively synchronized.
      If the passed collection already is thread safe (indicated by the marker interface ThreadSafe), then the collection itself is returned without further actions. This automatically ensures that a SynchCollection is not redundantly wrapped again in another SynchCollection.
      Type Parameters:
      E - the element type.
      Parameters:
      collection - the XCollection instance to be synchronized.
      Returns:
      a thread safe XCollection using the passed collection.

    • toArray

      public static <E> E[] toArray​(Iterable<? extends E> iterable, Class<E> type)
      Converts an Iterable into an array.
      Type Parameters:
      E - the element type.
      Parameters:
      iterable - the iterable to convert
      type - the component type of the array to be created
      Returns:
      an array containing the values of the iterable

    • addSuppressed

      public static final <T extends Throwable> T addSuppressed​(T throwable, Throwable suppressed)

    • addSuppressed

      public static final <T extends Throwable> T addSuppressed​(T throwable, Throwable... suppresseds)

    • asUnchecked

      public RuntimeException asUnchecked​(Exception e)

    • on

      public static final <S> S on​(S subject, Consumer<? super S> logic)
      Abbreviation for "execute on". Read as "on [subject] execute [logic]" Nifty little helper logic that allows to execute custom logic on a subject instance but still return that instance. Useful for method chaining.
      Type Parameters:
      S - the subject's type
      Parameters:
      subject - the subject to execute the logic on
      logic - the logic to execute
      Returns:
      the subject

    • check

      public static void check​(BooleanTerm condition) throws Error
      Forces the passed condition to evaluate to true by throwing an Error otherwise.
      Parameters:
      condition - the condition to check
      Throws:
      Error - if the passed condition fails.

    • check

      public static void check​(BooleanTerm condition, String message) throws Error
      Forces the passed condition to evaluate to true by throwing an Error otherwise.
      Parameters:
      condition - the condition to check
      message - the custom error message
      Throws:
      Error - if the passed condition fails.

    • check

      public static void check​(BooleanTerm condition, String message, int stackLevels) throws Error
      Forces the passed condition to evaluate to true by throwing an Error otherwise.
      Parameters:
      condition - the condition to check
      message - the custom error message
      stackLevels - the amount of stack levels for the resulting error
      Throws:
      Error - if the passed condition fails.

    • validate

      public static <T> T validate​(T value, Predicate<? super T> validator) throws IllegalArgumentException
      Throws:
      IllegalArgumentException

    • illegalArgument

      public static IllegalArgumentException illegalArgument​(Object object)

    • validate

      public static <T,​ E extends Exception> T validate​(T value, Predicate<? super T> validator, Function<? super T,​E> exceptor) throws E extends Exception
      Throws:
      E extends Exception

    • repeat

      public static <P extends _intProcedure> P repeat​(int amount, P logic)

    • repeat

      public static <P extends _intProcedure> P repeat​(int startValue, int length, P logic)

    • repeat

      public static <P extends Runnable> P repeat​(int amount, P logic)

    • repeat

      public static <P extends Runnable> P repeat​(int startValue, int length, P logic)

    • validateIndex

      public static final long validateIndex​(long availableLength, long index) throws IndexBoundsException
      Throws:
      IndexBoundsException

    • validateRange

      public static final long validateRange​(long bound, long startIndex, long length)

    • IndexBoundsException

      public static final IndexBoundsException IndexBoundsException​(long startIndex, long indexBound, long index, String message, int stackTraceCutDepth)