Module org.praxislive.core

Package org.praxislive.core.types

Class PMap

java.lang.Object

org.praxislive.core.Value

org.praxislive.core.types.PMap

public final class PMap
extends Value

An ordered map of Strings to Values.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	PMap.Builder	A PMap builder.
static final class	PMap.Entry
static class	PMap.MapBasedValue	An abstract superclass for values that are backed solely by a PMap.

Nested classes/interfaces inherited from class org.praxislive.core.Value

Value.Type<T extends Value>

Field Summary

Fields

Modifier and Type	Field	Description
static final PMap	EMPTY	An empty PMap.
static final BinaryOperator<Value>	IF_ABSENT	An operator for use with merge(org.praxislive.core.types.PMap, org.praxislive.core.types.PMap, java.util.function.BinaryOperator) that only adds mappings where the key is not present in the base map.
static final BinaryOperator<Value>	REPLACE	An operator for use with merge(org.praxislive.core.types.PMap, org.praxislive.core.types.PMap, java.util.function.BinaryOperator) that will replace mapped values in the base map, unless the new value is empty in which case the mapping is removed.
static final String	TYPE_NAME	Value type name.

Method Summary

Modifier and Type	Method	Description
OrderedMap<String,Value>	asMap()	An unmodifiable OrderedMap view of this PMap.
<T> OrderedMap<String,T>	asMapOf(Class<T> type)	Access an unmodifiable OrderedMap view of this PMap as a map of the provided value type.
static PMap.Builder	builder()	Create a PMap.Builder.
static PMap.Entry	entry(String key, Object value)	Create a PMap.Entry for creating a PMap.
boolean	equals(Object obj)	Values must override the default equals method.
boolean	equivalent(Value arg)	Indicates whether some other Value is equivalent to this one.
static Optional<PMap>	from(Value value)	Cast or convert the provided value into a PMap, wrapped in an Optional.
Value	get(String key)	Get the value for the given key, or null if the key does not exist.
boolean	getBoolean(String key, boolean def)	Get a boolean value from the map, returning a default value if the key is not mapped or mapped to a value that cannot be converted to a boolean.
double	getDouble(String key, double def)	Get a double value from the map, returning a default value if the key is not mapped or mapped to a value that cannot be converted to a double.
int	getInt(String key, int def)	Get an integer value from the map, returning a default value if the key is not mapped or mapped to a value that cannot be converted to an integer.
String	getString(String key, String def)	Get a String value from the map, returning a default value if the key is not mapped.
int	hashCode()	Values must override the default hashcode method.
boolean	isEmpty()	Check whether this Value is an empty value and has a zero length string representation.
List<String>	keys()	List of map keys.
static PMap	merge(PMap base, PMap additional, BinaryOperator<Value> operator)	Create a new PMap by merging the additional map into the base map, according to the result of the provided operator.
static PMap	of(String key, Object value)	Create a PMap with one mapping.
static PMap	of(String key1, Object value1, String key2, Object value2)	Create a PMap with two mappings.
static PMap	of(String key1, Object value1, String key2, Object value2, String key3, Object value3)	Create a PMap with three mappings.
static PMap	of(String key1, Object value1, String key2, Object value2, String key3, Object value3, String key4, Object value4)	Create a PMap with four mappings.
static PMap	of(String key1, Object value1, String key2, Object value2, String key3, Object value3, String key4, Object value4, String key5, Object value5)	Create a PMap with five mappings.
static PMap	ofEntries(PMap.Entry... entries)	Create a PMap of the provided mappings.
static PMap	ofMap(Map<String,? extends Value> map)	Create a PMap from the provided Map.
static PMap	parse(String text)	Parse the given text into a PMap.
int	size()	Size of the map.
String	toString()	Values must override the default method to return a string representation that is immutable.

Methods inherited from class org.praxislive.core.Value

info, ofObject, type

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

TYPE_NAME

public static final String TYPE_NAME

Value type name.

See Also:

• Constant Field Values

