com.prosysopc.ua.stack.utils

Class MultiDimensionArrayUtils

java.lang.Object

com.prosysopc.ua.stack.utils.MultiDimensionArrayUtils

public class MultiDimensionArrayUtils
extends Object

Multi-dimension array utils.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MultiDimensionArrayUtils.ArrayIterator<T>

Constructor Summary

Constructors

Constructor and Description
MultiDimensionArrayUtils()

Method Summary

Modifier and Type	Method and Description
static Class<?>	arrayClassOf(Class<?> clazz, int dimensions) Returns a equivalent Class object that is an array Class with the given dimensions.
static <R> MultiDimensionArrayUtils.ArrayIterator<R>	arrayIterator(Object array, int[] dimLens) arrayIterator.
static boolean	checkValueAgainstInstrumentRange(Variant variantValue, Range range, NodeId dataTypeId) Checks if the value of a Variant is within the InstrumentRange of target UaValueNode.
static Object	clone(Object array) Clones the multi-dimension structure of an array but the not the individual elements.
static Object[]	createMultiDimArray(Class<?> componentType, int[] dims) Deep create multi-level array.
static <T,E extends Exception> Object[]	createMultiDimArray(Class<T> componentType, int[] dims, CheckedFunction<int[],T,E> generator) Deep create multi-level array.
static Object	deepClone(Object array) Deep clone structure and elements.
static <E extends Exception> void	deepForEach(Object data, CheckedConsumer<Object,E> operation) Similar to #forEachIndexed(Object, Class, CheckedConsumer), but the given operation is recursively called for elements of data that are arrays (it is not called for the "intermediate array objects").
static Object	deepGet(Object array, int... selector) Selects a part of an array and returns it.
static Object	deepGet(Object array, List<Integer> selector) Selects a part of an array and returns it.
static void	deepSet(Object array, Object newValue, int... selector) Sets a value to a multidimensional array for the selected index.
static void	deepSet(Object array, Object newValue, List<Integer> selector) Sets a value to a multidimensional array for the selected index.
static Object	demuxArray(Object src, int[] dims) Demux single-dimension array (x[]) to a multi-dimension array (x[][][]).
static Object	demuxArray(Object src, int[] dims, Class<?> componentType) Demux single-dimension array (x[]) to a multi-dimension array (x[][][]).
static void	demuxArray(Object src, int[] dims, Object dst) Demuxes single dimension array into a multi-dimension array.
static <T,E extends Exception> void	forEach(Object data, Class<T> componentClass, CheckedConsumer<T,E> operation) Applies the given operation for each "element" of the data.
static <T,E extends Exception> void	forEachIndexed(Object data, Class<T> componentClass, CheckedBiConsumer<T,int[],E> operation) Same as forEach(Object, Class, CheckedConsumer) , but additionally provides the indexes of the given element.
static int[]	getArrayLengths(Object value) Get array length of each dimension of a multi-dimension array.
static int	getClassDimensions(Class<?> clazz) Get the number of dimensions the class has.
static <T extends Cloneable> Method	getCloneMethod(Class<T> clazz) Returns Method for the given class that can be used to call clone via reflection.
static Class<?>	getComponentType(Class<?> clazz) Get the component type of an array class.
static int	getDimension(Object value) Get the number of dimensions in a multi-dimension array.
static int	getLength(int[] dims) Returns the total number of elements in a multi-dimension array.
static <S,T,E extends Exception> Object	map(Object data, Class<S> sourceComponentClass, Class<T> targetComponentClass, CheckedFunction<? super S,? extends T,E> transformer) Converts the given data with the given transformer and returns the output, that is of the same dimension.
static <S,T,E extends Exception> Object	mapIndexed(Object data, Class<S> sourceComponentClass, Class<T> targetComponentClass, CheckedBiFunction<? super S,int[],? extends T,E> transformer) Same as map(Object, Class, Class, CheckedFunction), but additionally provides the indexes of the given element to map.
static Object	muxArray(Object src) Multiplex multi-dimension array (x[][][]) to single-dimension array (x[]).
static Object	muxArray(Object src, int[] dims) Multiplex multi-dimension array (x[][][]) to single-dimension array (x[]).
static Object	muxArray(Object src, int[] dims, Class<?> componentType) Multiplex multi-dimension array (x[][][]) to single-dimension array (x[]).
static void	muxArray(Object src, int[] dims, Object dst) Multiplexes multi-dimension array into a single-dimension array.
static void	printArrayDeep(Object value, PrintStream out) Print multi-dimension array.
static <T,E extends Exception> void	replaceAll(Object data, Class<T> componentClass, CheckedBiFunction<T,int[],T,E> transformer) Replaces in-place all elements in the given array (of any dimension) using the given transformer.
static <T,E extends Exception> Object	resize(Object array, Class<T> componentType, int[] newDimensions) Returns a new array with the given dimensions.
static <T,E extends Exception> Object	resize(Object array, Class<T> componentType, int[] newDimensions, CheckedFunction<int[],T,E> generator) Returns a new array with the given dimensions.
static <T,E extends Exception> void	setAll(Object data, Class<T> componentClass, CheckedFunction<int[],T,E> generator) Sets all elements of the given array (of any dimension) using the given generator function to compute each element.
static String	toString(Object object) Format object to String.
static String	toString(Object object, EncoderContext ctx) Format object to String, try decoding ExtensionObjects with the given context.

