Package org.apache.sis.measure
Class RangeFormat
java.lang.Object
java.text.Format
org.apache.sis.measure.RangeFormat
- All Implemented Interfaces:
Serializable
,Cloneable
,Localized
- Direct Known Subclasses:
SampleRangeFormat
Parses and formats
Range
instances according the given locale.
This class complies to the format described in the ISO 31-11
standard, except that the minimal and maximal values are separated by the "…
" character
instead of coma. More specifically, the format is defined as below:
- If the range is empty, then the range is represented by "
{}
". - Otherwise if the minimal value is equal to the
maximal value, then that single value is formatted
inside braces as in "
{value}
". - Otherwise the minimal and maximal values are formatted inside bracket or parenthesis,
depending on whether each endpoint is inclusive or exclusive:
- "
[min … max]
" if both endpoints are inclusive (closed interval); - "
(min … max)
" if both endpoints are exclusive (open interval); - or a mix of both styles if an endpoint is inclusive while the other is exclusive.
∞
" symbol is used in place ofmin
ormax
for unbounded ranges. - "
MeasurementRange
, then the
unit of measurement is appended except for empty ranges.
Lenient parsing
At parsing time, the above formatting rules are relaxed as below:- Empty ranges can be represented by "
[]
"or "()
" in addition to the standard "{}
". - The braces are optional for singleton values, i.e. "
value
" is accepted as well as "{value}
".
Range type and type of range elements
The kind of ranges created by theparse(…)
methods is determined
by the type of range elements:
- If the elements type is assignable to
Date
, then theparse(…)
methods will createRange<Date>
objects. - If the elements type is assignable to
Number
, then:- If the text to parse contains a unit of measurement, then
the
parse(…)
methods will createMeasurementRange
objects. - Otherwise the
parse(…)
methods will createNumberRange
objects.
- If the text to parse contains a unit of measurement, then
the
- Since:
- 0.3
- Version:
- 1.1
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Constants that are used as attribute keys in the iterator returned fromformatToCharacterIterator(Object)
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
true
ifRangeFormat
shall use the alternate form at formatting time.private final int
The character closing a range in which the maximal value is exclusive.private final int
An alternative character closing a range in which the maximal value is exclusive.private final int
The character closing a range in which the maximal value is inclusive.private final int
The character closing an empty range or a range containing only one element.protected final Format
The format to use for parsing and formatting the range components.protected final Class
<?> The type of the range components.private final String
Symbols used by this format, inferred fromDecimalFormatSymbols
.Whether we should insert a space between the bracket and the unit symbol.private Locale
The locale for error message, ornull
for the default.private static final int
The constant value forFieldPosition
which designate the maximal value.private static final int
The constant value forFieldPosition
which designate the minimal value.private final char
Symbols used by this format, inferred fromDecimalFormatSymbols
.private final int
The character opening a range in which the minimal value is exclusive.private final int
An alternative character opening a range in which the minimal value is exclusive.private final int
The character opening a range in which the minimal value is inclusive.private final int
The character opening an empty range or a range containing only one element.private final String
The string to use as a separator between minimal and maximal value, not including whitespaces.private static final long
For cross-version compatibility.private static final int
The constant value forFieldPosition
which designate the unit of measurement.protected final UnitFormat
The format for unit of measurement, ornull
if none. -
Constructor Summary
ConstructorsConstructorDescriptionCreates a new format for parsing and formatting number ranges using the default locale.RangeFormat
(Locale locale) Creates a new format for parsing and formatting number ranges using the given locale.RangeFormat
(Locale locale, Class<?> elementType) Creates a new format for parsing and formatting ranges of the given element type using the given locale.RangeFormat
(Locale locale, TimeZone timezone) Creates a new format for parsing and formattingRange<Date>
using the given locale and timezone. -
Method Summary
Modifier and TypeMethodDescriptionprivate static Range
<?> Casts the given object to aRange
, or throws anIllegalArgumentException
if the given object is not aRange
instance.clone()
Returns a clone of this range format.private Object
Converts the given value to an instance of theelementType
type.format
(Object range, StringBuffer toAppendTo, FieldPosition pos) Formats aRange
and appends the resulting text to a given string buffer.private void
format
(Range<?> range, StringBuffer toAppendTo, FieldPosition pos, FormattedCharacterIterator characterIterator) Implementation of the format methods.formatToCharacterIterator
(Object range) Formats a range as an attributed character iterator.getElementPattern
(boolean localized) Returns the pattern used byelementFormat
for formatting the minimum and maximum values.private static int
getField
(FieldPosition position) Returns the*_FIELD
constant for the given field position, or -1 if none.Returns this formatter locale.private boolean
insertSpaceBeforeUnit
(javax.measure.Unit<?> unit) Returns whether we should insert a space between the bracket and the unit symbol.boolean
Returnstrue
if thisRangeFormat
shall use the alternate form at formatting time.private boolean
isClose
(int c) Returnstrue
if the given character is any of the closing bracket characters.private boolean
isOpen
(int c) Returnstrue
if the given character is any of the opening bracket characters.Range
<?> Parses text from the given string to produce a range.Range
<?> parse
(String source, ParsePosition pos) Parses text from a string to produce a range.parseObject
(String source) Parses text from a string to produce a range.parseObject
(String source, ParsePosition pos) Parses text from a string to produce a range.void
setAlternateForm
(boolean alternateForm) Sets whether thisRangeFormat
shall use the alternate form at formatting time.void
setElementPattern
(String pattern, boolean localized) Sets the pattern to be used byelementFormat
for formatting the minimum and maximum values.private Object
toFormattable
(Object value) Converts the given object to a type thatformat(…)
method can process.private Range
<?> tryParse
(String source, ParsePosition pos) Tries to parse the given text.private Object
Returns a "nil" value.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
MIN_VALUE_FIELD
private static final int MIN_VALUE_FIELDThe constant value forFieldPosition
which designate the minimal value.- See Also:
-
MAX_VALUE_FIELD
private static final int MAX_VALUE_FIELDThe constant value forFieldPosition
which designate the maximal value.- See Also:
-
UNIT_FIELD
private static final int UNIT_FIELDThe constant value forFieldPosition
which designate the unit of measurement.- See Also:
-
openSet
private final int openSetThe character opening an empty range or a range containing only one element. The default value is'{'
. -
openInclusive
private final int openInclusiveThe character opening a range in which the minimal value is inclusive. The default value is'['
. -
openExclusive
private final int openExclusiveThe character opening a range in which the minimal value is exclusive. The default value is'('
. Note that the']'
character is also sometimes used. -
openExclusiveAlt
private final int openExclusiveAltAn alternative character opening a range in which the minimal value is exclusive. This character is not used for formatting (onlyopenExclusive
is used), but is accepted during parsing. The default value is']'
. -
closeSet
private final int closeSetThe character closing an empty range or a range containing only one element. The default value is'}'
. -
closeInclusive
private final int closeInclusiveThe character closing a range in which the maximal value is inclusive. The default value is']'
. -
closeExclusive
private final int closeExclusiveThe character closing a range in which the maximal value is exclusive. The default value is')'
. Note that the'['
character is also sometimes used. -
closeExclusiveAlt
private final int closeExclusiveAltAn alternative character closing a range in which the maximal value is exclusive. This character is not used for formatting (onlycloseExclusive
is used), but is accepted during parsing. The default value is'['
. -
separator
The string to use as a separator between minimal and maximal value, not including whitespaces. The default value is"…"
(Unicode 2026). -
minusSign
private final char minusSignSymbols used by this format, inferred fromDecimalFormatSymbols
. -
infinity
Symbols used by this format, inferred fromDecimalFormatSymbols
. -
alternateForm
private boolean alternateFormtrue
ifRangeFormat
shall use the alternate form at formatting time. This flag as no effect on parsing, since both forms are accepted.- See Also:
-
elementType
The type of the range components. Valid types areNumber
,Angle
,Date
or a subclass of those types. This value determines the kind of range to be created by the parse method:- See Also:
-
elementFormat
The format to use for parsing and formatting the range components. The format is determined from the element type:AngleFormat
if the element type is assignable toAngle
.NumberFormat
if the element type is assignable toNumber
.DateFormat
if the element type is assignable toDate
.
-
unitFormat
The format for unit of measurement, ornull
if none. This is non-null if and only ifelementType
is assignable toNumber
but not toAngle
. -
insertSpaceBeforeUnit
Whether we should insert a space between the bracket and the unit symbol.- See Also:
-
locale
The locale for error message, ornull
for the default.
-
-
Constructor Details
-
RangeFormat
public RangeFormat()Creates a new format for parsing and formatting number ranges using the default locale. -
RangeFormat
Creates a new format for parsing and formatting number ranges using the given locale.- Parameters:
locale
- the locale for parsing and formatting range components.
-
RangeFormat
Creates a new format for parsing and formattingRange<Date>
using the given locale and timezone.- Parameters:
locale
- the locale for parsing and formatting range components.timezone
- the timezone for the dates to be formatted.
-
RangeFormat
Creates a new format for parsing and formatting ranges of the given element type using the given locale. The element type is typicallyDate.class
or some subclass ofNumber.class
.- Parameters:
locale
- the locale for parsing and formatting range components.elementType
- the type of range components.- Throws:
IllegalArgumentException
- if the given type is not recognized by this constructor.
-
-
Method Details
-
isOpen
private boolean isOpen(int c) Returnstrue
if the given character is any of the opening bracket characters. -
isClose
private boolean isClose(int c) Returnstrue
if the given character is any of the closing bracket characters. -
getLocale
Returns this formatter locale. This is the locale specified at construction time if any, or the default locale at construction time otherwise. -
getElementPattern
Returns the pattern used byelementFormat
for formatting the minimum and maximum values. If the element format does not use pattern, returnsnull
.- Parameters:
localized
-true
for returning the localized pattern, orfalse
for the unlocalized one.- Returns:
- the pattern, or
null
if theelementFormat
doesn't use pattern. - See Also:
-
setElementPattern
Sets the pattern to be used byelementFormat
for formatting the minimum and maximum values.- Parameters:
pattern
- the new pattern.localized
-true
if the given pattern is localized.- Throws:
IllegalStateException
- if theelementFormat
does not use pattern.- See Also:
-
isAlternateForm
public boolean isAlternateForm()Returnstrue
if thisRangeFormat
shall use the alternate form at formatting time. The alternate form expresses open intervals like]a…b[
instead of(a…b)
.This flag has no effect on parsing, since the parser accepts both forms.
- Returns:
true
for using the alternate format instead of the default format.
-
setAlternateForm
public void setAlternateForm(boolean alternateForm) Sets whether thisRangeFormat
shall use the alternate form at formatting time. The alternate form expresses open intervals like]a…b[
instead of(a…b)
.- Parameters:
alternateForm
-true
for using the alternate format, orfalse
for using the default format.
-
insertSpaceBeforeUnit
private boolean insertSpaceBeforeUnit(javax.measure.Unit<?> unit) Returns whether we should insert a space between the bracket and the unit symbol. We cache the result because checking for this condition forces us to format the unit symbol twice. -
getField
Returns the*_FIELD
constant for the given field position, or -1 if none. -
cast
Casts the given object to aRange
, or throws anIllegalArgumentException
if the given object is not aRange
instance. This is used for validating argument ofObject
type in formatting methods.- Throws:
IllegalArgumentException
-
format
Formats aRange
and appends the resulting text to a given string buffer. See the class javadoc for a description of the format.- Specified by:
format
in classFormat
- Parameters:
range
- theRange
object to format.toAppendTo
- where the text is to be appended.pos
- identifies a field in the formatted text, ornull
if none.- Returns:
- the string buffer passed in as
toAppendTo
, with formatted text appended. - Throws:
IllegalArgumentException
- if this formatter cannot format the given object.
-
format
private void format(Range<?> range, StringBuffer toAppendTo, FieldPosition pos, FormattedCharacterIterator characterIterator) Implementation of the format methods.- Parameters:
range
- the range to format.toAppendTo
- where the text is to be appended.pos
- identifies a field in the formatted text, ornull
if none.characterIterator
- the character iterator for which the attributes need to be set, or null if none.
-
formatToCharacterIterator
Formats a range as an attributed character iterator. Callers can iterate and queries the attribute values as in the following example: Alternatively, if the current iterator index is before the start of the minimum value field, then the starting position of that field can be obtained directly byit.getRunLimit(MIN_VALUE)
. If the current iterator index is inside the minimum value field, then the above method call will rather returns the end of that field. The same strategy works for other all fields too.The returned character iterator contains all
NumberFormat.Field
,DateFormat.Field
orAngleFormat.Field
attributes in addition to theRangeFormat.Field
ones. Consequently, the same character may have more than one attribute.In Apache SIS implementation, the returned character iterator also implements the
CharSequence
interface for convenience.- Overrides:
formatToCharacterIterator
in classFormat
- Parameters:
range
- theRange
object to format.- Returns:
- a character iterator together with the attributes describing the formatted value.
- Throws:
IllegalArgumentException
- ifvalue
if not an instance ofRange
.
-
parseObject
Parses text from a string to produce a range. The default implementation delegates toparse(String)
with no additional work.- Overrides:
parseObject
in classFormat
- Parameters:
source
- the text, part of which should be parsed.- Returns:
- a range parsed from the string.
- Throws:
ParseException
- if the given string cannot be fully parsed.
-
parseObject
Parses text from a string to produce a range. The default implementation delegates toparse(String, ParsePosition)
with no additional work.- Specified by:
parseObject
in classFormat
- Parameters:
source
- the text, part of which should be parsed.pos
- index and error index information as described above.- Returns:
- a range parsed from the string, or
null
in case of error.
-
parse
Parses text from the given string to produce a range. This method use the full string. If there is some unparsed characters after the parsed range, then this method thrown an exception.- Parameters:
source
- the text to parse.- Returns:
- the parsed range (never
null
). - Throws:
ParseException
- if the given string cannot be fully parsed.
-
parse
Parses text from a string to produce a range. The method attempts to parse text starting at the index given bypos
. If parsing succeeds, then the index ofpos
is updated to the index after the last character used, and the parsed range is returned. If an error occurs, then the index ofpos
is not changed, the error index ofpos
is set to the index of the character where the error occurred, andnull
is returned.- Parameters:
source
- the text, part of which should be parsed.pos
- index and error index information as described above.- Returns:
- a range parsed from the string, or
null
in case of error.
-
tryParse
Tries to parse the given text. In case of success, the error index is undetermined and need to be reset to -1. In case of failure (including an exception being thrown), the parse index is undetermined and need to be reset to its initial value.- Throws:
UnconvertibleObjectException
-
convert
Converts the given value to an instance of theelementType
type. This method is partially the converse oftoFormattable(Object)
.- Throws:
UnconvertibleObjectException
-
toFormattable
Converts the given object to a type thatformat(…)
method can process. This method is partially the converse ofconvert(Object)
. -
valueOfNil
Returns a "nil" value. This is used for creating empty ranges. -
clone
Returns a clone of this range format.
-