Package io.permazen.encoding

Class StringEncoding

java.lang.Object
io.permazen.encoding.AbstractEncoding<String>
io.permazen.encoding.StringEncoding
All Implemented Interfaces:
Encoding<String>, NaturalSortAware, Serializable, Comparator<String>
public class StringEncoding extends AbstractEncoding<String>
String encoding. Null values are not supported by this class.

Strings are encoded as a sequence of characters followed by 0x00, where each character is encoded via UnsignedIntEncoder, with the special exception that the characters 0x0000 and 0x0001 are prefixed with a 0x01 byte to avoid writing a 0x00. We rely on the fact that UnsignedIntEncoder encodes 0 and 1 as 0x00 and 0x01, respectively. As a result of this encoding, this encoding sortsNaturally().

See Also:

  • Constructor Details

    • StringEncoding

      public StringEncoding(EncodingId encodingId)

  • Method Details

    • withEncodingId

      public StringEncoding withEncodingId(EncodingId encodingId)
      Description copied from interface: Encoding
      Build an encoding that has the given EncodingId but is otherwise equivalent to this encoding.

      If this encoding already has encodingId, then this method may (but is not required to) return this same instance.

      Parameters:
      encodingId - new encoding's EncodingId, or null for an anonymized encoding
      Returns:
      a version of this encoding with the given EncodingId

    • read

      public String read(ByteReader reader)
      Description copied from interface: Encoding
      Read a value from the given input.
      Parameters:
      reader - byte input
      Returns:
      field value (possibly null)

    • write

      public void write(ByteWriter writer, String value)
      Description copied from interface: Encoding
      Write a value to the given output.
      Parameters:
      writer - byte output
      value - value to write (possibly null)

    • skip

      public void skip(ByteReader reader)
      Description copied from interface: Encoding
      Read and discard a byte[] encoded value from the given input.
      Parameters:
      reader - byte input

    • toString

      public String toString(String value)
      Encode the given non-null value as a String.

      Because Encoding.toString() disallows XML-invalid characters, the returned string is not always equal to value. Instead, the implementation in StringEncoding delegates to StringEncoder.encode() to backslash-escape invalid characters.

      Parameters:
      value - string value, never null
      Returns:
      backslash-escaped value
      Throws:
      IllegalArgumentException - if value is null
      See Also:

    • fromString

      public String fromString(String string)
      Parse a non-null value previously encoded by toString().

      The implementation in StringEncoding delegates to StringEncoder.decode().

      Parameters:
      string - non-null value previously encoded by toString()
      Returns:
      decoded value
      Throws:
      IllegalArgumentException - if string is invalid
      IllegalArgumentException - if string is null

    • hasPrefix0xff

      public boolean hasPrefix0xff()
      Description copied from interface: Encoding
      Determine whether any of this encoding's encoded values start with a 0xff byte. Certain optimizations are possible when this is not the case. It is safe for this method to always return true.

      Note: changing the result of this method may result in an incompatible encoding if this encoding is wrapped in another class.

      The implementation in Encoding returns true.

      Returns:
      true if an encoded value starting with 0xff exists

    • compare

      public int compare(String string1, String string2)
      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.

    • sortsNaturally

      public boolean sortsNaturally()
      Description copied from interface: NaturalSortAware
      Determine if this instance sorts Java instances naturally.

      This method should return true only if all of the following are true:

      • This class also implements Comparator for some Java type T.
      • Type T has a natural ordering (i.e., T itself implements Comparable).
      • The ordering implied by this class's compare() method is identical to T's natural ordering.
      Returns:
      true if this instance orders Java values in their natural order

    • convert

      public <S> String 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 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