EMPTY

public static final PMap EMPTY

An empty PMap.

IF_ABSENT

public static final BinaryOperator<Value> IF_ABSENT

An operator for use with merge(org.praxislive.core.types.PMap, org.praxislive.core.types.PMap, java.util.function.BinaryOperator) that only adds mappings where the key is not present in the base map.

REPLACE

public static final BinaryOperator<Value> REPLACE

An operator for use with merge(org.praxislive.core.types.PMap, org.praxislive.core.types.PMap, java.util.function.BinaryOperator) that will replace mapped values in the base map, unless the new value is empty in which case the mapping is removed.

Method Details

get

public Value get(String key)

Get the value for the given key, or null if the key does not exist.

Parameters:

key - map key

Returns:

mapped value or null

getBoolean

public boolean getBoolean(String key,
 boolean def)

Get a boolean value from the map, returning a default value if the key is not mapped or mapped to a value that cannot be converted to a boolean.

Parameters:

key - map key

def - default if unmapped or invalid

Returns:

value or default

getInt

public int getInt(String key,
 int def)

Get an integer value from the map, returning a default value if the key is not mapped or mapped to a value that cannot be converted to an integer.

Parameters:

key - map key

def - default if unmapped or invalid

Returns:

value or default

getDouble

public double getDouble(String key,
 double def)

Get a double value from the map, returning a default value if the key is not mapped or mapped to a value that cannot be converted to a double.

Parameters:

key - map key

def - default if unmapped or invalid

Returns:

value or default

getString

public String getString(String key,
 String def)

Get a String value from the map, returning a default value if the key is not mapped.

Parameters:

key - map key

def - default if unmapped

Returns:

value or default

size

public int size()

Size of the map. This is the number of key-value pairs.

Returns:

size of the map

keys

public List<String> keys()

List of map keys. This is returned as a List as the keys are ordered.

Returns:

map keys

asMap

public OrderedMap<String,Value> asMap()

An unmodifiable OrderedMap view of this PMap.

Returns:

map view

asMapOf

public <T> OrderedMap<String,T> asMapOf(Class<T> type)

Access an unmodifiable OrderedMap view of this PMap as a map of the provided value type.

If the provided type is Value then this method acts the same as calling asMap().

If the provided type is a Value subclass and all values in the map returned by asMap() are of this type, then the map is cast and returned.

If the provided type is a Value subclass or any other type supported by ValueMapper then a new map will be returned with the values converted to the required type.

This method throws an IllegalArgumentException if no value mapper exists for the provided type, of if not all map values can be converted to the provided type.

Type Parameters:

T - value type

Parameters:

type - class of the value type

Returns:

ordered map view of the provided value type

Throws:

IllegalArgumentException - if there is no mapper for the provided type, or if all values cannot be converted to the provided type

toString

public String toString()

Description copied from class: Value

Values must override the default method to return a string representation that is immutable.

Specified by:

toString in class Value

Returns:

String representation

isEmpty

public boolean isEmpty()

Description copied from class: Value

Check whether this Value is an empty value and has a zero length string representation. Subclasses may wish to override this for efficiency if the String representation is lazily created.

Overrides:

isEmpty in class Value

Returns:

boolean true if empty

equivalent

public boolean equivalent(Value arg)

Description copied from class: Value

Indicates whether some other Value is equivalent to this one. Unlike Value.equals(java.lang.Object) this method is not symmetric - a value of a different type might be equivalent to this without the other type considering the reverse to be true.

The default implementation uses identity or String equality.

Overrides:

equivalent in class Value

Parameters:

arg - value to test for equivalence

Returns:

true if value is equivalent to this

hashCode

public int hashCode()

Description copied from class: Value

Values must override the default hashcode method.

Specified by:

hashCode in class Value

Returns:

int hashcode

equals

public boolean equals(Object obj)

Description copied from class: Value

