Package org.apache.sis.io.wkt
Class Symbols
java.lang.Object
org.apache.sis.io.wkt.Symbols
- All Implemented Interfaces:
Serializable
,Cloneable
,Localized
The set of symbols to use for Well Known Text (WKT) parsing and formatting.
The two constants defined in this class, namely
Users can create their own
SQUARE_BRACKETS
and CURLY_BRACKETS
,
define the symbols for ISO 19162 compliant WKT formatting. Their properties are:
WKT aspect | Standard value | Comment |
---|---|---|
Locale for number format: | Locale.ROOT |
|
Bracket symbols: | [ …] or ( …) |
Note: the […] brackets are common in referencing WKT,
while the (…) brackets are common in geometry WKT. |
Quote symbols: | " …" |
Note: Apache SIS accepts also “…” quotes
for more readable String literals in Java code, but this is non-standard. |
Sequence symbols: | { …} |
|
Separator: | , |
Symbols
instance for parsing or formatting a WKT with different symbols.- Since:
- 0.4
- Version:
- 1.3
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate int[]
List of characters (as Unicode code points) acceptable as opening or closing brackets.private int
The character (as Unicode code point) used for opening (openSequence
) or closing (closeSequence
) an array or enumeration.static final Symbols
A set of symbols with values between parentheses, likeDATUM("WGS84")
.(package private) static final char
The prefix character for the value of a WKT fragment.private boolean
true
if this instance shall be considered as immutable.private Locale
The locale of decimal format symbols or other symbols.(package private) static final char
Separator between numbers in a sequence of numbers.private int
The character (as Unicode code point) used for opening (openSequence
) or closing (closeSequence
) an array or enumeration.private String
The preferred closing quote character (quotes[1]
) as a string.private int[]
List of characters (as Unicode code point) used for opening or closing a quoted text.(package private) static final boolean
Set totrue
if parsing and formatting of numbers in scientific notation is allowed.private String
The string used as a separator in a list of values.private static final long
For cross-version compatibility.static final Symbols
A set of symbols with values between square brackets, likeDATUM["WGS84"]
.private String
Same value thanseparator
but without leading and trailing spaces. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Symbols
(int[] brackets, int[] quotes) Constructor reserved toSQUARE_BRACKETS
andCURLY_BRACKETS
constants.Creates a new set of WKT symbols initialized to a copy of the given symbols. -
Method Summary
Modifier and TypeMethodDescriptionprivate void
Throws an exception if this set of symbols is immutable.clone()
Returns a clone of thisSymbols
.boolean
containsElement
(CharSequence wkt, String element) Returnstrue
if the given WKT contains at least one instance of the given element.private boolean
containsElement
(CharSequence wkt, String element, int offset) Implementation ofcontainsElement(CharSequence, String)
without verification of argument validity.(package private) final NumberFormat
Creates a new number format to use for parsing and formatting.private static void
ensureValidQuoteOrBracket
(String name, int code) Ensures that the given code point is a valid Unicode code point but not a Unicode identifier part.boolean
Compares thisSymbols
with the given object for equality.final int
Returns the character used for closing a sequence of values.final int
getClosingBracket
(int index) Returns the closing bracket character at the given index.final int
getClosingQuote
(int index) Returns the closing quote character at the given index.static Symbols
Returns the default set of symbols.final Locale
Returns the locale for formatting dates and numbers.final int
Returns the number of paired brackets.final int
Returns the number of paired quotes.final int
getOpeningBracket
(int index) Returns the opening bracket character at the given index.final int
getOpeningQuote
(int index) Returns the opening quote character at the given index.final int
Returns the character used for opening a sequence of values.(package private) final String
getQuote()
Returns the preferred closing quote character as a string.final String
Returns the string used as a separator in a list of values.int
hashCode()
Returns a hash code value for this object.(package private) final Symbols
Returns an immutable copy of this set of symbols, orthis
if this instance is already immutable.private static int
matching
(int[] chars, int c) Implementation ofmatchingBracket(int)
andmatchingQuote(int)
.(package private) final int
matchingBracket
(int c) If the given character is an opening bracket, returns the matching closing bracket.(package private) final int
matchingQuote
(int c) If the given character is an opening quote, returns the matching closing quote.(package private) final Object
Invoked on deserialization for replacing the deserialized instance by the constant instance.(package private) final String
Returns the value ofgetSeparator()
without trailing spaces, followed by the system line separator.void
Sets the locale of decimal format symbols or other symbols.void
setPairedBrackets
(String preferred, String... alternatives) Sets the opening and closing brackets to the given pairs.void
setPairedQuotes
(String preferred, String... alternatives) Sets the opening and closing quotes to the given pairs.void
setSeparator
(String separator) Sets the string to use as a separator in a list of values.void
setSequenceBrackets
(int openSequence, int closeSequence) Sets the characters used for opening and closing a sequence of values.private static int[]
toCodePoints
(String preferred, String[] alternatives) Packs the given pairs of bracket or quotes in a single array of code points.(package private) final String
Returns the separator without trailing spaces.(package private) final boolean
useScientificNotation
(double abs) Returnstrue
if the formatter should use scientific notation for the given value.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
SCIENTIFIC_NOTATION
Set totrue
if parsing and formatting of numbers in scientific notation is allowed. The way to achieve that is currently a hack, becauseNumberFormat
has no API for managing that as of JDK 1.8.- See Also:
-
NUMBER_SEPARATOR
static final char NUMBER_SEPARATORSeparator between numbers in a sequence of numbers. This is used for example between the coordinates of a point.- See Also:
-
FRAGMENT_VALUE
static final char FRAGMENT_VALUEThe prefix character for the value of a WKT fragment.- See Also:
-
SQUARE_BRACKETS
A set of symbols with values between square brackets, likeDATUM["WGS84"]
. This instance defines:Locale.ROOT
for decimal format symbols.- Square brackets by default, as in
DATUM["WGS84"]
, but accepting also curly brackets as inDATUM("WGS84")
. Both are legal WKT. - English quotation mark (
'"'
) by default, but accepting also “…” quotes for more readableString
constants in Java code. - Coma separator followed by a space (
", "
).
-
CURLY_BRACKETS
A set of symbols with values between parentheses, likeDATUM("WGS84")
. This instance is identical toSQUARE_BRACKETS
except that the default brackets are the curly ones instead of the square ones (but both are still accepted at parsing time).This format is rare with referencing objects but common with geometry objects.
-
locale
The locale of decimal format symbols or other symbols.- See Also:
-
brackets
private int[] bracketsList of characters (as Unicode code points) acceptable as opening or closing brackets. The array shall comply to the following restrictions:- The characters at index 0 and 1 are the preferred opening and closing brackets respectively.
- For each even index i,
brackets[i+1]
is the closing bracket matchingbrackets[i]
.
- See Also:
-
quotes
private int[] quotesList of characters (as Unicode code point) used for opening or closing a quoted text. The array shall comply to the following restrictions:- The characters at index 0 and 1 are the preferred opening and closing quotes respectively.
- For each even index i,
quotes[i+1]
is the closing quote matchingquotes[i]
.
'"'
. -
quote
The preferred closing quote character (quotes[1]
) as a string. We use the closing quote because this is the character that the parser will look for determining the text end.- See Also:
-
openSequence
private int openSequenceThe character (as Unicode code point) used for opening (openSequence
) or closing (closeSequence
) an array or enumeration. -
closeSequence
private int closeSequenceThe character (as Unicode code point) used for opening (openSequence
) or closing (closeSequence
) an array or enumeration. -
separator
The string used as a separator in a list of values. This is usually", "
, but may be different if a non-English locale is used for formatting numbers. -
trimmedSeparator
Same value thanseparator
but without leading and trailing spaces. -
isImmutable
private boolean isImmutabletrue
if this instance shall be considered as immutable.
-
-
Constructor Details
-
Symbols
Creates a new set of WKT symbols initialized to a copy of the given symbols.- Parameters:
symbols
- the symbols to copy.
-
Symbols
private Symbols(int[] brackets, int[] quotes) Constructor reserved toSQUARE_BRACKETS
andCURLY_BRACKETS
constants. The given array is stored by reference - it is not cloned.
-
-
Method Details
-
checkWritePermission
Throws an exception if this set of symbols is immutable.- Throws:
UnsupportedOperationException
-
getDefault
Returns the default set of symbols. This is currently set toSQUARE_BRACKETS
.- Returns:
- the default set of symbols.
-
getLocale
Returns the locale for formatting dates and numbers. The default value isLocale.ROOT
.Relationship between
TheSymbols
locale andWKTFormat
localeWKTFormat.getLocale(Locale.DISPLAY)
property specifies the language to use when formattingInternationalString
instances and can be set to any value. On the contrary, theLocale
property of thisSymbols
class controls the decimal format symbols and is very rarely set to another locale thanLocale.ROOT
. -
setLocale
Sets the locale of decimal format symbols or other symbols. Note that any non-English locale is likely to produce WKT that do not conform to ISO 19162. Such WKT can be used for human reading, but not for data export.- Parameters:
locale
- the new symbols locale.- Throws:
UnsupportedOperationException
- if thisSymbols
instance is immutable.
-
matching
private static int matching(int[] chars, int c) Implementation ofmatchingBracket(int)
andmatchingQuote(int)
. -
matchingBracket
final int matchingBracket(int c) If the given character is an opening bracket, returns the matching closing bracket. Otherwise returns -1. -
getNumPairedBrackets
public final int getNumPairedBrackets()Returns the number of paired brackets. For example if the WKT parser accepts both the[…]
and(…)
bracket pairs, then this method returns 2.- Returns:
- the number of bracket pairs.
- See Also:
-
getOpeningBracket
public final int getOpeningBracket(int index) Returns the opening bracket character at the given index. Index 0 stands for the default bracket used at formatting time. All other index are for optional brackets accepted at parsing time.- Parameters:
index
- index of the opening bracket to get, from 0 togetNumPairedBrackets()
exclusive.- Returns:
- the opening bracket at the given index, as a Unicode code point.
- Throws:
IndexOutOfBoundsException
- if the given index is out of bounds.
-
getClosingBracket
public final int getClosingBracket(int index) Returns the closing bracket character at the given index. Index 0 stands for the default bracket used at formatting time. All other index are for optional brackets accepted at parsing time.- Parameters:
index
- index of the closing bracket to get, from 0 togetNumPairedBrackets()
exclusive.- Returns:
- the closing bracket at the given index, as a Unicode code point.
- Throws:
IndexOutOfBoundsException
- if the given index is out of bounds.
-
setPairedBrackets
Sets the opening and closing brackets to the given pairs. Each string shall contain exactly two code points (usually two characters). The first code point is taken as the opening bracket, and the second code point as the closing bracket.Example: The following code will instruct the WKT formatter to use the (…) pair of brackets at formatting time, but still accept the more common […] pair of brackets at parsing time:- Parameters:
preferred
- the preferred pair of opening and closing quotes, used at formatting time.alternatives
- alternative pairs of opening and closing quotes accepted at parsing time.- Throws:
UnsupportedOperationException
- if thisSymbols
instance is immutable.
-
matchingQuote
final int matchingQuote(int c) If the given character is an opening quote, returns the matching closing quote. Otherwise returns -1. -
getNumPairedQuotes
public final int getNumPairedQuotes()Returns the number of paired quotes. For example if the WKT parser accepts both the"…"
and“…”
quote pairs, then this method returns 2.- Returns:
- the number of quote pairs.
- See Also:
-
getOpeningQuote
public final int getOpeningQuote(int index) Returns the opening quote character at the given index. Index 0 stands for the default quote used at formatting time, which is usually'"'
. All other index are for optional quotes accepted at parsing time.- Parameters:
index
- index of the opening quote to get, from 0 togetNumPairedQuotes()
exclusive.- Returns:
- the opening quote at the given index, as a Unicode code point.
- Throws:
IndexOutOfBoundsException
- if the given index is out of bounds.
-
getClosingQuote
public final int getClosingQuote(int index) Returns the closing quote character at the given index. Index 0 stands for the default quote used at formatting time, which is usually'"'
. All other index are for optional quotes accepted at parsing time.- Parameters:
index
- index of the closing quote to get, from 0 togetNumPairedQuotes()
exclusive.- Returns:
- the closing quote at the given index, as a Unicode code point.
- Throws:
IndexOutOfBoundsException
- if the given index is out of bounds.
-
getQuote
Returns the preferred closing quote character as a string. This is the quote to double if it appears in a Unicode string to format. We check for the closing quote because this is the one that the parser will look for determining the text end. -
setPairedQuotes
Sets the opening and closing quotes to the given pairs. Each string shall contain exactly two code points (usually two characters). The first code point is taken as the opening quote, and the second code point as the closing quote.Example: The following code will instruct the WKT formatter to use the prettier “…” quotation marks at formatting time (especially useful forString
constants in Java code), but still accept the standard "…" quotation marks at parsing time:- Parameters:
preferred
- the preferred pair of opening and closing quotes, used at formatting time.alternatives
- alternative pairs of opening and closing quotes accepted at parsing time.- Throws:
UnsupportedOperationException
- if thisSymbols
instance is immutable.
-
toCodePoints
Packs the given pairs of bracket or quotes in a single array of code points. This method also verifies arguments validity. -
ensureValidQuoteOrBracket
Ensures that the given code point is a valid Unicode code point but not a Unicode identifier part. -
getOpenSequence
public final int getOpenSequence()Returns the character used for opening a sequence of values. This is usually'{'
.- Returns:
- the character used for opening a sequence of values, as a Unicode code point.
-
getCloseSequence
public final int getCloseSequence()Returns the character used for closing a sequence of values. This is usually'}'
.- Returns:
- the character used for closing a sequence of values, as a Unicode code point.
-
setSequenceBrackets
public void setSequenceBrackets(int openSequence, int closeSequence) Sets the characters used for opening and closing a sequence of values.- Parameters:
openSequence
- the character for opening a sequence of values, as a Unicode code point.closeSequence
- the character for closing a sequence of values, as a Unicode code point.- Throws:
UnsupportedOperationException
- if thisSymbols
instance is immutable.
-
getSeparator
Returns the string used as a separator in a list of values. This is usually", "
, but may be different if a non-English locale is used for formatting numbers.- Returns:
- the string used as a separator in a list of values.
-
setSeparator
Sets the string to use as a separator in a list of values. The given string will be used "as-is" at formatting time, but leading and trailing spaces will be ignored at parsing time.- Parameters:
separator
- the new string to use as a separator in a list of values.- Throws:
UnsupportedOperationException
- if thisSymbols
instance is immutable.
-
trimmedSeparator
Returns the separator without trailing spaces. -
separatorNewLine
Returns the value ofgetSeparator()
without trailing spaces, followed by the system line separator. -
createNumberFormat
Creates a new number format to use for parsing and formatting. EachWKTFormat
will create its own instance, sinceNumberFormat
s are not guaranteed to be thread-safe.Scientific notation
TheNumberFormat
created here does not use scientific notation. This is okay for many WKT formatting purpose since Earth ellipsoid axis lengths in metres are large enough for triggering scientific notation, while we want to express them as normal numbers with centimetre precision. However, this is problematic for small numbers like 1E-5. Callers may need to adjust the precision depending on the kind of numbers (length or angle) to format. -
useScientificNotation
final boolean useScientificNotation(double abs) Returnstrue
if the formatter should use scientific notation for the given value. We use scientific notation if the number magnitude is too high or too low. The threshold values used here may be different than the threshold values used in the standardStringBuilder.append(double)
method. In particular, we use a higher threshold for large numbers because ellipsoid axis lengths are above the JDK threshold when the axis length is given in feet (about 2.1E+7) while we still want to format them as usual numbers. Note that we perform this special formatting only if the 'NumberFormat' is not localized (which is the usual case).- Parameters:
abs
- the absolute value of the number to format.
-
containsElement
Returnstrue
if the given WKT contains at least one instance of the given element. Invoking this method is equivalent to invokingString.contains(CharSequence)
except for the following:- The search is case-insensitive.
- Characters between opening quotes and closing quotes are ignored.
- The element found in the given WKT cannot be preceded by other Unicode identifier characters.
- The element found in the given WKT must be followed, ignoring space, by an opening bracket.
Example:containsElement(wkt, "AXIS")
returnstrue
if the given WKT contains at least one instance of theAXIS[…]
element, ignoring case.- Parameters:
wkt
- the WKT to inspect.element
- the element to search for.- Returns:
true
if the given WKT contains at least one instance of the given element.
-
containsElement
Implementation ofcontainsElement(CharSequence, String)
without verification of argument validity.- Parameters:
wkt
- the WKT to inspect.element
- the element to search. Must contains only uppercase letters.offset
- the index to start the search from.
-
immutable
Returns an immutable copy of this set of symbols, orthis
if this instance is already immutable. -
clone
Returns a clone of thisSymbols
. The returned instance is modifiable (i.e. setter methods will not throwUnsupportedOperationException
). -
equals
Compares thisSymbols
with the given object for equality. -
hashCode
public int hashCode()Returns a hash code value for this object. -
readResolve
Invoked on deserialization for replacing the deserialized instance by the constant instance. This method also opportunistically recompute thequote
field if no replacement is done.- Returns:
- the object to use after deserialization.
- Throws:
ObjectStreamException
- required by specification but should never be thrown.
-