Package squidpony

Class StringConvert<T>

java.lang.Object
squidpony.StringConvert<T>
public abstract class StringConvert<T>
extends Object
Used to standardize conversion for a given type, T, to and from a serialized String format. This abstract class should usually be made concrete by a single-purpose class (not the type T itself). Also includes a static registry of types as CharSequence arrays (including the classes of generic type parameters in array elements after the first) to the corresponding StringConvert objects that have been constructed for those types, although the registry must store the StringConvert objects without any further types (you can cast the StringConvert to a StringConvert with the desired generic type, or call restore(String) on the un-parametrized type and get back an Object that can be cast to the correct type, but we aren't able to store the actual type). The static method lookup(CharSequence[]) can be used to find the StringConvert registered for a type name combination. The static method get(CharSequence) can be used to find a StringConvert by its name. The static utility method asArray(CharSequence[]) can be used to reduce the amount of arrays produced by varargs, especially when you have a bunch of Class items and need Strings, but the array it returns must not be edited once used to construct a StringConvert.

  • Field Details

  • Constructor Details

    • StringConvert

      public StringConvert​(boolean isArray, CharSequence... types)
      Constructs a StringConvert using a vararg or array of CharSequence objects, such as Strings, as well as a boolean flag to determine if the StringConvert works on an array instead of a normal object. If an array of types is passed, it must not be altered after usage. If no varargs are passed, if types is null, or if the first item of types is null, then this uses a special type representation where the name is "void" and typeNames has "void" as its only element. If types has length 1, then the name will be the "simple name" of the first element in types, as produced by Class.getSimpleName() (note that this produces an empty string for anonymous classes), and typeNames will again have that simple name as its only value. Otherwise, this considers items after the first to be the names of generic type arguments of the first, using normal Java syntax of "Outer<A,B>" if given the Strings for types "Outer", "A", "B". No spaces will be present in the name, but thanks to some customization of the registry, you can give a String with spaces in it to get(CharSequence) and still find the correct one). You can give type names with generic components as the names of generic type arguments, such as new StringConvert("OrderedMap", "String", "OrderedSet<String>") for a mapping of String keys to values that are themselves sets of Strings. After constructing a StringConvert, it is automatically registered so it can be looked up by name with get(CharSequence) or by component generic types with lookup(CharSequence...); both of these will not return a StringConvert with type info for what it takes and returns beyond "Object", but the result can be cast to a StringConvert with the correct type.
      Parameters:
      isArray - true if this should convert an array type as opposed to a normal object or primitive type
      types - a vararg of Class objects representing the type this can convert, including generic type parameters of the first element, if there are any, at positions after the first

    • StringConvert

      public StringConvert​(CharSequence... types)
      Constructs a StringConvert using a vararg or array of CharSequence objects, such as Strings. If an array is passed, it must not be altered after usage. If no arguments are passed, if types is null, or if the first item of types is null, then this uses a special type representation where the name is "void" and typeNames has "void" as its only element. If types has length 1, then the name will be the "simple name" of the first element in types, as produced by Class.getSimpleName() (note that this produces an empty string for anonymous classes), and typeNames will again have that simple name as its only value. Otherwise, this considers items after the first to be the names of generic type arguments of the first, using normal Java syntax of "Outer<A,B>" if given the Strings for types "Outer", "A", "B". No spaces will be present in the name, but thanks to some customization of the registry, you can give a String with spaces in it to get(CharSequence) and still find the correct one). You can give type names with generic components as the names of generic type arguments, such as new StringConvert("OrderedMap", "String", "OrderedSet<String>") for a mapping of String keys to values that are themselves sets of Strings. After constructing a StringConvert, it is automatically registered so it can be looked up by name with get(CharSequence) or by component generic types with lookup(CharSequence...); both of these will not return a StringConvert with type info for what it takes and returns beyond "Object", but the result can be cast to a StringConvert with the correct type.
      Parameters:
      types - a vararg of Class objects representing the type this can convert, including generic type parameters of the first element, if there are any, at positions after the first

  • Method Details

    • getName

      public CharSequence getName()

    • stringify

      public abstract String stringify​(T item)

    • restore

      public abstract T restore​(String text)

    • restore

      public <T2> T2 restore​(String text, Class<T2> type)
      Attempts to restore a specific type of value from the given text. Useful when this StringConvert does not have meaningful generic type information (e.g. StringConvert<?>), and you know the correct type externally. May throw a ClassCastException if type is not compatible with the type this deserializes to (that is, T).
      Type Parameters:
      T2 - you must be able to cast from a T (the type described by this class' specificName) to a T2
      Parameters:
      text - the text to try to read as serialized data describing a T2 object
      type - the Class of the data to try to produce, which should be as specific as possible
      Returns:
      if this is successful, a T2 drawn from the data in text; otherwise, this may throw an exception

    • get

      public static StringConvert<?> get​(CharSequence name)
      Gets the registered StringConvert for the given type name, if there is one, or returns null otherwise. The name can have the normal parts of a generic type, such as "OrderedMap<String, ArrayList<String>>", as long as such a type was fully registered. For that example, you could use Converters.convertOrderedMap(Converters.convertString, Converters.convertArrayList(Converters.convertString)) to produce and register a StringConvert for the aforementioned generic type.
      Parameters:
      name - the name of the type to find a registered StringConvert, such as "ArrayList<String>" or "char[]"
      Returns:
      the registered StringConvert, if it was found, or null if none was found

    • lookup

      public static StringConvert<?> lookup​(CharSequence... types)
      Looks up the StringConvert for a given vararg of Class instances (if an array of Classes is used other than a vararg, it must not be altered in the future, nor reused in a way that modifies its elements). Returns null if no StringConvert is found. You should usually cast the returned StringConvert, if non-null, to the specific StringConvert generic type you want.
      Parameters:
      types - the vararg of types to look up
      Returns:
      the StringConvert registered for the given types, or null if none has been made

    • asArray

      public static CharSequence[] asArray​(CharSequence... types)
      Simply takes a vararg of Class and returns the simple names of the Classes as a String array. Can be handy to avoid re-creating arrays implicitly from varargs of Class items.
      Parameters:
      types - a vararg of Class
      Returns:
      the String simple names of types as an array