Symbols (Apache SIS 0.8 API)

Object
- Symbols

All Implemented Interfaces:: Serializable, Cloneable, Localized

public class Symbols
extends Object
implements Localized, Cloneable, Serializable

The set of symbols to use for Well Known Text (WKT) parsing and formatting. The two constants defined in this class, namely SQUARE_BRACKETS and CURLY_BRACKETS, define the symbols for ISO 19162 compliant WKT formatting. Their properties are:

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: ,

Users can create their own Symbols instance for parsing or formatting a WKT with different symbols.

Since:: 0.4
See Also:: WKTFormat.getSymbols(), WKTFormat.setSymbols(Symbols), Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static Symbols`	`CURLY_BRACKETS` A set of symbols with values between parentheses, like `DATUM("WGS84")`.
`static Symbols`	`SQUARE_BRACKETS` A set of symbols with values between square brackets, like `DATUM["WGS84"]`.

Constructor Summary

Constructors
Constructor and Description

Symbols(Symbols symbols)
Creates a new set of WKT symbols initialized to a copy of the given symbols.

Constructors
Constructor and Description
`Symbols(Symbols symbols)` Creates a new set of WKT symbols initialized to a copy of the given symbols.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Symbols`	`clone()` Returns a clone of this `Symbols`.
`boolean`	`containsAxis(CharSequence wkt)` Returns `true` if the given WKT contains at least one instance of the `AXIS[…]` element.
`boolean`	`containsElement(CharSequence wkt, String element)` Returns `true` if the given WKT contains at least one instance of the given element.
`boolean`	`equals(Object other)` Compares this `Symbols` with the given object for equality.
`int`	`getCloseSequence()` Returns the character used for closing a sequence of values.
`int`	`getClosingBracket(int index)` Returns the closing bracket character at the given index.
`int`	`getClosingQuote(int index)` Returns the closing quote character at the given index.
`static Symbols`	`getDefault()` Returns the default set of symbols.
`Locale`	`getLocale()` Returns the locale for formatting dates and numbers.
`int`	`getNumPairedBrackets()` Returns the number of paired brackets.
`int`	`getNumPairedQuotes()` Returns the number of paired quotes.
`int`	`getOpeningBracket(int index)` Returns the opening bracket character at the given index.
`int`	`getOpeningQuote(int index)` Returns the opening quote character at the given index.
`int`	`getOpenSequence()` Returns the character used for opening a sequence of values.
`String`	`getSeparator()` Returns the string used as a separator in a list of values.
`int`	`hashCode()` Returns a hash code value for this object.
`void`	`setLocale(Locale locale)` 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.

Methods inherited from class Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SQUARE_BRACKETS
```
public static final Symbols SQUARE_BRACKETS
```
    A set of symbols with values between square brackets, like DATUM["WGS84"]. This instance defines:
    - Locale.ROOT for decimal format symbols.
    - Square brackets by default, as in DATUM["WGS84"], but accepting also curly brackets as in DATUM("WGS84"). Both are legal WKT.
    - English quotation mark ('"') by default, but accepting also “…” quotes for more readable String constants in Java code.
    - Coma separator followed by a space (", ").
    This is the most frequently used WKT format for referencing objects.
  - CURLY_BRACKETS
```
public static final Symbols CURLY_BRACKETS
```
    A set of symbols with values between parentheses, like DATUM("WGS84"). This instance is identical to SQUARE_BRACKETS except that the default brackets are the curly ones instead than the square ones (but both are still accepted at parsing time).
    This format is rare with referencing objects but common with geometry objects.
- Constructor Detail
  - Symbols
```
public Symbols(Symbols symbols)
```
    Creates a new set of WKT symbols initialized to a copy of the given symbols.
    
    Parameters:
    
    symbols - the symbols to copy.
- Method Detail
  - getDefault
```
public static Symbols getDefault()
```
    Returns the default set of symbols. This is currently set to SQUARE_BRACKETS.
    
    Returns:
    
    the default set of symbols.
  - getLocale
