Module org.tquadrat.foundation.base
Package org.tquadrat.foundation.lang

Interface StringConverter<T>

Type Parameters:
T - The Object type for the conversion.
All Superinterfaces:
Serializable
All Known Implementing Classes:
DefaultEnumStringConverter, GenericStringConverter
@ClassVersion(sourceVersion="$Id: StringConverter.java 1107 2024-03-01 15:33:11Z tquadrat $") @API(status=STABLE, since="0.1.0") public interface StringConverter<T> extends Serializable

Defines the conversion between Strings and object instances, where the concrete behaviour is defined by the implementation of the interface.

Implementations of StringConverter are meant as a tool to translate Strings to Objects for technical purposes, not necessarily for human convenience.

Each implementation should ensure that

  StringConverter<T> c = …
  T v = …
  true == ( v.equals( c.fromString( c.toString( v ) );

is always valid.

If that condition could not be met, this must be clearly documented.

For the other direction (from String to object back to String), this condition is weaker, as long as the result is equivalent to the original, as for numbers that can be represented as decimal, octal or hexadecimal.

An implementation of StringConverter usually holds no state and it is possible to reuse an instance. Therefore it is recommended to provide a public static final field INSTANCE that is initialised with a reference for a single instance of the implementation.

Notes:
  • Both fromString(CharSequence) and toString(Object) will return null if called with a null argument.
  • Usually the java.util.Locale.ROOT locale is used when locale specific conversion or parsing is required; this means in particular that numbers will use the decimal point as separator.
  • In order to make an implementation of this interface visible for forClass(), forEnum() and list(), that implementation needs to be exposed as a service provider for org.tquadrat.foundation.lang.StringConverter.
  • If the implementation is published as a service provider, and if it has a static INSTANCE field holding the reference to an instance of the converter, the implementation should also provide a static final method provider() that returns that reference.
  • Two implementations of StringConverter for the same subject class may cause unpredictable results if both are exposed as service providers.
  • When an implementation of StringConverter is published as a service, the subject class usually is guessed from the return value of fromString(), but sometimes this does not work reliably. In that case it is required that the implementation of StringConverter provides a method public Collection<Class<?>> getSubjectClass() that returns the respective classes.
    This is definitely required, when the concrete implementation of the string converter is derived from an abstract base class; this abstract class must be visible for this module, too.
Author:
Thomas Thrien (thomas.thrien@tquadrat.org)
Version:
$Id: StringConverter.java 1107 2024-03-01 15:33:11Z tquadrat $
Since:
0.1.0
UML Diagram
UML Diagram for "org.tquadrat.foundation.lang.StringConverter"⁠

UML Diagram for "org.tquadrat.foundation.lang.StringConverter"

UML Diagram for "org.tquadrat.foundation.lang.StringConverter"⁠

  • Field Details

  • Method Details

    • forClass

      @API(status=STABLE, since="0.1.0") static <C> Optional<StringConverter<C>> forClass(Class<C> type)
      Returns an instance of StringConverter for the given Class. If there is no converter for the given type, or the type is null, the return value is Optional.empty().
      Type Parameters:
      C - The class a converter is needed for.
      Parameters:
      type - The instance of the class a converter is needed for.
      Returns:
      An instance of Optional that holds the instance of StringConverter.

    • forEnum

      @API(status=STABLE, since="0.0.6") static <E extends Enum<E>> StringConverter<E> forEnum(Class<E> type)
      Returns an instance of StringConverter for the given Enum type. If there is no converter for the given type in the registry, a new instance of StringConverter will be created, based on a default implementation.
      Type Parameters:
      E - The class a converter is needed for.
      Parameters:
      type - The instance of the class a converter is needed for.
      Returns:
      The requested instance of StringConverter.

    • fromString

      T fromString(CharSequence source) throws IllegalArgumentException
      Converts the given String to an object instance.
      Parameters:
      source - The String representation for the object instance; can be null.
      Returns:
      The resulting object instance; will be null if source was already null.
      Throws:
      IllegalArgumentException - The format of the given String is invalid and cannot be parsed into the object instance.

    • toString

      default String toString(T source)
      Converts the given object instance to a String.
      Note:
      • Even if an implementation of might exist for T, it cannot be used to implement this method; will never return null (if implemented accordingly), for a null argument, it will return the String "null". That contradicts the contract for this method.
      Parameters:
      source - The object to convert; can be null.
      Returns:
      The resulting String; will be null if source was already null.

    • list

      @API(status=STABLE, since="0.1.0") static Collection<Class<?>> list()
      Returns the classes for that an instance of StringConverter is already registered,
      Returns:
      The classes with a string converter.