Module org.jhotdraw8.base
Package org.jhotdraw8.base.converter

Interface Converter<T>

Type Parameters:
T - the data type
All Known Subinterfaces:
ResolvingConverter<T>
All Known Implementing Classes:
CaseInsensitiveMappedConverter, ConverterFormatAdapter, DefaultConverter, DoubleConverter, FloatConverter, IntegerConverter, MappedConverter, NumberConverter
public interface Converter<T>
Converts a data value of type T from or to a String representation.

This interface is designed so that it can be adapted to the various String conversion APIs in the JDK.

Author:
Werner Randelshofer

  • Method Details

    • fromString

      default @Nullable T fromString(@NonNull CharSequence in, @Nullable IdResolver idResolver) throws ParseException
      Constructs a value from a string.

      The converter should try to create the value greedily, by consuming as many characters as possible for the value.

      This method does not change the state of the converter.

      Parameters:
      in - A char buffer which holds the string. The char buffer must be treated as read only! The position of the char buffer denotes the beginning of the string when this method is invoked. After completion of this method, the position is set after the last consumed character.
      idResolver - The factory for looking up object ids. Nullable for some converters.
      Returns:
      The value. Nullable.
      Throws:
      ParseException - if conversion failed. The error offset field is set to the position where parsing failed. The position of the buffer is undefined.

    • fromString

      @Nullable T fromString(@NonNull CharBuffer in, @Nullable IdResolver idResolver) throws ParseException
      Constructs a value from a string.

      The converter should try to create the value greedily, by consuming as many characters as possible for the value.

      This method does not change the state of the converter.

      Parameters:
      in - A char buffer which holds the string. The char buffer must be treated as read only! The position of the char buffer denotes the beginning of the string when this method is invoked. After completion of this method, the position is set after the last consumed character.
      idResolver - The factory for looking up object ids. Nullable for non-resolving converters.
      Returns:
      The value. Nullable.
      Throws:
      ParseException - if conversion failed. The error offset field is set to the position where parsing failed. The position of the buffer is undefined.

    • toString

      <TT extends T> void toString(Appendable out, @Nullable IdSupplier idSupplier, @Nullable TT value) throws IOException
      Converts a value to a string and appends it to the provided Appendable.

      This method does not change the state of the converter.

      Type Parameters:
      TT - the value type
      Parameters:
      out - The appendable
      idSupplier - The factory for creating object ids. Nullable for non-resolving converters.
      value - The value. Nullable.
      Throws:
      IOException - thrown by Appendable

    • fromString

      default @Nullable T fromString(@NonNull CharBuffer in) throws ParseException
      Constructs a value from a string.

      The converter should try to create the value greedily, by consuming as many characters as possible for the value.

      This method does not change the state of the converter.

      Parameters:
      in - A char buffer which holds the string. The char buffer must be treated as read only! The position of the char buffer denotes the beginning of the string when this method is invoked. After completion of this method, the position is set after the last consumed character.
      Returns:
      The value. Nullable.
      Throws:
      ParseException - if conversion failed. The error offset field is set to the position where parsing failed. The position of the buffer is undefined.

    • fromString

      default @Nullable T fromString(@NonNull CharSequence in) throws ParseException
      Constructs a value from a CharSequence.

      The conversion only succeeds if the entire CharSequence is consumed.

      This method does not change the state of the converter.

      Note: this is a convenience method. Implementing classes rarely need to overwrite this method.

      Parameters:
      in - The String.
      Returns:
      The value. Nullable.
      Throws:
      ParseException - on conversion failure

    • getDefaultValue

      @Nullable T getDefaultValue()
      Provides a default value for APIs which always require a value even if conversion from String failed.
      Returns:
      The default value to use when conversion from String failed.

    • getHelpText

      default @Nullable String getHelpText()
      Returns a help text which describes the supported String format.

      The format should be described in the following notation:

      • A production should consist of a single line starting with Format of ⟨x⟩:. Where x is the name of the production.
      • A terminal symbol should be given with its literal characters. Whitespace characters should be implied. Mandatory whitespace characters can be indicated with a bottom square bracket: ⎵.
      • Nonterminal symbols should be given in mathematical angle brackets: ⟨x⟩.
      • Alternatives should be separated by full-width vertical bar: x｜y.
      • Groups of symbols should be surrounded by full width parantheses: （x y）.
      • Zero or one occurrences of a symbol should be surrounded by full width square brackets: ［x］.
      • Zero or many occurrences of a symbol should be surrounded by full width angle brackets: ｛x｝.
      Example: 
       Format of ⟨Color⟩: ⟨name⟩｜ #⟨hex⟩｜ rgb(⟨r⟩,⟨g⟩,⟨b⟩)｜ rgba(⟨r⟩,⟨g⟩,⟨b⟩,⟨a⟩)｜ hsb(⟨h⟩,⟨s⟩,⟨b⟩)｜ hsba(⟨h⟩,⟨s⟩,⟨b⟩,⟨a⟩)
      Returns:
      help text. Returns null if no help text is available.

    • toString

      default <TT extends T> void toString(@NonNull Appendable out, @Nullable TT value) throws IOException
      Converts a value to a string and appends it to the provided Appendable.

      This method does not change the state of the converter.

      Type Parameters:
      TT - the value type
      Parameters:
      out - The appendable
      value - The value. Nullable.
      Throws:
      IOException - thrown by Appendable

    • toString

      default <TT extends T> @NonNull String toString(@Nullable TT value)
      Converts a value to a String.

      This method does not change the state of the converter.

      Note: this is a convenience method. Implementing classes rarely need to overwrite this method.

      Type Parameters:
      TT - the value type
      Parameters:
      value - The value. Nullable.
      Returns:
      The String.

    • toString

      default <TT extends T> @NonNull String toString(@Nullable IdSupplier idSupplier, @Nullable TT value)
      Converts a value to a String.

      This method does not change the state of the converter.

      Note: this is a convenience method. Implementing classes rarely need to overwrite this method.

      Type Parameters:
      TT - the value type
      Parameters:
      value - The value. Nullable.
      Returns:
      The String.

    • needsIdResolver

      default boolean needsIdResolver()