```
public final Locale getLocale()
```
    Returns the locale for formatting dates and numbers. The default value is Locale.ROOT.
    Relationship between Symbols locale and WKTFormat locale
    The WKTFormat.getLocale(Locale.DISPLAY) property specifies the language to use when formatting InternationalString instances and can be set to any value. On the contrary, the Locale property of this Symbols class controls the decimal format symbols and is very rarely set to an other locale than Locale.ROOT.
    
    Specified by:
    
    getLocale in interface Localized
    
    Returns:
    
    the locale for dates and numbers.
    
    See Also:
    
    WKTFormat.getLocale(Locale.Category)
  - setLocale
```
public void setLocale(Locale locale)
```
    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.
  - 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(int), getClosingBracket(int)
  - 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 to getNumPairedBrackets() 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 to getNumPairedBrackets() 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
```
public void setPairedBrackets(String preferred,
                              String... alternatives)
```
    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:
    symbols.setPairedBrackets("()", "[]");
    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.
  - 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(int), getClosingQuote(int)
  - 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 to getNumPairedQuotes() 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 to getNumPairedQuotes() exclusive.
    
    Returns:
    
    the closing quote at the given index, as a Unicode code point.
    
    Throws:
    
    IndexOutOfBoundsException - if the given index is out of bounds.
  - setPairedQuotes
```
public void setPairedQuotes(String preferred,
                            String... alternatives)
```
    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 for String constants in Java code), but still accept the standard "…" quotation marks at parsing time:
    symbols.setPairedQuotes("“”", "\"\"");
    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.
  - 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.
  - getSeparator
```
public final String 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
```
public void setSeparator(String separator)
```
    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.
  - containsElement
```
public boolean containsElement(CharSequence wkt,
                               String element)
```
    Returns true if the given WKT contains at least one instance of the given element. Invoking this method is equivalent to invoking String.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 can not be preceded by other Unicode identifier characters.
    - The element found in the given WKT must be followed, ignoring space, by an opening bracket.
    The purpose of this method is to guess some characteristics about the encoded object without the cost of a full WKT parsing.
    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.
  - containsAxis
```
public boolean containsAxis(CharSequence wkt)
```
    Returns true if the given WKT contains at least one instance of the AXIS[…] element. Invoking this method is equivalent to invoking containsElement(wkt, "AXIS").
    Use case
    The check for axis elements is of particular interest because the axis order is a frequent cause of confusion when processing geographic data. Some applications just ignore any declared axis order in favor of their own hard-coded (longitude, latitude) axis order. Consequently, the presence of AXIS[…] elements in a WKT is an indication that the encoded object may not be understood as intended by some external software products.
    
    Parameters:
    
    wkt - the WKT to inspect.
    
    Returns:
    
    true if the given WKT contains at least one instance of the AXIS[…] element.
  - clone
```
public Symbols clone()
```
    Returns a clone of this Symbols.
    
    Overrides:
    
    clone in class Object
    
    Returns:
    
    a clone of this Symbols.
  - equals
```
public boolean equals(Object other)
```
    Compares this Symbols with the given object for equality.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    other - the object to compare with this Symbols.
    
    Returns:
    
    true if both objects are equal.
  - hashCode
```
public int hashCode()
```
    Returns a hash code value for this object.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    a hash code value.

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:	`,`

Class Symbols

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Detail

SQUARE_BRACKETS

CURLY_BRACKETS

Constructor Detail

Symbols

Method Detail

getDefault

getLocale

setLocale

getNumPairedBrackets

getOpeningBracket

getClosingBracket

setPairedBrackets

getNumPairedQuotes

getOpeningQuote

getClosingQuote

setPairedQuotes

getOpenSequence

getCloseSequence

setSequenceBrackets

getSeparator

setSeparator

containsElement

containsAxis

clone

equals

hashCode