squidpony

Class StringConvert<T>

java.lang.Object

squidpony.StringConvert<T>

public abstract class StringConvert<T>
extends java.lang.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 Summary

Fields

Modifier and Type	Field and Description
boolean	isArray
java.lang.CharSequence	name
static K2<StringConvert,java.lang.CharSequence[]>	registry
static CrossHash.IHasher	spaceIgnoringArrayHasher
static CrossHash.IHasher	spaceIgnoringHasher
java.lang.String	specificName
java.lang.CharSequence[]	typeNames

Constructor Summary

Constructors

Constructor and Description
StringConvert(boolean isArray, java.lang.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.
StringConvert(java.lang.CharSequence... types) Constructs a StringConvert using a vararg or array of CharSequence objects, such as Strings.

Method Summary

Modifier and Type	Method and Description
static java.lang.CharSequence[]	asArray(java.lang.CharSequence... types) Simply takes a vararg of Class and returns the simple names of the Classes as a String array.
static StringConvert<?>	get(java.lang.CharSequence name) Gets the registered StringConvert for the given type name, if there is one, or returns null otherwise.
java.lang.CharSequence	getName()
static StringConvert<?>	lookup(java.lang.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).
abstract T	restore(java.lang.String text)
<T2> T2	restore(java.lang.String text, java.lang.Class<T2> type) Attempts to restore a specific type of value from the given text.
abstract java.lang.String	stringify(T item)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

public final java.lang.CharSequence name

typeNames

public final java.lang.CharSequence[] typeNames

specificName

public final java.lang.String specificName

isArray

public final boolean isArray

spaceIgnoringHasher

public static final CrossHash.IHasher spaceIgnoringHasher

spaceIgnoringArrayHasher

public static final CrossHash.IHasher spaceIgnoringArrayHasher

registry

public static final K2<StringConvert,java.lang.CharSequence[]> registry

Constructor Detail

StringConvert

public StringConvert(boolean isArray,
                     java.lang.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 CharSequence 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(java.lang.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 CharSequence 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 Detail

getName

public java.lang.CharSequence getName()

stringify

public abstract java.lang.String stringify(T item)

restore

public abstract T restore(java.lang.String text)

restore

public <T2> T2 restore(java.lang.String text,
                       java.lang.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(java.lang.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(java.lang.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 java.lang.CharSequence[] asArray(java.lang.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