Values must override the default equals method. This method should only return true if the supplied Object is of the same type as the implementing Value. Values of an unknown type should be coerced before calling this method. This method does not have to guarantee that this.equals(that) == this.toString().equals(that.toString())

Specified by:

equals in class Value

Parameters:

obj -

Returns:

boolean

of

public static PMap of(String key,
 Object value)

Create a PMap with one mapping. Map values that are not Value types will be converted automatically.

Parameters:

key - map key

value - mapped value

Returns:

new PMap

of

public static PMap of(String key1,
 Object value1,
 String key2,
 Object value2)

Create a PMap with two mappings. Map values that are not Value types will be converted automatically.

Parameters:

key1 - first map key

value1 - first mapped value

key2 - second map key

value2 - second mapped value

Returns:

new PMap

of

public static PMap of(String key1,
 Object value1,
 String key2,
 Object value2,
 String key3,
 Object value3)

Create a PMap with three mappings. Map values that are not Value types will be converted automatically.

Parameters:

key1 - first map key

value1 - first mapped value

key2 - second map key

value2 - second mapped value

key3 - third map key

value3 - third mapped value

Returns:

new PMap

of

public static PMap of(String key1,
 Object value1,
 String key2,
 Object value2,
 String key3,
 Object value3,
 String key4,
 Object value4)

Create a PMap with four mappings. Map values that are not Value types will be converted automatically.

Parameters:

key1 - first map key

value1 - first mapped value

key2 - second map key

value2 - second mapped value

key3 - third map key

value3 - third mapped value

key4 - fourth map key

value4 - fourth mapped value

Returns:

new PMap

of

public static PMap of(String key1,
 Object value1,
 String key2,
 Object value2,
 String key3,
 Object value3,
 String key4,
 Object value4,
 String key5,
 Object value5)

Create a PMap with five mappings. Map values that are not Value types will be converted automatically.

Parameters:

key1 - first map key

value1 - first mapped value

key2 - second map key

value2 - second mapped value

key3 - third map key

value3 - third mapped value

key4 - fourth map key

value4 - fourth mapped value

key5 - fifth map key

value5 - fifth mapped value

Returns:

new PMap

ofEntries

public static PMap ofEntries(PMap.Entry... entries)

Create a PMap of the provided mappings. Use entry(java.lang.String, java.lang.Object) to create entries.

Parameters:

entries - map entries

Returns:

new PMap

entry

public static PMap.Entry entry(String key,
 Object value)

Create a PMap.Entry for creating a PMap. Values that are not Value types will be converted automatically.

Parameters:

key - map key

value - map value

Returns:

map entry

ofMap

public static PMap ofMap(Map<String,? extends Value> map)

Create a PMap from the provided Map. The order of keys in the PMap will be based on the iteration order of the map.

If the provided map is an OrderedMap then no copy of the map will be made and the map returned by asMap() will be the map passed in to this method.

Parameters:

map - map to copy

Returns:

new PMap

parse

public static PMap parse(String text)
                  throws ValueFormatException

Parse the given text into a PMap.

Parameters:

text - text to parse

Returns:

parsed PArray

Throws:

ValueFormatException

from

public static Optional<PMap> from(Value value)

Cast or convert the provided value into a PMap, wrapped in an Optional. If the value is already a PMap, the Optional will wrap the existing value. If the value is not a PMap and cannot be converted into one, an empty Optional is returned.

Parameters:

value - value

Returns:

optional PMap

merge

public static PMap merge(PMap base,
 PMap additional,
 BinaryOperator<Value> operator)

Create a new PMap by merging the additional map into the base map, according to the result of the provided operator. The operator will be called for all values in the additional map, even if no mapping exists in the base map. The operator must be able to handle null input. The operator should return the resulting mapped value, or null to remove the mapping. See REPLACE and IF_ABSENT for operators that should cover most common usage.

Parameters:

base - base map

additional - additional map

operator - operator to compute result value

Returns:

new PMap

builder

public static PMap.Builder builder()

Create a PMap.Builder.

Returns:

new PMap.Builder