Package io.permazen.encoding

Class ArrayEncoding<T,E>

java.lang.Object
io.permazen.encoding.AbstractEncoding<T>
io.permazen.encoding.ArrayEncoding<T,E>
Type Parameters:
T - array type
E - array element type
All Implemented Interfaces:
Encoding<T>, NaturalSortAware, Serializable, Comparator<T>
Direct Known Subclasses:
Base64ArrayEncoding, BooleanArrayEncoding, CharacterArrayEncoding, ObjectArrayEncoding
public abstract class ArrayEncoding<T,E> extends AbstractEncoding<T>
Support superclass for built-in array Encodings.

The string form looks like [ "elem1", "elem2", ..., "elemN" ].

This class does not support null arrays; wrap in NullSafeEncoding to get that. The default value is the empty array.

Arrays sort lexicographically.

See Also:

  • Constructor Details

  • Method Details

    • getElementEncoding

      public Encoding<E> getElementEncoding()
      Get the element type.
      Returns:
      element type

    • toString

      public String toString(T array)
      Description copied from interface: Encoding
      Encode a non-null value as a String for later decoding by fromString().

      Each of the characters in the returned String must be one of the valid XML characters (tab, newline, carriage return, \u0020 - \ud7ff, and \ue000 - \ufffd).

      Parameters:
      array - actual value, never null
      Returns:
      string encoding of value acceptable to fromString()
      See Also:

    • fromString

      public T fromString(String string)
      Description copied from interface: Encoding
      Parse a non-null value previously encoded by toString(T).
      Parameters:
      string - non-null value previously encoded as a String by toString(T)
      Returns:
      actual value

    • compare

      public int compare(T array1, T array2)
      Description copied from interface: Encoding
      Order two field values.

      This method must provide a total ordering of all supported Java values that is consistent with the database ordering, i.e., the unsigned lexicographical ordering of the corresponding byte[] encoded field values.

      If null is a supported Java value, then the this method must accept null parameters without throwing an exception (note, this is a stronger requirement than the Comparator interface normally requires).

      Note: by convention, null values usually sort last.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class AbstractEncoding<T>

    • equals

      public boolean equals(Object obj)
      Specified by:
      equals in interface Comparator<T>
      Overrides:
      equals in class AbstractEncoding<T>

    • convert

      public <S> T convert(Encoding<S> type, S value)
      Description copied from interface: Encoding
      Attempt to convert a value from the given Encoding into a value of this Encoding.

      For a non-null value, the implementation in Encoding first checks whether the value is already a valid value for this encoding; if so, the value is returned. Otherwise, it invokes encoding.toString(value) to convert value into a String, and then attempts to parse that string via this.fromString(); if the parse fails, an IllegalArgumentException is thrown. Note this means that any value will convert successfully to a String, as long as it doesn't contain an invalid escape sequence (see StringEncoding.toString(java.lang.String)).

      If value is null, the implementation in Encoding returns null, unless this encoding does not support null values, in which case an IllegalArgumentException is thrown.

      Permazen's built-in encodings include the following conversions:

      • Non-boolean Primitive types:
        • Convert from other non-boolean primitive types as if by the corresponding Java cast
        • Convert from boolean by converting to zero (if false) or one (if true)
      • Boolean: converts from other primitive types as if by value != 0
      • A char[] array and a String are convertible to each other
      • A char and a String of length one are convertible to each other (other Strings are not)
      • Arrays: converted by converting each array element individually (if possible)
      Type Parameters:
      S - source encoding
      Parameters:
      type - the Encoding of value
      value - the value to convert
      Returns:
      value converted to this instance's type

    • toArrayString

      public static String toArrayString(String[] strings, boolean spacing)
      Create a single, combined String representation of an array of Strings.
      Parameters:
      strings - the individual strings
      spacing - true to include spaces around each element
      Returns:
      combined array string
      Throws:
      IllegalArgumentException - if strings is null

    • fromArrayString

      public static String[] fromArrayString(String string)
      Parse a combined String representation of an array of Strings and return the individual strings.

      This method inverts ArrayEncoding.toArrayString(). Extra whitespace is ignored.

      Parameters:
      string - the array string
      Returns:
      array of original strings
      Throws:
      IllegalArgumentException - if string is null

    • getArrayLength

      protected abstract int getArrayLength(T array)
      Get the length of the given array.
      Parameters:
      array - non-null array
      Returns:
      array length

    • getArrayElement

      protected abstract E getArrayElement(T array, int index)
      Get an element from the given array.
      Parameters:
      array - non-null array
      index - index of target element in array
      Returns:
      array element at index index

    • createArray

      protected abstract T createArray(List<E> elements)
      Create a new array instance containing the given elements.
      Parameters:
      elements - content for the new array
      Returns:
      newly created array