Methods inherited from class java.lang.Object

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

Constructor Detail

MultiDimensionArrayUtils

public MultiDimensionArrayUtils()

Method Detail

arrayClassOf

public static Class<?> arrayClassOf(Class<?> clazz,
                                    int dimensions)

Returns a equivalent Class object that is an array Class with the given dimensions.

Parameters:

clazz - class to make array Class variant out of

dimensions - the number of dimensions the class will have

Returns:

the array class variant of the given class with number of given dimensions

Throws:

IllegalArgumentException - if given negative dimensions

arrayIterator

public static <R> MultiDimensionArrayUtils.ArrayIterator<R> arrayIterator(Object array,
                                                                          int[] dimLens)

arrayIterator.

Type Parameters:

R - a R object.

Parameters:

array - a Object object.

dimLens - an array of int.

Returns:

a MultiDimensionArrayUtils.ArrayIterator object.

checkValueAgainstInstrumentRange

public static boolean checkValueAgainstInstrumentRange(Variant variantValue,
                                                       Range range,
                                                       NodeId dataTypeId)

Checks if the value of a Variant is within the InstrumentRange of target UaValueNode.

Parameters:

variantValue - the new value

range - the InstrumentRange

valueNode - the target UaValueNode

Returns:

true if the new value is within the InstrumentRange and false otherwise

clone

public static Object clone(Object array)

Clones the multi-dimension structure of an array but the not the individual elements. Element references remain the same is in the original.

Parameters:

array - a Object object.

Returns:

cloned array

createMultiDimArray

public static Object[] createMultiDimArray(Class<?> componentType,
                                           int[] dims)

Deep create multi-level array.

Parameters:

componentType - component type

dims - dimension lengths

Returns:

multi-level array

createMultiDimArray

public static <T,E extends Exception> Object[] createMultiDimArray(Class<T> componentType,
                                                                   int[] dims,
                                                                   CheckedFunction<int[],T,E> generator)
                                                            throws E extends Exception

Deep create multi-level array. The given generator function is called for each position in the array (see MultiDimensionArrayUtils.ArrayIterator.getIndices()).

Parameters:

componentType - component type

dims - dimension lengths

Returns:

multi-level array

Throws:

E extends Exception

deepClone

public static Object deepClone(Object array)

Deep clone structure and elements. Elements are cloned if they are cloneable, otherwise references are copied.

Parameters:

array - a Object object.

Returns:

a Object object.

deepForEach

public static <E extends Exception> void deepForEach(Object data,
                                                     CheckedConsumer<Object,E> operation)
                                              throws E extends Exception

Similar to #forEachIndexed(Object, Class, CheckedConsumer), but the given operation is recursively called for elements of data that are arrays (it is not called for the "intermediate array objects"). Throws any exception thrown by the given operation. The results are undefined if the array refers itself in any element.

Throws:

E extends Exception

deepGet

public static Object deepGet(Object array,
                             int... selector)

Selects a part of an array and returns it. For example a call to this with deepGet(arr, x, y, z) would be equal to arr[x][y][z].

deepGet

public static Object deepGet(Object array,
                             List<Integer> selector)

Selects a part of an array and returns it. See deepGet(Object, int...) for an example.

deepSet

public static void deepSet(Object array,
                           Object newValue,
                           int... selector)

Sets a value to a multidimensional array for the selected index. The newValue must be of suitable dimensions for the selected element or scalar if selector contains as many elements as the dimensions of the given array. For example, a call to this method with "deepSet(arr, "NewValue", x, y, z)" would be equal to arr[x][y][z] = "NewValue".

deepSet

public static void deepSet(Object array,
                           Object newValue,
                           List<Integer> selector)

Sets a value to a multidimensional array for the selected index. The newValue must be of suitable dimensions for the selected element or scalar if selector contains as many elements as the dimensions of the given array. See deepSet(Object, Object, int...) for an example.

demuxArray

public static Object demuxArray(Object src,
                                int[] dims)

Demux single-dimension array (x[]) to a multi-dimension array (x[][][]).

Parameters:

src - single-dimension array

