Module org.tquadrat.foundation.base

Package org.tquadrat.foundation.lang

Interface Stringer<T>

Type Parameters:

T - The type of the argument value.

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@ClassVersion(sourceVersion="$Id: Stringer.java 1060 2023-09-24 19:21:40Z tquadrat $")
@FunctionalInterface
@API(status=STABLE,
     since="0.1.0")
public interface Stringer<T>

This interface defines a method to compose a String representation from arbitrary objects.

It will also provide several convenience implementations for the interface that can be used with special argument types. Currently, these are

• OBJECT_STRINGER as a catch-all
• BASE_STRINGER when the output of the default implementation of Object.toString() is desired even when a more sophisticated implementation of toString() is available
• OBJECTCLASS_STRINGER when only the object's class should be returned instead of its contents/value.
• CLASS_STRINGER for instances of Class
• FILEOBJECT_STRINGER for instances of File
• OPTIONAL_STRINGER for instances of Optional
• STRING_STRINGER for instances of String
• URL_STRINGER for instances of URL (There is no URI_STRINGER as URI provides a sufficient implementation of Object.toString())

There are no explicit stringers for the classes from the java.time package as instances of these classes have sufficient implementations of Object.toString() and are therefore already well covered by OBJECT_STRINGER. Same is true for the class Path.

This is a functional interface whose functional method is toString(Object).

Note:

• The method toString(Object) will never return null; if called with a null argument, it will return the String "null".
  This is different to the behaviour of the toString(Object) method of an implementation of StringConverter that returns null for a null argument.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: Stringer.java 1060 2023-09-24 19:21:40Z tquadrat $

Since:

0.1.0

See Also:

• StringConverter.toString(Object)
• CommonConstants.NULL_STRING

UML Diagram

⁠

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

⁠

Field Summary

Fields

Modifier and Type	Field	Description
static final Stringer<? super Object>	BASE_STRINGER	An implementation of Stringer that produces an output that looks like that from the default implementation of Object.toString()
static final Stringer<byte[]>	BYTEARRAY_STRINGER	An implementation of Stringer for byte arrays.
static final Stringer<Class<?>>	CLASS_STRINGER	An implementation of Stringer for instances of Class.
static final Stringer<Object>	DEFAULT_STRINGER	A generic Stringer implementation that delegates to Objects.toString(Object).
static final Stringer<File>	FILEOBJECT_STRINGER	An implementation of Stringer for instances of File.
static final Stringer<? super Object>	OBJECT_STRINGER	A Stringer implementation that calls String.format( "%s", o ) for an object o if that implements the interface Formattable, otherwise it delegates to Objects.toString(Object).
static final Stringer<? super Object>	OBJECTCLASS_STRINGER	An implementation of Stringer that returns the name of the object's class instead of a representation of the object's value.
static final Stringer<Optional<?>>	OPTIONAL_STRINGER	An implementation of Stringer for instances of Optional.
static final Stringer<String>	STRING_STRINGER	An implementation for Stringer for instances of String.
static final Stringer<URL>	URL_STRINGER	An implementation for Stringer for instances of URL.

Method Summary

Modifier and Type	Method	Description
static <A> Function<A,String>	asFunction(Stringer<? super A> stringer)	Returns the given Stringer as an instance of Function.
static <A> Stringer<A>	fromStringConverter(StringConverter<? super A> stringConverter)	Creates a Stringer for the given instance of StringConverter.
default Function<T,String>	toFunction()	Returns this Stringer instance as an instance of Function.
String	toString(T value)	Returns a String representation of the given argument, or "null" if the given value is null.
static <A> Stringer<A>	wrapFunction(Function<? super A,String> function)	Wraps a function that returns a String to an argument stringer.

Field Details

BASE_STRINGER

@API(status=STABLE,
     since="0.0.7")
static final Stringer<? super Object> BASE_STRINGER

An implementation of Stringer that produces an output that looks like that from the default implementation of Object.toString(): it returns

  o.getClass().getName() + "@" + Integer.toHexString( o.hashCode() );

.

BYTEARRAY_STRINGER

@API(status=STABLE,
     since="0.0.5")
static final Stringer<byte[]> BYTEARRAY_STRINGER

An implementation of Stringer for byte arrays.

The result looks like this:

byte [<length>]

where length is the array length of the given argument.

CLASS_STRINGER

@API(status=STABLE,
     since="0.0.5")
static final Stringer<Class<?>> CLASS_STRINGER

An implementation of Stringer for instances of Class.

DEFAULT_STRINGER

@API(status=STABLE,
     since="0.0.5")
static final Stringer<Object> DEFAULT_STRINGER

A generic Stringer implementation that delegates to Objects.toString(Object).

FILEOBJECT_STRINGER

@API(status=STABLE,
     since="0.0.5")
static final Stringer<File> FILEOBJECT_STRINGER

An implementation of Stringer for instances of File.

OBJECT_STRINGER

@API(status=STABLE,
     since="0.0.5")
static final Stringer<? super Object> OBJECT_STRINGER

A Stringer implementation that calls String.format( "%s", o ) for an object o if that implements the interface Formattable, otherwise it delegates to Objects.toString(Object).

See Also:

• DEFAULT_STRINGER

OBJECTCLASS_STRINGER

@API(status=STABLE,
     since="0.0.5")
static final Stringer<? super Object> OBJECTCLASS_STRINGER

An implementation of Stringer that returns the name of the object's class instead of a representation of the object's value.

OPTIONAL_STRINGER

@API(status=STABLE,
     since="0.0.5")
static final Stringer<Optional<?>> OPTIONAL_STRINGER

An implementation of Stringer for instances of Optional.

It returns basically the result of Objects.toString(Object,String) with the value of the Optional and the text "[empty]" as the nullDefault arguments.

STRING_STRINGER

@API(status=STABLE,
     since="0.0.5")
static final Stringer<String> STRING_STRINGER

An implementation for Stringer for instances of String.

URL_STRINGER

@API(status=STABLE,
     since="0.0.5")
static final Stringer<URL> URL_STRINGER

An implementation for Stringer for instances of URL.

Method Details

asFunction

@API(status=STABLE,
     since="0.0.5")
static <A> Function<A,String> asFunction(Stringer<? super A> stringer)

Returns the given Stringer as an instance of Function.

Type Parameters:

A - The type of the input for the stringer.

Parameters:

stringer - The instance to wrap.

Returns:

The function.

fromStringConverter

@API(status=STABLE,
     since="0.0.7")
static <A> Stringer<A> fromStringConverter(StringConverter<? super A> stringConverter)

Creates a Stringer for the given instance of StringConverter.

A String converter cannot be used directly as a Stringer because Stringer's toString() method will never return null (in case the argument is null, it returns the NULL_STRING), while StringConverter.toString() returns null for a null argument.

Type Parameters:

A - The type of the input for the stringer.

Parameters:

stringConverter - The StringConverter instance.

Returns:

The Stringer.

toFunction

@API(status=STABLE,
     since="0.0.7")
default Function<T,String> toFunction()

Returns this Stringer instance as an instance of Function.

Returns:

The function.

toString

String toString(T value)

Returns a String representation of the given argument, or "null" if the given value is null.

Parameters:

value - The value.

Returns:

The String representation.

wrapFunction

@API(status=STABLE,
     since="0.0.7")
static <A> Stringer<A> wrapFunction(Function<? super A,String> function)

Wraps a function that returns a String to an argument stringer.

Type Parameters:

A - The type of the input for the function.

Parameters:

function - The function to wrap.

Returns:

The argument stringer that wraps the function.