CharacterReference
Date: 2016-12-04

net.htmlparser.jericho

## Class CharacterReference

- java.lang.Object
- - net.htmlparser.jericho.Segment
  - - net.htmlparser.jericho.CharacterReference

- All Implemented Interfaces:
    java.lang.CharSequence, java.lang.Comparable<Segment>
  Direct Known Subclasses:
    CharacterEntityReference, NumericCharacterReference

      public abstract class CharacterReference
      extends Segment

  Represents an HTML Character Reference, implemented by the subclasses `CharacterEntityReference` and `NumericCharacterReference`.

  This class, together with its subclasses, contains static methods to perform most required operations without having to instantiate an object.

  Instances of this class are useful when the positions of character references in a source document are required, or to replace the found character references with customised text.

  `CharacterReference` instances are obtained using one of the following methods:

  - `parse(CharSequence characterReferenceText)`
  - `Source.getNextCharacterReference(int pos)`
  - `Source.getPreviousCharacterReference(int pos)`
  - `Segment.getAllCharacterReferences()`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `INVALID_CODE_POINT` Represents an invalid unicode code point.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendCharTo(java.lang.Appendable appendable)` Appends the character represented by this character reference to the specified appendable object.
    `static java.lang.String` | `decode(java.lang.CharSequence encodedText)` Decodes the specified HTML encoded text into normal text.
    `static java.lang.String` | `decode(java.lang.CharSequence encodedText, boolean insideAttributeValue)` Decodes the specified HTML encoded text into normal text.
    `static java.lang.String` | `decodeCollapseWhiteSpace(java.lang.CharSequence text)` Decodes the specified text after collapsing its white space.
    `static java.lang.String` | `encode(char ch)` Encodes the specified character into a character reference if required.
    `static java.lang.String` | `encode(java.lang.CharSequence unencodedText)` Encodes the specified text, escaping special characters into character references.
    `static java.lang.String` | `encodeWithWhiteSpaceFormatting(java.lang.CharSequence unencodedText)` Encodes the specified text, preserving line breaks, tabs and spaces for rendering by converting them to markup.
    `char` | `getChar()` Returns the character represented by this character reference.
    `abstract java.lang.String` | `getCharacterReferenceString()` Returns the encoded form of this character reference.
    `static java.lang.String` | `getCharacterReferenceString(int codePoint)` Returns the encoded form of the specified unicode code point.
    `int` | `getCodePoint()` Returns the unicode code point represented by this character reference.
    `static int` | `getCodePointFromCharacterReferenceString(java.lang.CharSequence characterReferenceText)` Parses a single encoded character reference text into a unicode code point.
    `java.lang.String` | `getDecimalCharacterReferenceString()` Returns the decimal encoded form of this character reference.
    `static java.lang.String` | `getDecimalCharacterReferenceString(int codePoint)` Returns the decimal encoded form of the specified unicode code point.
    `static java.io.Writer` | `getEncodingFilterWriter(java.io.Writer writer)` Returns a filter `Writer` that encodes all text before passing it through to the specified `Writer`.
    `java.lang.String` | `getHexadecimalCharacterReferenceString()` Returns the hexadecimal encoded form of this character reference.
    `static java.lang.String` | `getHexadecimalCharacterReferenceString(int codePoint)` Returns the hexadecimal encoded form of the specified unicode code point.
    `java.lang.String` | `getUnicodeText()` Returns the unicode code point of this character reference in U+ notation.
    `static java.lang.String` | `getUnicodeText(int codePoint)` Returns the specified unicode code point in U+ notation.
    `boolean` | `isTerminated()` Indicates whether this character reference is terminated by a semicolon (`;`).
    `static CharacterReference` | `parse(java.lang.CharSequence characterReferenceText)` Parses a single encoded character reference text into a `CharacterReference` object.
    `static java.lang.String` | `reencode(java.lang.CharSequence encodedText)` Re-encodes the specified text, equivalent to decoding and then encoding again.
    `static boolean` | `requiresEncoding(char ch)` Indicates whether the specified character would need to be encoded in HTML text.

    - ### Methods inherited from class net.htmlparser.jericho.Segment

      `charAt, compareTo, encloses, encloses, equals, getAllCharacterReferences, getAllElements, getAllElements, getAllElements, getAllElements, getAllElements, getAllElementsByClass, getAllStartTags, getAllStartTags, getAllStartTags, getAllStartTags, getAllStartTags, getAllStartTagsByClass, getAllTags, getAllTags, getBegin, getChildElements, getDebugInfo, getEnd, getFirstElement, getFirstElement, getFirstElement, getFirstElement, getFirstElementByClass, getFirstStartTag, getFirstStartTag, getFirstStartTag, getFirstStartTag, getFirstStartTag, getFirstStartTagByClass, getFormControls, getFormFields, getMaxDepthIndicator, getNodeIterator, getRenderer, getRowColumnVector, getSource, getStyleURISegments, getTextExtractor, getURIAttributes, hashCode, ignoreWhenParsing, isWhiteSpace, isWhiteSpace, length, parseAttributes, subSequence, toString`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### INVALID_CODE_POINT

          public static final int INVALID_CODE_POINT

      Represents an invalid unicode code point.

      This can be the result of parsing a numeric character reference outside of the valid unicode range of 0x000000-0x10FFFF, or any other invalid character reference.

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getCodePoint

          public int getCodePoint()

      Returns the unicode code point represented by this character reference.
      Returns:
        the unicode code point represented by this character reference.
      See Also:
        `appendCharTo(Appendable)`

    - #### getChar

          public char getChar()

      Returns the character represented by this character reference.

      If this character reference represents a unicode supplimentary code point, any bits outside of the least significant 16 bits of the code point are truncated, yielding an incorrect result.

      To ensure that the character is correctly appended to an `Appendable` object such as a `Writer`, use the code:
      `characterReference.` `appendCharTo``(appendable)`
      instead of:
      `appendable.append(characterReference.getChar())`

      Returns:
        the character represented by this character reference.
      See Also:
        `appendCharTo(Appendable)`, `getCodePoint()`

    - #### appendCharTo

          public final void appendCharTo(java.lang.Appendable appendable)
                                  throws java.io.IOException

      Appends the character represented by this character reference to the specified appendable object.

      If this character is a unicode supplementary character, then both the UTF-16 high/low surrogate `char` values of the of the character are appended, as described in the Unicode character representations section of the `java.lang.Character` class.

      If the static `Config.ConvertNonBreakingSpaces` property is set to `true` (the default), then calling this method on a non-breaking space character reference (`&nbsp;`) results in a normal space being appended.

      Parameters:
        `appendable` - the object to append this character reference to.
      Throws:
        `java.io.IOException`

    - #### isTerminated

          public boolean isTerminated()

      Indicates whether this character reference is terminated by a semicolon (`;`).

      Conversely, this library defines an unterminated character reference as one which does not end with a semicolon.

      The SGML specification allows unterminated character references in some circumstances, and because the HTML 4.01 specification states simply that "authors may use SGML character references", it follows that they are also valid in HTML documents, although their use is strongly discouraged.

      Unterminated character references are not allowed in XHTML documents.

      Returns:
        `true` if this character reference is terminated by a semicolon, otherwise `false`.
      See Also:
        `decode(CharSequence encodedText, boolean insideAttributeValue)`

    - #### encode

          public static java.lang.String encode(java.lang.CharSequence unencodedText)

      Encodes the specified text, escaping special characters into character references.

      Each character is encoded only if the `requiresEncoding(char)` method would return `true` for that character, using its `CharacterEntityReference` if available, or a decimal `NumericCharacterReference` if its unicode code point is greater than U+007F.

      The only exception to this is an apostrophe (U+0027), which depending on the current setting of the static `Config.IsApostropheEncoded` property, is either left unencoded (default setting), or encoded as the numeric character reference "`&#39;`".

      This method never encodes an apostrophe into its character entity reference `&apos;` as this entity is not defined for use in HTML. See the comments in the `CharacterEntityReference` class for more information.

      To encode text using only numeric character references, use the
      `NumericCharacterReference.encode(CharSequence)` method instead.

      Parameters:
        `unencodedText` - the text to encode.
      Returns:
        the encoded string.
      See Also:
        `decode(CharSequence)`

    - #### encode

          public static java.lang.String encode(char ch)

      Encodes the specified character into a character reference if required.

      The encoding of the character follows the same rules as for each character in the `encode(CharSequence unencodedText)` method.

      Parameters:
        `ch` - the character to encode.
      Returns:
        a character reference if appropriate, otherwise a string containing the original character.

    - #### encodeWithWhiteSpaceFormatting

          public static java.lang.String encodeWithWhiteSpaceFormatting(java.lang.CharSequence unencodedText)

      Encodes the specified text, preserving line breaks, tabs and spaces for rendering by converting them to markup.

      This performs the same encoding as the `encode(CharSequence)` method, but also performs the following conversions:

      - Line breaks, being Carriage Return (U+000D) or Line Feed (U+000A) characters, and Form Feed characters (U+000C) are converted to "`<br />`". CR/LF pairs are treated as a single line break.
      - Multiple consecutive spaces are converted so that every second space is converted to "`&nbsp;`" while ensuring the last is always a normal space.
      - Tab characters (U+0009) are converted as if they were four consecutive spaces.

      The conversion of multiple consecutive spaces to alternating space/non-breaking-space allows the correct number of spaces to be rendered, but also allows the line to wrap in the middle of it.

      Note that zero-width spaces (U+200B) are converted to the numeric character reference "`&#x200B;`" through the normal encoding process, but IE6 does not render them properly either encoded or unencoded.

      There is no method provided to reverse this encoding.

      Parameters:
        `unencodedText` - the text to encode.
      Returns:
        the encoded string with white space formatting converted to markup.
      See Also:
        `encode(CharSequence)`

    - #### decode

          public static java.lang.String decode(java.lang.CharSequence encodedText)

      Decodes the specified HTML encoded text into normal text.

      All character entity references and numeric character references are converted to their respective characters.

      This is equivalent to `decode(encodedText,false)`.

      Unterminated character references are dealt with according to the rules for text outside of attribute values in the current compatibility mode.

      If the static `Config.ConvertNonBreakingSpaces` property is set to `true` (the default), then all non-breaking space (`&nbsp;`) character entity references are converted to normal spaces.

      Although character entity reference names are case sensitive, and in some cases differ from other entity references only by their case, some browsers also recognise them in a case-insensitive way. For this reason, all decoding methods in this library recognise character entity reference names even if they are in the wrong case.

      Parameters:
        `encodedText` - the text to decode.
      Returns:
        the decoded string.
      See Also:
        `encode(CharSequence)`

    - #### decode

          public static java.lang.String decode(java.lang.CharSequence encodedText,
                                boolean insideAttributeValue)

      Decodes the specified HTML encoded text into normal text.

      All character entity references and numeric character references are converted to their respective characters.

      Unterminated character references are dealt with according to the value of the `insideAttributeValue` parameter and the current compatibility mode.

      If the static `Config.ConvertNonBreakingSpaces` property is set to `true` (the default), then all non-breaking space (`&nbsp;`) character entity references are converted to normal spaces.

      Although character entity reference names are case sensitive, and in some cases differ from other entity references only by their case, some browsers also recognise them in a case-insensitive way. For this reason, all decoding methods in this library recognise character entity reference names even if they are in the wrong case.

      Parameters:
        `encodedText` - the text to decode.
        `insideAttributeValue` - specifies whether the encoded text is inside an attribute value.
      Returns:
        the decoded string.
      See Also:
        `decode(CharSequence)`, `encode(CharSequence)`

    - #### decodeCollapseWhiteSpace

          public static java.lang.String decodeCollapseWhiteSpace(java.lang.CharSequence text)

      Decodes the specified text after collapsing its white space.

      All leading and trailing white space is omitted, and any sections of internal white space are replaced by a single space.

      The result is how the text would normally be rendered by a user agent, assuming it does not contain any tags.

      If the static `Config.ConvertNonBreakingSpaces` property is set to `true` (the default), then all non-breaking space (`&nbsp;`) character entity references are converted to normal spaces.

      Unterminated character references are dealt with according to the rules for text outside of attribute values in the current compatibility mode. See the discussion of the `insideAttributeValue` parameter of the `decode(CharSequence, boolean insideAttributeValue)` method for a more detailed explanation of this topic.

      Parameters:
        `text` - the source text
      Returns:
        the decoded text with collapsed white space.
      See Also:
        `FormControl.getPredefinedValues()`

    - #### reencode

          public static java.lang.String reencode(java.lang.CharSequence encodedText)

      Re-encodes the specified text, equivalent to decoding and then encoding again.

      This process ensures that the specified encoded text does not contain any remaining unencoded characters.

      IMPLEMENTATION NOTE: At present this method simply calls the `decode` method followed by the `encode` method, but a more efficient implementation may be used in future.

      Parameters:
        `encodedText` - the text to re-encode.
      Returns:
        the re-encoded string.

    - #### getCharacterReferenceString

          public abstract java.lang.String getCharacterReferenceString()

      Returns the encoded form of this character reference.

      The exact behaviour of this method depends on the class of this object. See the `CharacterEntityReference.getCharacterReferenceString()` and `NumericCharacterReference.getCharacterReferenceString()` methods for more details.

      Examples:
        `CharacterReference.parse("&GT;").getCharacterReferenceString()` returns "`&gt;`"
        `CharacterReference.parse("&#x3E;").getCharacterReferenceString()` returns "`&#3e;`"
      Returns:
        the encoded form of this character reference.
      See Also:
        `getCharacterReferenceString(int codePoint)`, `getDecimalCharacterReferenceString()`

    - #### getCharacterReferenceString

          public static java.lang.String getCharacterReferenceString(int codePoint)

      Returns the encoded form of the specified unicode code point.

      This method returns the character entity reference encoded form of the unicode code point if one exists, otherwise it returns the decimal character reference encoded form.

      The only exception to this is an apostrophe (U+0027), which is encoded as the numeric character reference "`&#39;`" instead of its character entity reference "`&apos;`".

      Examples:
        `CharacterReference.getCharacterReferenceString(62)` returns "`&gt;`"
        `CharacterReference.getCharacterReferenceString('>')` returns "`&gt;`"
        `CharacterReference.getCharacterReferenceString('☺')` returns "`&#9786;`"
      Parameters:
        `codePoint` - the unicode code point to encode.
      Returns:
        the encoded form of the specified unicode code point.
      See Also:
        `getHexadecimalCharacterReferenceString(int codePoint)`

    - #### getDecimalCharacterReferenceString

          public java.lang.String getDecimalCharacterReferenceString()

      Returns the decimal encoded form of this character reference.

      This is equivalent to `getDecimalCharacterReferenceString``(``getCodePoint()``)`.

      Example:
        `CharacterReference.parse("&gt;").getDecimalCharacterReferenceString()` returns "`&#62;`"
      Returns:
        the decimal encoded form of this character reference.
      See Also:
        `getCharacterReferenceString()`, `getHexadecimalCharacterReferenceString()`

    - #### getDecimalCharacterReferenceString

          public static java.lang.String getDecimalCharacterReferenceString(int codePoint)

      Returns the decimal encoded form of the specified unicode code point.

      Example:
        `CharacterReference.getDecimalCharacterReferenceString('>')` returns "`&#62;`"
      Parameters:
        `codePoint` - the unicode code point to encode.
      Returns:
        the decimal encoded form of the specified unicode code point.
      See Also:
        `getCharacterReferenceString(int codePoint)`, `getHexadecimalCharacterReferenceString(int codePoint)`

    - #### getHexadecimalCharacterReferenceString

          public java.lang.String getHexadecimalCharacterReferenceString()

      Returns the hexadecimal encoded form of this character reference.

      This is equivalent to `getHexadecimalCharacterReferenceString``(``getCodePoint()``)`.

      Example:
        `CharacterReference.parse("&gt;").getHexadecimalCharacterReferenceString()` returns "`&#x3e;`"
      Returns:
        the hexadecimal encoded form of this character reference.
      See Also:
        `getCharacterReferenceString()`, `getDecimalCharacterReferenceString()`

    - #### getHexadecimalCharacterReferenceString

          public static java.lang.String getHexadecimalCharacterReferenceString(int codePoint)

      Returns the hexadecimal encoded form of the specified unicode code point.

      Example:
        `CharacterReference.getHexadecimalCharacterReferenceString('>')` returns "`&#x3e;`"
      Parameters:
        `codePoint` - the unicode code point to encode.
      Returns:
        the hexadecimal encoded form of the specified unicode code point.
      See Also:
        `getCharacterReferenceString(int codePoint)`, `getDecimalCharacterReferenceString(int codePoint)`

    - #### getUnicodeText

          public java.lang.String getUnicodeText()

      Returns the unicode code point of this character reference in U+ notation.

      This is equivalent to `getUnicodeText(getCodePoint())`.

      Example:
        `CharacterReference.parse("&gt;").getUnicodeText()` returns "`U+003E`"
      Returns:
        the unicode code point of this character reference in U+ notation.
      See Also:
        `getUnicodeText(int codePoint)`

    - #### getUnicodeText

          public static java.lang.String getUnicodeText(int codePoint)

      Returns the specified unicode code point in U+ notation.

      Example:
        `CharacterReference.getUnicodeText('>')` returns "`U+003E`"
      Parameters:
        `codePoint` - the unicode code point.
      Returns:
        the specified unicode code point in U+ notation.

    - #### parse

          public static CharacterReference parse(java.lang.CharSequence characterReferenceText)

      Parses a single encoded character reference text into a `CharacterReference` object.

      The character reference must be at the start of the given text, but may contain other characters at the end. The `getEnd()` method can be used on the resulting object to determine at which character position the character reference ended.

      If the text does not represent a valid character reference, this method returns `null`.

      Unterminated character references are always accepted, regardless of the settings in the current compatibility mode.

      To decode all character references in a given text, use the `decode(CharSequence)` method instead.

      Example:
        `CharacterReference.parse("&gt;").getChar()` returns '`>`'
      Parameters:
        `characterReferenceText` - the text containing a single encoded character reference.
      Returns:
        a `CharacterReference` object representing the specified text, or `null` if the text does not represent a valid character reference.
      See Also:
        `decode(CharSequence)`

    - #### getCodePointFromCharacterReferenceString

          public static int getCodePointFromCharacterReferenceString(java.lang.CharSequence characterReferenceText)

      Parses a single encoded character reference text into a unicode code point.

      The character reference must be at the start of the given text, but may contain other characters at the end.

      If the text does not represent a valid character reference, this method returns `INVALID_CODE_POINT`.

      This is equivalent to `parse(characterReferenceText)``.``getCodePoint()`, except that it returns `INVALID_CODE_POINT` if an invalid character reference is specified instead of throwing a `NullPointerException`.

      Example:
        `CharacterReference.getCodePointFromCharacterReferenceString("&gt;")` returns `38`
      Parameters:
        `characterReferenceText` - the text containing a single encoded character reference.
      Returns:
        the unicode code point representing representing the specified text, or `INVALID_CODE_POINT` if the text does not represent a valid character reference.

    - #### requiresEncoding

          public static final boolean requiresEncoding(char ch)

      Indicates whether the specified character would need to be encoded in HTML text.

      This is the case if a character entity reference exists for the character, or the unicode code point is greater than U+007F.

      The only exception to this is an apostrophe (U+0027), which only returns `true` if the static `Config.IsApostropheEncoded` property is currently set to `true`.

      Parameters:
        `ch` - the character to test.
      Returns:
        `true` if the specified character would need to be encoded in HTML text, otherwise `false`.

    - #### getEncodingFilterWriter

          public static java.io.Writer getEncodingFilterWriter(java.io.Writer writer)

      Returns a filter `Writer` that encodes all text before passing it through to the specified `Writer`.
      Parameters:
        `writer` - the destination for the encoded text
      Returns:
        a filter `Writer` that encodes all text before passing it through to the specified `Writer`.
      See Also:
        `encode(CharSequence unencodedText)`