net.sf.okapi.lib.xliff2.core

## Class Fragment

- java.lang.Object
- - net.sf.okapi.lib.xliff2.core.Fragment

- All Implemented Interfaces:
    java.lang.Appendable, java.lang.Iterable<java.lang.Object>

      public class Fragment
      extends java.lang.Object
      implements java.lang.Iterable<java.lang.Object>, java.lang.Appendable

  Represents a fragment of extracted content. A fragment is the content of a source or target in a `Part` or `Segment`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static char` | `CODE_CLOSING` First character of the special pair indicating a reference to the closing tag of a code (a `CTag`).
    `static char` | `CODE_OPENING` First character of the special pair indicating a reference to the opening tag of a code (a `CTag`).
    `static char` | `CODE_STANDALONE` First character of the special pair indicating a reference to the standalone tag of a code (a `CTag`).
    `static char` | `MARKER_CLOSING` First character of the special pair indicating a reference to the closing tag of a marker (a `MTag`).
    `static char` | `MARKER_OPENING` First character of the special pair indicating a reference to the opening tag of a marker (a `MTag`).
    `static char` | `PCONT_STANDALONE` First character of the special pair indicating a reference to the standalone holder for a protected content (a `PCont`).
    `static int` | `TAGREF_BASE` Base value for the tag reference index.
    `static int` | `TAGREF_MAX` Maximum number of tag possible per unit for a given type of tag: 6127.
    `static java.util.regex.Pattern` | `TAGREF_REGEX` Compiled regular expression for all possible kinds of tag reference (the two characters) in a coded text.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Fragment(Fragment original, Store store, boolean target)` Copy constructor.
    `Fragment(Store store, boolean target)` Creates a new source or target `Fragment` object.
    `Fragment(Store store, boolean target, java.lang.String plainText)` Creates a new source or target `Fragment` object with a content.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `annotate(int start, int end, MTag opening)` Annotates a span of content in this fragment.
    `int` | `annotate(int start, int end, java.lang.String type, java.lang.String value, java.lang.String ref)` Annotates a span of content in this fragment.
    `Fragment` | `append(char ch)` Appends a character at the end of this fragment.
    `Fragment` | `append(java.lang.CharSequence plainText)` Appends a plain text string to this fragment.
    `Fragment` | `append(java.lang.CharSequence plainText, int start, int end)` Appends a sub-sequence of a given plain text string to this fragment.
    `void` | `append(Fragment fragment)` Appends a fragment to this fragment.
    `Tag` | `append(Tag tag)` Appends a tag to this fragment.
    `CTag` | `append(TagType tagType, java.lang.String id, java.lang.String data, boolean canOverlap)` Appends a code tag.
    `CTag` | `appendCode(java.lang.String id, java.lang.String data)` Appends a standalone code to this fragment.
    `void` | `checkPosition(int position)` Verifies if a given position in the coded text is on the second special character of a tag reference.
    `void` | `clear()` Clears the fragment: removes all tags and text.
    `CTag` | `closeCodeSpan(java.lang.String id, java.lang.String data)` Creates at the end of this fragment a closing tag for an existing code.
    `MTag` | `closeMarkerSpan(java.lang.String id)` Appends a tag to close the marker of a given id.
    `Fragment` | `delete(int start, int end)` Deletes a section of this fragment (including any protected content within the section).
    `boolean` | `equals(java.lang.Object object)` Indicates if this fragment equals another object.
    `int` | `getClosingPosition(Tag opening)` Gets the closing position of a span of content in this fragment for a given opening tag.
    `Tag` | `getClosingTag(Tag tag)` Gets the closing tag corresponding to a given opening tag within a unit.
    `java.lang.String` | `getCodedText()` Gets the content of this fragment in coded text format.
    `static int` | `getCodedTextPosition(java.lang.CharSequence codedText, int plainTextPosition, boolean leftOfTag)` Gets the coded text position in a given coded text string for a given plain text position.
    `int` | `getCodedTextPosition(int plainTextPosition, boolean leftOfTag)` Helper methods calling `getCodedTextPosition(CharSequence, int, boolean)` with the coded text of this fragment as the first parameter.
    `CTag` | `getCTag(java.lang.CharSequence ctext, int pos)` Gets the `CTag` for a given reference in a coded text.
    `Directionality` | `getDir(boolean resolved)`
    `<T> java.lang.Iterable<T>` | `getIterable(java.lang.Class<T> type)` Creates a new instance of an iterable interface for a given class of objects.
    `MTag` | `getMTag(java.lang.CharSequence ctext, int pos)` Gets the `MTag` for a given reference in a coded text.
    `Tag` | `getOpeningTag(Tag tag)` Gets the opening tag corresponding to a given closing tag within a unit.
    `MTag` | `getOrCreateMarker(int start, int end, java.lang.String matchingType, java.lang.String typeForNew)` Get or create an annotation marker for a given span of content.
    `java.util.List<Tag>` | `getOwnTags()` Creates a list of all the source or target tags in this fragment.
    `java.util.Map<Tag,java.lang.Integer>` | `getOwnTagsStatus()` Creates a map of the opening and closing tags in this fragment and their corresponding status as tag: (0=isolated, 1=not-well-formed or 2=well-formed).
    `java.lang.String` | `getPlainText()` Gets a plain text version (all tag references stripped out) of the content of this fragment.
    `Store` | `getStore()` Gets the store associated with this fragment.
    `Tag` | `getTag(java.lang.CharSequence ctext, int pos)` Gets the `MTag` or `CTag` for a given reference in a coded text.
    `Tag` | `getTag(int key)` Gets the tag for a given key.
    `Tags` | `getTags()` Gets the source or target tags for the unit where this segment is located.
    `Tag` | `getWellFormedClosing(Tag opening, int from)` Gets the well-formed closing tag for a given opening one, starting at a given character position.
    `static boolean` | `hasContentAfter(java.lang.String codedText, int position)` Indicates if a given coded text has any non-marker tags at or after a given position.
    `int` | `hashCode()`
    `boolean` | `hasTag()` Indicates if this fragment contains at least one tag.
    `Fragment` | `insert(java.lang.CharSequence plainText, int offset)` Inserts a plain text at a given position.
    `CTag` | `insert(TagType tagType, java.lang.String type, java.lang.String id, java.lang.String data, int offset, boolean connect, boolean allowOrphan)` Inserts a code at a given position (including the end) of this fragment.
    `static boolean` | `isChar1(char value)` Helper method that checks if a given character is the first special character of a tag reference.
    `static boolean` | `isCTag(char value)` Indicates if a given character is the first special character of a `CTag` reference.
    `boolean` | `isEmpty()` Indicates if this fragment is empty.
    `boolean` | `isTarget()` Indicates if this fragment is a target content.
    `java.util.Iterator<java.lang.Object>` | `iterator()` Creates an iterator for all the different objects composing this fragment.
    `CTag` | `openCodeSpan(java.lang.String id, java.lang.String data)` Creates at the end of this fragment an opening tag for a new code.
    `MTag` | `openMarkerSpan(java.lang.String id, java.lang.String type)` Appends a tag opening a new marker span.
    `static void` | `printCommonAttributes(CTag code, Tags tags, java.lang.StringBuilder tmp, CTag closing, boolean outputDataRefEnd)` Output the common attributes for a given CTag object.
    `static void` | `printExtAttributes(Tag tag, java.lang.StringBuilder output, java.util.Stack<NSContext> nsStack)`
    `void` | `remove(Tag tag)` Removes a tag from this fragment (including if the tag is in a protected content).
    `void` | `setCodedText(java.lang.String codedText)` Sets the coded text content for this fragment.
    `void` | `setDir(Directionality dir)` Sets the directionality for this fragment.
    `void` | `showProtectedContent()` Expands all `PCont` references in this fragment into normal content.
    `static char` | `toChar1(int key)` Gets the first character of a tag reference from a given tag key.
    `static char` | `toChar2(int key)` Gets the second character of a tag reference from a given tag key.
    `static int` | `toKey(int c1, int c2)` Converts the first and second character of a tag reference to the key of the tag.
    `static java.lang.String` | `toRef(int key)` Converts a tag key to a reference as used in the coded text
    `java.lang.String` | `toString()` Returns a string representation of the fragment: the text in coded text format.
    `java.lang.String` | `toXLIFF()` Creates an XLIFF output of this fragment, without handling the inline codes original data, without namespace content and without inherited data context.
    `java.lang.String` | `toXLIFF(java.util.Stack<NSContext> nsStack, java.util.Stack<InheritedData> context, boolean withOriginalData)` Creates an XLIFF output for this fragment.
    `boolean` | `unitHasOpening(CTag ctag)` Tests if the unit to which this fragment belongs has an opening code for a given closing code.

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

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

