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 Summary

Modifier and Type	Method	Description
`static _longKeyValue`	`_longKeyValue(long key, long value)`
`static <T extends Throwable> T`	`addSuppressed(T throwable, Throwable suppressed)`	As usual, the JDK developers fail to create smoothly usable methods, so one has to clean up after them. Usage: `throw addSuppressed(new SomethingIsWrongException(), e);`
`static <T extends Throwable> T`	`addSuppressed(T throwable, Throwable... suppresseds)`
`static <T> T[]`	`array(T... elements)`
`static <E> E[]`	`Array(int length, E element)`
`static <E> E[]`	`Array(E element)`
`static <E> E[]`	`Array(Class<E> componentType, int length)`
`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.
`static <E> E[]`	`Array(Class<E> componentType, int length, _intIndexedSupplier<E> supplier)`
`static <E> E[]`	`Array(Class<E> componentType, E element)`
`static <E> E[]`	`Array(Class<E> componentType, E element, int length)`
`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)`.
`static <T> T[]`	`ArrayForElementType(T sampleInstance, int length)`
`static <E> E[]`	`ArrayOfSameType(E[] sampleArray)`
`static <E> E[]`	`ArrayOfSameType(E[] sampleArray, int length)`
`static <E> ArrayView<E>`	`ArrayView(E... elements)`
`static VarString`	`assembleString(VarString vs, XGettingCollection<?> collection)`
`RuntimeException`	`asUnchecked(Exception e)`
`static <E> XList<E>`	`asX(List<E> oldList)`
`static <K, V> XMap<K,V>`	`asX(Map<K,V> oldMap)`
`static <E> XSet<E>`	`asX(Set<E> oldSet)`
`static boolean[]`	`booleans(boolean... elements)`
`static Boolean[]`	`box(boolean... values)`
`static Byte[]`	`box(byte... values)`
`static Character[]`	`box(char... values)`
`static Double[]`	`box(double... values)`
`static Float[]`	`box(float... values)`
`static Integer[]`	`box(int... values)`
`static Long[]`	`box(long... values)`
`static Short[]`	`box(short... values)`
`static ThrowBreak`	`BREAK()`
`static byte[]`	`bytes(byte... elements)`
`static char[]`	`chars(char... elements)`
`static void`	`check(BooleanTerm condition)`	Forces the passed condition to evaluate to true by throwing an `Error` otherwise.
`static void`	`check(BooleanTerm condition, String message)`	Forces the passed condition to evaluate to true by throwing an `Error` otherwise.
`static void`	`check(BooleanTerm condition, String message, int stackLevels)`	Forces the passed condition to evaluate to true by throwing an `Error` otherwise.
`static int`	`checkArrayRange(long capacity)`	Central validation point for Java's current technical limitation of max int as max array capacity.
`static <T> T`	`coalesce(T... elements)`
`static <T> T`	`coalesce(T firstElement, T secondElement)`
`static <T> WeakReference<T>[]`	`consolidateWeakReferences(WeakReference<T>[] array)`	Removes all `null` entries and entries with `null`-referents.
`static <E> Constant<E>`	`Constant(E element)`
`static <E> ConstHashEnum<E>`	`ConstEnum(E... elements)`
`static <E> ConstList<E>`	`ConstList(E... elements)`
`static double[]`	`doubles(double... elements)`
`static <T> Empty<T>`	`empty()`
`static <K, V> EmptyTable<K,V>`	`emptyTable()`
`static <E> HashEnum<E>`	`Enum(E... elements)`
`static <E> HashEnum<E>`	`Enum(Iterable<? extends E> elements)`
`static <T> boolean`	`equal(T o1, T o2)`
`static float[]`	`floats(float... elements)`
`static boolean`	`hasNoContent(XGettingCollection<?> collection)`
`static IllegalArgumentException`	`illegalArgument(Object object)`
`static IndexBoundsException`	`IndexBoundsException(long startIndex, long indexBound, long index, String message, int stackTraceCutDepth)`
`static int[]`	`ints(int... elements)`
`static boolean`	`isFalse(Boolean b)`	Helper method to project ternary values to binary logic. Useful for checking "really false" (not true and not unknown).
`static boolean`	`isNotFalse(Boolean b)`	Helper method to project ternary values to binary logic. Useful for checking "really not false" (either true or unknown).
`static boolean`	`isNotNull(Object reference)`
`static boolean`	`isNotTrue(Boolean b)`	Helper method to project ternary values to binary logic. Useful for checking "really not true" (either false or unknown).
`static boolean`	`isNull(Object reference)`
`static boolean`	`isTrue(Boolean b)`	Helper method to project ternary values to binary logic. Useful for checking "really true" (not false and not unknown).
`static <K, V> KeyValue<K,V>`	`KeyValue(K key, V value)`
`static <E> XList<E>`	`List(E... elements)`
`static <E> XList<E>`	`List(Iterable<? extends E> elements)`
`static long[]`	`longs(long... elements)`
`static <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").
`static <E> E[]`	`notEmpty(E[] array)`
`static <S extends Sized> S`	`notEmpty(S sized)`
`static <T> T`	`notNull(T object)`	Transiently ensures the passed object to be not `null` by either returning it in case it is not `null` or throwing a `NullPointerException` otherwise.
`static Object[]`	`objects(Object... elements)`
`static <S> S`	`on(S subject, Consumer<? super S> logic)`	Abbreviation for "execute on".
`static XList<Integer>`	`range(int firstValue, int lastValue)`	Utility method to create a list of integers from `firstValue` to `lastValue`.
`static <T> XReference<T>`	`Reference(T object)`
`static <P extends _intProcedure> P`	`repeat(int startValue, int length, P logic)`
`static <P extends _intProcedure> P`	`repeat(int amount, P logic)`
`static short[]`	`shorts(short... elements)`
`static <E> Singleton<E>`	`Singleton(E element)`
`static String[]`	`strings(String... elements)`
`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.
`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.
`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.
`static <K, V> HashTable<K,V>`	`Table(K key, V value)`
`static <K, V> HashTable<K,V>`	`Table(KeyValue<? extends K,? extends V>... elements)`
`static XList<Integer>`	`times(int n)`	Utility method to create a list of integers from 1 to the passed `n` value.
`static <E> E[]`	`toArray(Iterable<? extends E> iterable, Class<E> type)`	Converts an `Iterable` into an array.
`static byte[]`	`toBytes(int value)`
`static byte[]`	`toBytes(long value)`
`static <T, K, V> KeyValue<K,V>`	`toKeyValue(T instance, Function<? super T,KeyValue<K,V>> mapper)`
`static String`	`toString(XGettingCollection<?> collection)`
`static boolean`	`unbox(Boolean d)`
`static boolean`	`unbox(Boolean d, boolean nullSubstitute)`
`static byte`	`unbox(Byte d)`
`static byte`	`unbox(Byte d, byte nullSubstitute)`
`static char`	`unbox(Character d)`
`static char`	`unbox(Character d, char nullSubstitute)`
`static double`	`unbox(Double d)`
`static double`	`unbox(Double d, double nullSubstitute)`
`static float`	`unbox(Float d)`
`static float`	`unbox(Float d, float nullSubstitute)`
`static int`	`unbox(Integer d)`
`static int[]`	`unbox(Integer[] array)`
`static int[]`	`unbox(Integer[] array, int nullReplacement)`
`static int`	`unbox(Integer d, int nullSubstitute)`
`static long`	`unbox(Long d)`
`static long[]`	`unbox(Long[] array)`
`static long[]`	`unbox(Long[] array, long nullReplacement)`
`static long`	`unbox(Long d, long nullSubstitute)`
`static short`	`unbox(Short d)`
`static short`	`unbox(Short d, short nullSubstitute)`
`static int[]`	`unbox(XGettingCollection<Integer> ints)`
`static int[]`	`unbox(XGettingCollection<Integer> ints, int nullReplacement)`
`static <T> T`	`validate(T value, Predicate<? super T> validator)`
`static <T, E extends Exception> T`	`validate(T value, Predicate<? super T> validator, Function<? super T,E> exceptor)`
`static long`	`validateIndex(long availableLength, long index)`
`static long`	`validateRange(long bound, long startIndex, long length)`
`static <T> WeakReference<T>`	`WeakReference(T referent)`
`static <T> WeakReference<T>[]`	`WeakReferences(int length)`
`static <T> WeakReference<T>[]`	`WeakReferences(T... referents)`

Methods inherited from class java.lang.Object

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

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.

Class X

Method Summary

Methods inherited from class java.lang.Object

Method Details