dims - an array of int.

Returns:

multi-dimension array

demuxArray

public static Object demuxArray(Object src,
                                int[] dims,
                                Class<?> componentType)

Demux single-dimension array (x[]) to a multi-dimension array (x[][][]).

Parameters:

src - single-dimension array

dims - an array of int.

componentType - a Class object.

Returns:

multi-dimension array

demuxArray

public static void demuxArray(Object src,
                              int[] dims,
                              Object dst)

Demuxes single dimension array into a multi-dimension array.

Parameters:

src - one dimension array (e.g. int[])

dims - length of each dimension

dst - multi-dimension array to be filled (use createMultiDimArray())

forEach

public static <T,E extends Exception> void forEach(Object data,
                                                   Class<T> componentClass,
                                                   CheckedConsumer<T,E> operation)
                                            throws E extends Exception

Applies the given operation for each "element" of the data. Does nothing if given data is null. For scalar inputs applies the operation for the input. For arrays and multidimensional arrays applies the operation for each element (note that if the given data contains arrays with null elements, then then operation is called with null). If the given operation throws, this method will throw that exception. Throws IllegalArgumentException if the given data elements cannot be casted to the given component class.

Type Parameters:

T - Component type.

E - Exception (if any) thrown by the operation

Parameters:

data - Scalar or anydimensional array to whose elements the operation is applied

componentClass - class of the components i.e. elements of the array

operation - The operation to perform for each element. The second parameter is the position of the element (see MultiDimensionArrayUtils.ArrayIterator.getIndices(); for scalar data this is an empty array).

Throws:

E - Throws if the operation throws.

E extends Exception

forEachIndexed

public static <T,E extends Exception> void forEachIndexed(Object data,
                                                          Class<T> componentClass,
                                                          CheckedBiConsumer<T,int[],E> operation)
                                                   throws E extends Exception

Same as forEach(Object, Class, CheckedConsumer) , but additionally provides the indexes of the given element. Scalar (non-null) inputs receive empty int[] array.

Throws:

E extends Exception

getArrayLengths

public static int[] getArrayLengths(Object value)

Get array length of each dimension of a multi-dimension array.

Parameters:

value - multi-dimension array

Returns:

lengths of each dimension

getClassDimensions

public static int getClassDimensions(Class<?> clazz)

Get the number of dimensions the class has. 0 if not array. Returns 0 if given null.

getCloneMethod

public static <T extends Cloneable> Method getCloneMethod(Class<T> clazz)
                                                   throws Exception

Returns Method for the given class that can be used to call clone via reflection. Note that this method is mainly intended for SDK internal use (public due to uses from multiple packages) and may change in the future. Returns cached results for subsequent calls per Class (cleared on StackUtils.shutdown()). Throws if the method is not found (which in general should be a coding mistake as every Cloneable should have public clone method).

Throws:

Exception

getComponentType

public static Class<?> getComponentType(Class<?> clazz)

Get the component type of an array class. Returns null if given null.

Parameters:

clazz - (array) class

Returns:

component type

getDimension

public static int getDimension(Object value)

Get the number of dimensions in a multi-dimension array. Single-dimension arrays return 1. Null and scalars return 0.

Parameters:

value - multi-dimension array

Returns:

the number of dimensions

getLength

public static int getLength(int[] dims)

Returns the total number of elements in a multi-dimension array.

Parameters:

dims - lengths of each dimension

Returns:

total number of elements

map

public static <S,T,E extends Exception> Object map(Object data,
                                                   Class<S> sourceComponentClass,
                                                   Class<T> targetComponentClass,
                                                   CheckedFunction<? super S,? extends T,E> transformer)
                                            throws E extends Exception

Converts the given data with the given transformer and returns the output, that is of the same dimension. That is, for null this method returns null, for scalar a scalar, for array an array and so on. The given data (elements) must be assignable to the given sourceComponentClass. Throws IllegalArgumentException if mapping fails (also throws anything the given transformer throws). The return for non-null data will be of the targetComponentClass having the same dimensions as the given data.

Throws:

E extends Exception

mapIndexed

public static <S,T,E extends Exception> Object mapIndexed(Object data,
                                                          Class<S> sourceComponentClass,
                                                          Class<T> targetComponentClass,
                                                          CheckedBiFunction<? super S,int[],? extends T,E> transformer)
                                                   throws E extends Exception

Same as map(Object, Class, Class, CheckedFunction), but additionally provides the indexes of the given element to map. Scalar transformation use an empty array as the indexes.

Throws:

E extends Exception

muxArray

public static Object muxArray(Object src)

Multiplex multi-dimension array (x[][][]) to single-dimension array (x[]).

Parameters:

src - multi-dimension array

Returns:

single-dimension array