- - ### Field Detail

    - #### CODE_OPENING

          public static final char CODE_OPENING

      First character of the special pair indicating a reference to the opening tag of a code (a `CTag`).
      See Also:
        Constant Field Values

    - #### CODE_CLOSING

          public static final char CODE_CLOSING

      First character of the special pair indicating a reference to the closing tag of a code (a `CTag`).
      See Also:
        Constant Field Values

    - #### CODE_STANDALONE

          public static final char CODE_STANDALONE

      First character of the special pair indicating a reference to the standalone tag of a code (a `CTag`).
      See Also:
        Constant Field Values

    - #### MARKER_OPENING

          public static final char MARKER_OPENING

      First character of the special pair indicating a reference to the opening tag of a marker (a `MTag`).
      See Also:
        Constant Field Values

    - #### MARKER_CLOSING

          public static final char MARKER_CLOSING

      First character of the special pair indicating a reference to the closing tag of a marker (a `MTag`).
      See Also:
        Constant Field Values

    - #### PCONT_STANDALONE

          public static final char PCONT_STANDALONE

      First character of the special pair indicating a reference to the standalone holder for a protected content (a `PCont`).
      See Also:
        Constant Field Values

    - #### TAGREF_BASE

          public static final int TAGREF_BASE

      Base value for the tag reference index.
      See Also:
        Constant Field Values

    - #### TAGREF_MAX

          public static final int TAGREF_MAX

      Maximum number of tag possible per unit for a given type of tag: 6127.
      See Also:
        Constant Field Values

    - #### TAGREF_REGEX

          public static final java.util.regex.Pattern TAGREF_REGEX

      Compiled regular expression for all possible kinds of tag reference (the two characters) in a coded text.

  - ### Constructor Detail

    - #### Fragment

          public Fragment(Fragment original,
                  Store store,
                  boolean target)

      Copy constructor.
      Parameters:
        `original` - the original fragment to duplicate.
        `store` - the store to attach to the new fragment.
        `target` - true if the new fragment is a target, false if it is a source.

    - #### Fragment

          public Fragment(Store store,
                  boolean target)

      Creates a new source or target `Fragment` object.
      Parameters:
        `store` - the shared `Store` for this object.
        `target` - true if this fragment is a target fragment, false if it is a source fragment.

    - #### Fragment

          public Fragment(Store store,
                  boolean target,
                  java.lang.String plainText)

      Creates a new source or target `Fragment` object with a content.
      Parameters:
        `store` - the shared `Store` for this object.
        `target` - true if this fragment is a target fragment, false if it is a source fragment.
        `plainText` - the content of this fragment.

  - ### Method Detail

    - #### toKey

          public static int toKey(int c1,
                  int c2)

      Converts the first and second character of a tag reference to the key of the tag.

      Note that both parameters are passed as integer for convenience, but they are characters.

      Parameters:
        `c1` - the first character of the reference (the type of inline object and the type of tag).
        `c2` - the second character of the reference (the encoded 'index' part of the key)
      Returns:
        the key for the given tag reference.
      See Also:
        `toChar1(int)`, `toChar2(int)`, `toRef(int)`

    - #### toChar1

          public static char toChar1(int key)

      Gets the first character of a tag reference from a given tag key.
      Parameters:
        `key` - the key to process.
      Returns:
        the first character of the tag reference for the given tag key.
      See Also:
        `toChar2(int)`, `toRef(int)`, `toKey(int, int)`

    - #### toChar2

          public static char toChar2(int key)

      Gets the second character of a tag reference from a given tag key.
      Parameters:
        `key` - the key to process.
      Returns:
        the second character of the tag reference for the given tag key.
      See Also:
        `toChar1(int)`, `toRef(int)`, `toKey(int, int)`

    - #### toRef

          public static java.lang.String toRef(int key)

      Converts a tag key to a reference as used in the coded text
      Parameters:
        `key` - the key to convert
      Returns:
        the tag reference for the given key.
      See Also:
        `toKey(int, int)`, `toChar1(int)`, `toChar2(int)`

    - #### isChar1

          public static boolean isChar1(char value)

      Helper method that checks if a given character is the first special character of a tag reference. If it is true, the next character is the second character of a tag reference and the key for the tag can be obtained using `toKey(int, int)`.
      Parameters:
        `value` - the character to check.
      Returns:
        true if the given character is the first character of a tag reference.

    - #### isCTag

          public static boolean isCTag(char value)

      Indicates if a given character is the first special character of a `CTag` reference.
      Parameters:
        `value` - the character to check.
      Returns:
        true if the given character denotes a `CTag` reference.

    - #### hasContentAfter

          public static boolean hasContentAfter(java.lang.String codedText,
                                int position)

      Indicates if a given coded text has any non-marker tags at or after a given position.
      Parameters:
        `codedText` - the coded text to process.
        `position` - the position where to start checking.
      Returns:
        true if there is anything other than marker tags at or after the position, false if text or inline code tags are found.

    - #### getCodedTextPosition

          public static int getCodedTextPosition(java.lang.CharSequence codedText,
                                 int plainTextPosition,
                                 boolean leftOfTag)

      Gets the coded text position in a given coded text string for a given plain text position. The conversion is done as with the current state of the coded text, for example if the fragment has folded non-translatable text it is represented by a tag reference.
      Parameters:
        `codedText` - the coded text character sequence to use as the base for the conversion.
        `plainTextPosition` - the plain text position to convert.
        `leftOfTag` - true to return the left side position of the tag reference when the plain text position is on a tag reference (e.g. for end of range stopping before the reference). Use false to get the right side.
      Returns:
        the coded text position.
      See Also:
        `getPlainText()`, `getCodedTextPosition(int, boolean)`

    - #### toString

          public java.lang.String toString()

      Returns a string representation of the fragment: the text in coded text format.

      the coded text format is made of normal content and a pair of special characters for each tag in the content. The method has the same effect as calling `getCodedText()`.

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getPlainText

          public java.lang.String getPlainText()

      Gets a plain text version (all tag references stripped out) of the content of this fragment.
      Returns:
        the plain text version of this fragment.

    - #### getCodedText

          public java.lang.String getCodedText()

      Gets the content of this fragment in coded text format.

      the coded text format is made of normal content and a pair of special characters for each tag in the content.

      Returns:
        the coded text content for this fragment.

    - #### setCodedText

          public void setCodedText(java.lang.String codedText)

      Sets the coded text content for this fragment. IMPORTANT: the corresponding tags should be set too, at the store level, for all the fragments. See `getCodedText()` for more information on coded text.
      Parameters:
        `codedText` - the new coded text content to set.

    - #### getTags

          public Tags getTags()

      Gets the source or target tags for the unit where this segment is located.
      Returns:
        the source or target tags for the unit where this segment is located. Can be empty but never null.

    - #### getOwnTags

          public java.util.List<Tag> getOwnTags()

      Creates a list of all the source or target tags in this fragment. The list is a snapshot of the tags at the time the method is called, not a live list.
      Returns:
        a list of the tags for this fragment.

    - #### getOwnTagsStatus

          public java.util.Map<Tag,java.lang.Integer> getOwnTagsStatus()

      Creates a map of the opening and closing tags in this fragment and their corresponding status as tag: (0=isolated, 1=not-well-formed or 2=well-formed). Standalone codes are not in the resulting list.

      isolated means to counterpart tag within the parent unit.

      (not-)well-formed means (not-)well-formed within this fragment.

      Returns:
        a map of the opening and closing tags and their status, the map may be empty but never null.

    - #### getTag

          public Tag getTag(java.lang.CharSequence ctext,
                   int pos)

      Gets the `MTag` or `CTag` for a given reference in a coded text.
      Parameters:
        `ctext` - the coded text (e.g. String or StringBuilder object).
        `pos` - the position of the first character of the reference.
      Returns:
        the tag for the given tag reference, or null if there is no corresponding tag.

    - #### getCTag

          public CTag getCTag(java.lang.CharSequence ctext,
                     int pos)

      Gets the `CTag` for a given reference in a coded text.
      Parameters:
        `ctext` - the coded text (e.g. String or StringBuilder object).
        `pos` - the position of the first character of the reference.
      Returns:
        the tag for the given tag reference, or null if there is no corresponding tag.

    - #### getMTag

          public MTag getMTag(java.lang.CharSequence ctext,
                     int pos)

      Gets the `MTag` for a given reference in a coded text.
      Parameters:
        `ctext` - the coded text (e.g. String or StringBuilder object).
        `pos` - the position of the first character of the reference.
      Returns:
        the tag for the given tag reference, or null if there is no corresponding tag.

    - #### getStore

          public Store getStore()

      Gets the store associated with this fragment.
      Returns:
        the store associated with this fragment (never null).

    - #### getTag

          public Tag getTag(int key)

      Gets the tag for a given key.
      Parameters:
        `key` - the key of the tag to retrieve.
      Returns:
        the tag for the given key, or null if there is no corresponding tag.

    - #### toXLIFF

          public java.lang.String toXLIFF(java.util.Stack<NSContext> nsStack,
                                 java.util.Stack<InheritedData> context,
                                 boolean withOriginalData)

      Creates an XLIFF output for this fragment.
      Parameters:
        `nsStack` - the namespace context to use (can be null for out-of-context output).
        `context` - context of the inherited data (can be null for out-of-context output).
        `withOriginalData` - true to output references to original data, false otherwise.
      Returns:
        the XLIFF string.

    - #### getClosingTag

          public Tag getClosingTag(Tag tag)

      Gets the closing tag corresponding to a given opening tag within a unit.
      Parameters:
        `tag` - the opening tag.
      Returns:
        the closing tag, or null if none is found.

    - #### getOpeningTag

          public Tag getOpeningTag(Tag tag)

      Gets the opening tag corresponding to a given closing tag within a unit.
      Parameters:
        `tag` - the closing tag.
      Returns:
        the opening tag, or null if none is found.

    - #### getClosingPosition

          public int getClosingPosition(Tag opening)

      Gets the closing position of a span of content in this fragment for a given opening tag. If the corresponding closing tag is not present or outside of this fragment, this method returns -1.
      Parameters:
        `opening` - the opening tag.
      Returns:
        the position of the end of the span (the index of the first character of the key of the closing tag), or -1 if not found.

    - #### unitHasOpening

          public boolean unitHasOpening(CTag ctag)

      Tests if the unit to which this fragment belongs has an opening code for a given closing code.
      Parameters:
        `ctag` - the closing code to test.
      Returns:
        true if there is a corresponding opening code. False otherwise.

    - #### printCommonAttributes

          public static void printCommonAttributes(CTag code,
                                   Tags tags,
                                   java.lang.StringBuilder tmp,
                                   CTag closing,
                                   boolean outputDataRefEnd)

      Output the common attributes for a given CTag object.
      Parameters:
        `code` - the code to output.
        `tags` - the tags collection to which the code belongs (can be null if closing is null).
        `tmp` - the buffer where to output.
        `closing` - the closing code if this is a paired-code (can be null).
        `outputDataRefEnd` - true to output the dataRefEnd attribute if needed.

    - #### printExtAttributes

          public static void printExtAttributes(Tag tag,
                                java.lang.StringBuilder output,
                                java.util.Stack<NSContext> nsStack)

    - #### toXLIFF

          public java.lang.String toXLIFF()

      Creates an XLIFF output of this fragment, without handling the inline codes original data, without namespace content and without inherited data context.
      Returns:
        the XLIFF string.

    - #### isEmpty

          public boolean isEmpty()

      Indicates if this fragment is empty.
      Returns:
        true if this fragment is empty, false if it has text or inline code.

    - #### isTarget

          public boolean isTarget()

      Indicates if this fragment is a target content.
      Returns:
        true if this is a target content, false if it is a source content.

    - #### hasTag

          public boolean hasTag()

      Indicates if this fragment contains at least one tag.
      Returns:
        true if this fragment contains at least one tag, false otherwise.

    - #### getWellFormedClosing

          public Tag getWellFormedClosing(Tag opening,
                                 int from)

      Gets the well-formed closing tag for a given opening one, starting at a given character position.

      This will not find closing tag that are not well-formed (e.g. overlapping)

      Parameters:
        `opening` - the opening tag.
        `from` - the first character position to look at.
      Returns:
        the corresponding closing tag, or null if none is found.

    - #### append

          public Fragment append(char ch)

      Appends a character at the end of this fragment.
      Specified by:
        `append` in interface `java.lang.Appendable`
      Parameters:
        `ch` - the character to append.
      Returns:
        the fragment itself.

    - #### append

          public Fragment append(java.lang.CharSequence plainText)

      Appends a plain text string to this fragment. If the parameter is null, a string "null" is appended.
      Specified by:
        `append` in interface `java.lang.Appendable`
      Parameters:
        `plainText` - the string to append.
      Returns:
        the fragment itself.

    - #### append

          public Fragment append(java.lang.CharSequence plainText,
                        int start,
                        int end)

      Appends a sub-sequence of a given plain text string to this fragment. If the parameter is null, a string "null" is appended.
      Specified by:
        `append` in interface `java.lang.Appendable`
      Parameters:
        `plainText` - the source for the sub-sequence to append.
        `start` - the index of the first character in the subsequence.
        `end` - the index of the character following the last character in the subsequence.
      Returns:
        the fragment itself.

    - #### append

          public Tag append(Tag tag)

      Appends a tag to this fragment.
      Parameters:
        `tag` - the code or marker tag to append.
      Returns:
        the added tag (same as the parameter).

    - #### openMarkerSpan

          public MTag openMarkerSpan(java.lang.String id,
                            java.lang.String type)

      Appends a tag opening a new marker span.
      Parameters:
        `id` - the ID of the new marker (or null to use an auto-generated ID).
        `type` - the type of the new marker (or null for the default).
      Returns:
        the new marker's opening tag.
      See Also:
        `closeMarkerSpan(String)`

    - #### closeMarkerSpan

          public MTag closeMarkerSpan(java.lang.String id)

      Appends a tag to close the marker of a given id.
      Parameters:
        `id` - the id of the marker.
      Returns:
        the closing tag created.
      Throws:
        `XLIFFException` - if the opening tag for this marker cannot be found.
      See Also:
        `openMarkerSpan(String, String)`

    - #### append

          public CTag append(TagType tagType,
                    java.lang.String id,
                    java.lang.String data,
                    boolean canOverlap)

      Appends a code tag.
      Parameters:
        `tagType` - the `TagType` of the code tag (cannot be null).
        `id` - the id of the tag.
        `data` - the original data for this tag (can be null)
        `canOverlap` - true if this code can be overlapped, false otherwise. This parameter is ignored if the code is created from its counterpart.
      Returns:
        the added code tag.
      See Also:
        `appendCode(String, String)`

    - #### append

          public void append(Fragment fragment)

      Appends a fragment to this fragment.
      Parameters:
        `fragment` - the fragment to append (cannot be itself or null).

    - #### annotate

          public int annotate(int start,
                     int end,
                     java.lang.String type,
                     java.lang.String value,
                     java.lang.String ref)

      Annotates a span of content in this fragment.
      Parameters:
        `start` - the start position (in the coded text)
        `end` - the position just after the last character of the span (in the coded text). You can use -1 to indicate the end of the fragment.
        `type` - the type of the annotation. If the type is `term` or `its:term-no` the marker created is an instance of `TermTag` rather than `MTag`.
        `value` - the value of the `value` attribute (can be null).
        `ref` - the value of the `ref` attribute (can be null).
      Returns:
        the number of characters added to the coded text.
      See Also:
        `getOrCreateMarker(int, int, String, String)`

    - #### annotate

          public int annotate(int start,
                     int end,
                     MTag opening)

      Annotates a span of content in this fragment.
      Parameters:
        `start` - the start position (in the coded text)
        `end` - the position just after the last character of the span (in the coded text). You can use -1 to indicate the end of the fragment.
        `opening` - the start tag of the marker. The end tag will be generated from this tag.
      Returns:
        the number of characters added to the coded text.
      See Also:
        `getOrCreateMarker(int, int, String, String)`

    - #### getOrCreateMarker

          public MTag getOrCreateMarker(int start,
                               int end,
                               java.lang.String matchingType,
                               java.lang.String typeForNew)

      Get or create an annotation marker for a given span of content.
      Parameters:
        `start` - the start position (in the coded text)
        `end` - the position just after the last character of the span (in the coded text). You can use -1 to indicate the end of the fragment.
        `matchingType` - the type of marker that can be reused. Use null to reuse any marker.
        `typeForNew` - the type of the marker to create of none reusable is found (must not be null).
      Returns:
        the opening tag of the marker found or created.

    - #### remove

          public void remove(Tag tag)

      Removes a tag from this fragment (including if the tag is in a protected content). The tag is removed both from the coded text and from the list of tags.
      Parameters:
        `tag` - the tag to remove.

    - #### delete

          public Fragment delete(int start,
                        int end)

      Deletes a section of this fragment (including any protected content within the section).
      Parameters:
        `start` - the start index (inclusive)
        `end` - the end index (exclusive)
      Returns:
        the fragment itself.

    - #### iterator

          public java.util.Iterator<java.lang.Object> iterator()

      Creates an iterator for all the different objects composing this fragment. The objects returned can be of type `String`, `CTag`, `MTag` and `PCont`. To iterate through only one type of object use `getIterable(Class)`.
      Specified by:
        `iterator` in interface `java.lang.Iterable<java.lang.Object>`
      Returns:
        a new iterator for all the objects composing this fragment.
      See Also:
        `getIterable(Class)`

    - #### getIterable

          public <T> java.lang.Iterable<T> getIterable(java.lang.Class<T> type)

      Creates a new instance of an iterable interface for a given class of objects. Inline objects in hidden content are not returned by the iterator.
      Parameters:
        `type` - the class of the object to iterate through. this can be `Object`, `String`, `Tag`, `CTag`, `MTag` or `PCont`.
      Returns:
        the new iterable interface.
      See Also:
        `iterator()`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object object)

      Indicates if this fragment equals another object. Use `==` to see if two fragments are the same object.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `object` - the object to compare this fragment with.
      Returns:
        true if the object and this fragment are equals.

    - #### getDir

          public Directionality getDir(boolean resolved)

    - #### setDir

          public void setDir(Directionality dir)

      Sets the directionality for this fragment.
      Parameters:
        `dir` -

    - #### showProtectedContent

          public void showProtectedContent()

      Expands all `PCont` references in this fragment into normal content. To hide the protected content use `Unit.hideProtectedContent()`.

    - #### checkPosition

          public void checkPosition(int position)

      Verifies if a given position in the coded text is on the second special character of a tag reference.
      Parameters:
        `position` - the position to check.
      Throws:
        `InvalidPositionException` - when position points inside a tag reference.

    - #### clear

          public void clear()

      Clears the fragment: removes all tags and text.

    - #### getCodedTextPosition

          public int getCodedTextPosition(int plainTextPosition,
                                 boolean leftOfTag)

      Helper methods calling `getCodedTextPosition(CharSequence, int, boolean)` with the coded text of this fragment as the first parameter.
      Parameters:
        `plainTextPosition` - the plain text position to convert.
        `leftOfTag` - true to return the left side position of the tag reference when the plain text position is on a tag reference (e.g. for end of range stopping before the reference). Use false to get the right side.
      Returns:
        the coded text position.
      See Also:
        `getPlainText()`, `getCodedTextPosition(CharSequence, int, boolean)`

    - #### insert

          public Fragment insert(java.lang.CharSequence plainText,
                        int offset)

      Inserts a plain text at a given position.
      Parameters:
        `plainText` - the plain text to insert.
        `offset` - the position where to insert.
      Returns:
        the fragment itself.
      Throws:
        `InvalidPositionException` - if the offset is on a tag reference.
        `java.lang.IndexOutOfBoundsException` - if the offset is invalid.

    - #### insert

          public CTag insert(TagType tagType,
                    java.lang.String type,
                    java.lang.String id,
                    java.lang.String data,
                    int offset,
                    boolean connect,
                    boolean allowOrphan)

      Inserts a code at a given position (including the end) of this fragment.
      Parameters:
        `tagType` - the type of tag of the code.
        `type` - the type of the code (can be null).
        `id` - the id of the code (if null an new ID is created automatically) This parameter is ignored when the new tag is created by connecting it with another one.
        `data` - the original data for the code (can be null).
        `offset` - the position where to insert the code. Use -1 to append. Other negative values or values greater then the length of the coded text also cause the code to be appended at the end of the fragment.
        `connect` - true to connect a new opening code to its closing counterpart, or to connect a new closing code to its opening counterpart (the counterpart may be in a different fragment). Use false to create new opening or closing codes. This option is ignored used if the code is standalone.
        `allowOrphan` - true to allow the connect option to fail, that is: to not found the counterpart of the new code. this option is ignore if connect is false or if the new code is a standalone code.
      Returns:
        the new tag created.

    - #### appendCode

          public CTag appendCode(java.lang.String id,
                        java.lang.String data)

      Appends a standalone code to this fragment.
      Parameters:
        `id` - the id of the code tag (cannot be null).
        `data` - the original data for this tag (can be null).
      Returns:
        the new tag.

    - #### openCodeSpan

          public CTag openCodeSpan(java.lang.String id,
                          java.lang.String data)

      Creates at the end of this fragment an opening tag for a new code.
      Parameters:
        `id` - the id to use for this code (use null to use an automatic ID).
        `data` - the original data for the code, e.g. `<B>` (can be null).
      Returns:
        the new tag.

    - #### closeCodeSpan

          public CTag closeCodeSpan(java.lang.String id,
                           java.lang.String data)

      Creates at the end of this fragment a closing tag for an existing code.
      Parameters:
        `id` - the id of the code to close (must not be null).
        `data` - the original data for the code, e.g. `<B>` (can be null).
      Returns:
        the new tag.