muxArray

public static Object muxArray(Object src,
                              int[] dims)

Multiplex multi-dimension array (x[][][]) to single-dimension array (x[]).

Parameters:

src - multi-dimension array

dims - an array of int.

Returns:

single-dimension array

muxArray

public static Object muxArray(Object src,
                              int[] dims,
                              Class<?> componentType)

Multiplex multi-dimension array (x[][][]) to single-dimension array (x[]).

Parameters:

src - multi-dimension array

dims - an array of int.

componentType - a Class object.

Returns:

single-dimension array

muxArray

public static void muxArray(Object src,
                            int[] dims,
                            Object dst)

Multiplexes multi-dimension array into a single-dimension array.

Parameters:

src - multi-dimension array

dims - dimensions

dst - single-dimension array

printArrayDeep

public static void printArrayDeep(Object value,
                                  PrintStream out)

Print multi-dimension array.

Parameters:

value - a Object object.

out - output stream

replaceAll

public static <T,E extends Exception> void replaceAll(Object data,
                                                      Class<T> componentClass,
                                                      CheckedBiFunction<T,int[],T,E> transformer)
                                               throws E extends Exception

Replaces in-place all elements in the given array (of any dimension) using the given transformer. The second parameter in the transformer is the position of the element (see MultiDimensionArrayUtils.ArrayIterator.getIndices()). Throws if the given transformer throws.

Throws:

E extends Exception

resize

public static <T,E extends Exception> Object resize(Object array,
                                                    Class<T> componentType,
                                                    int[] newDimensions)

Returns a new array with the given dimensions. Existing elements from the old array are assigned to equivalent indexes in the new array wherever possible (shallow copy, elements itself are not cloned). For indexes that do not correspond to the elements in the old array are set to null.

If the new dimensions are smaller than the old dimensions, the data from the old array is truncated, only data from the index [0][0]... (repeated for the difference in dimensions) is used. Conversely, if the new dimensions are larger than the old dimensions, the old data indexes are treated as-if prefixed with [0][0]... (repeated for the difference in dimensions).

Type Parameters:

T - Expected element type.

E - Exception (if any) type thrown by the given generator.

Parameters:

array - the original array to clone. The dimensions shall be rectangular, i.e. the array must be representable as array[][]....[] with known size for all dimensions. Shall not be be an array of primitives.

componentType - element Class the array has.

newDimensions - the dimensions of the array to return.

Returns:

the new cloned array

Throws:

E - any exception thrown from the generator

resize

public static <T,E extends Exception> Object resize(Object array,
                                                    Class<T> componentType,
                                                    int[] newDimensions,
                                                    CheckedFunction<int[],T,E> generator)
                                             throws E extends Exception

Returns a new array with the given dimensions. Existing elements from the old array are assigned to equivalent indexes in the new array wherever possible (shallow copy, elements itself are not cloned). For indexes that do not correspond to the elements in the old array the given generator function is used to compute value for that index.

If the new dimensions are smaller than the old dimensions, the data from the old array is truncated, only data from the index [0][0]... (repeated for the difference in dimensions) is used. Conversely, if the new dimensions are larger than the old dimensions, the old data indexes are treated as-if prefixed with [0][0]... (repeated for the difference in dimensions).

Type Parameters:

T - Expected element type.

E - Exception (if any) type thrown by the given generator.

Parameters:

array - the original array to clone. The dimensions shall be rectangular, i.e. the array must be representable as array[][]....[] with known size for all dimensions. Shall not be be an array of primitives.

componentType - element Class the array has.

newDimensions - the dimensions of the array to return.

generator - Generator function to initialize new elements, the input is the position in the array (see MultiDimensionArrayUtils.ArrayIterator.getIndices()).

Returns:

the new cloned array

Throws:

E - any exception thrown from the generator

E extends Exception

setAll

public static <T,E extends Exception> void setAll(Object data,
                                                  Class<T> componentClass,
                                                  CheckedFunction<int[],T,E> generator)
                                           throws E extends Exception

Sets all elements of the given array (of any dimension) using the given generator function to compute each element. Throws, if the generator function throws. If you need access to existing elements, use replaceAll(Object, Class, CheckedBiFunction) instead.

Throws:

E extends Exception

toString

public static String toString(Object object)

Format object to String. Does not decode ExtensionObjects (use toString(Object, EncoderContext) for that).

Parameters:

object - a Object object.

Returns:

string representation of the object

toString

public static String toString(Object object,
                              EncoderContext ctx)

Format object to String, try decoding ExtensionObjects with the given context. Uses ExtensionObject.toString() if decoding fails.

Parameters:

object - the object

ctx - context to use for ExtensionObject decoding, can be null, in which case no decoding is attempted

Returns:

String representation of the object