net.sf.okapi.common.resource

## Interface ISegments

- All Superinterfaces:
    java.lang.Iterable<Segment>
  All Known Implementing Classes:
    Segments

      public interface ISegments
      extends java.lang.Iterable<Segment>

  Provides the methods to access all the segments of a `TextContainer`. To create an instance of this interface, use the method `TextContainer.getSegments()`.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `append(Segment segment)` Appends a segment at the end of this container.
    `void` | `append(Segment segment, boolean collapseIfPreviousEmpty)` Appends a segment at the end of this container.
    `void` | `append(Segment segment, java.lang.String textBefore)` Appends a segment at the end of this container, with an optional non-segment part just before.
    `void` | `append(Segment segment, java.lang.String textBefore, boolean collapseIfPreviousEmpty)` Appends a segment at the end of this container, with an optional non-segment part just before.
    `void` | `append(TextFragment fragment)` Appends a TextFragment as a segment at the end of this container.
    `void` | `append(TextFragment fragment, boolean collapseIfPreviousEmpty)` Appends a TextFragment as a segment at the end of this container.
    `java.util.List<Segment>` | `asList()` Get all segments.
    `int` | `count()` Gets the number of segments in this container.
    `int` | `create(int start, int end)` Creates a segment in this container.
    `int` | `create(java.util.List<Range> ranges)` Helper method to create segments without empty segments.
    `int` | `create(java.util.List<Range> ranges, boolean allowEmptySegments)` Creates a set of segments in this container.
    `Segment` | `get(int index)` Gets the segment for a given segment index.
    `Segment` | `get(java.lang.String id)` Gets the segment for a given identifier.
    `AlignmentStatus` | `getAlignmentStatus()` Returns the `AlignmentStatus` for these segments.
    `TextFragment` | `getFirstContent()` Gets the content of the first segment of this container.
    `int` | `getIndex(java.lang.String segId)` Gets the segment index for a given segment id.
    `Segment` | `getLast()` Gets the last `Segment` of the container.
    `TextFragment` | `getLastContent()` Gets the content of last segment of this container.
    `int` | `getPartIndex(int segIndex)` Gets the part index for a given segment index.
    `java.util.List<Range>` | `getRanges()` Gets the list of the boundaries for the current segments in this container.
    `void` | `insert(int index, Segment seg)` Inserts a given segment at the specified position.
    `java.util.Iterator<Segment>` | `iterator()` Gets an iterator for the segments of this container.
    `void` | `joinAll()` Merges back together all segments of this TextContainer object, and clear the list of segments.
    `void` | `joinAll(java.util.List<Range> ranges)` Merges back together all segments of this TextContainer object, and clear the list of segments.
    `int` | `joinWithNext(int segmentIndex)` Joins to a given segment all the parts between that segment and the next, as well as the next segment.
    `void` | `set(int index, Segment seg)` Sets a new segment at a given segment index.
    `void` | `setAlignmentStatus(AlignmentStatus alignmentStatus)` Sets the `AlignmentStatus` for these segments.
    `void` | `swap(int segIndex1, int segIndex2)` Swaps two segments in this container.

- - ### Method Detail

    - #### iterator

          java.util.Iterator<Segment> iterator()

      Gets an iterator for the segments of this container. This iterator does not iterate through non-segment parts of the content. Use `iterator()` for accessing both segments and non-segments parts.
      Specified by:
        `iterator` in interface `java.lang.Iterable<Segment>`
      Returns:
        an iterator for the segments of this container.

    - #### asList

          java.util.List<Segment> asList()

      Get all segments. Excludes inter-segment parts.
      Returns:
        List of segments.

    - #### swap

          void swap(int segIndex1,
                  int segIndex2)

      Swaps two segments in this container.

      For example, if you have a container "[segment1] [segment2]" and call `swap(0,1)` the resulting container becomes: "[segment2] [segment1]".

      Note that the segments identifiers stay with their segment.

      Parameters:
        `segIndex1` - the segment index of the first segment to swap.
        `segIndex2` - the segment index of the second segment to swap.

    - #### append

          void append(Segment segment,
                    boolean collapseIfPreviousEmpty)

      Appends a segment at the end of this container. If there is no content after the last segment, and the last segment is empty, the new segment replaces the last one (including its id, and the new id is validated). Otherwise the new segment is appended to the content as a new segment part and its id is validated.
      Parameters:
        `segment` - the segment to append.
        `collapseIfPreviousEmpty` - true to collapse the new segment if the last part of the container is an empty segment.

    - #### append

          void append(Segment segment,
                    java.lang.String textBefore,
                    boolean collapseIfPreviousEmpty)

      Appends a segment at the end of this container, with an optional non-segment part just before.

      If collapseIfPreviousEmpty is true and collapseIfPreviousEmpty is empty or null, and if the last part of the container is an empty segment, this new segment replaces the last one (including its id, and the new id is validated). Otherwise the new segment is appended to the content as a new segment part and its id is validated.

      Parameters:
        `segment` - the segment to append.
        `textBefore` - the text of the non-segment part before the segment (can be null).
        `collapseIfPreviousEmpty` - true to collapse the new segment if the last part of the container is an empty segment (that is if textBefore is also empty or null).

    - #### append

          void append(TextFragment fragment,
                    boolean collapseIfPreviousEmpty)

      Appends a TextFragment as a segment at the end of this container.

      If collapseIfPreviousEmpty is true and if the last part of the container is an empty segment, this new segment replaces the last one. Otherwise the new segment is appended to the content as a new segment part. In all case the id of the new segment is set automatically.

      Parameters:
        `fragment` - the fragment to append as a segment.
        `collapseIfPreviousEmpty` - true to collapse the new segment if the last part of the container is an empty segment.

    - #### append

          void append(Segment segment)

      Appends a segment at the end of this container.

      This call is the same as calling `append(Segment, boolean)` with collapseIfPreviousEmpty set to true.

      Parameters:
        `segment` - the segment to append.

    - #### append

          void append(Segment segment,
                    java.lang.String textBefore)

      Appends a segment at the end of this container, with an optional non-segment part just before.

      This call is the same as calling `append(Segment, String, boolean)` with collapseIfPreviousEmpty set to true.

      Parameters:
        `segment` - the segment to append.
        `textBefore` - the text of the non-segment part before the segment (can be null).

    - #### append

          void append(TextFragment fragment)

      Appends a TextFragment as a segment at the end of this container.

      This call is the same as calling `append(TextFragment, boolean)` with collapseIfPreviousEmpty set to true.

      Parameters:
        `fragment` - the fragment to append as a segment.

    - #### set

          void set(int index,
                 Segment seg)

      Sets a new segment at a given segment index.

      If the new segment's id exists already in the container, it is replaced by a valid id.

      Parameters:
        `index` - the segment index position.
        `seg` - the new segment.

    - #### insert

          void insert(int index,
                    Segment seg)

      Inserts a given segment at the specified position.

      If the segment to insert has no id or an id that is already used in the text container, the id is automatically changed to a new valid id.

      Parameters:
        `index` - the segment index position. If the given position is the same as the number of segments in the container, the call is the same as `append(Segment, boolean)` with collapseIfPreviousEmpty set to true.
        `seg` - the segment to insert.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of bounds.

    - #### create

          int create(java.util.List<Range> ranges,
                   boolean allowEmptySegments)

      Creates a set of segments in this container. Use `TextContainer.getCodedText()` to get the coded text to use as the base for the segment boundaries. If the content is already segmented, it is automatically un-segmented before the new segmentation is applied.
      Parameters:
        `ranges` - the ranges of the segments to create. The ranges must be ordered from the lesser position to the higher one (i.e. from left to right). If this parameter is empty or null, no modification is done.
        `allowEmptySegments` - true to allow empty segments to be created, false to skip them.
      Returns:
        the number of parts (segments and non-segments) created during the operation.

    - #### create

          int create(java.util.List<Range> ranges)

      Helper method to create segments without empty segments. This is the same as calling `create(List, boolean)` with false.
      Parameters:
        `ranges` - the ranges of the segments to create.
      Returns:
        the number of parts (segments and non-segments) created during the operation.
      See Also:
        `create(List, boolean)`

    - #### create

          int create(int start,
                   int end)

      Creates a segment in this container. Use `TextContainer.getCodedText()` to get the coded text to use as the base for the segment boundaries. If the content is already segmented, it is automatically un-segmented before the new segmentation is applied. If start and end position are the same, no segment is created for those boundaries.

      For example:

      - calling createSegment(2,3) on "a b c" will result in: "a [b] c".
      - calling createSegment(2,3) on "[a b] [c]" will result in: "a [b] c".
      Parameters:
        `start` - the start of the segment.
        `end` - the position just after the last character of the the segment.
      Returns:
        the number of parts (segments and non-segments) created during the operation.

    - #### count

          int count()

      Gets the number of segments in this container. This method always returns at least 1.
      Returns:
        the number of segments in the container.
      See Also:
        `TextContainer.count()`

    - #### getFirstContent

          TextFragment getFirstContent()

      Gets the content of the first segment of this container.
      Returns:
        the content of the first segment of this container.
      See Also:
        `TextContainer.getFirstContent()`, `getLastContent()`, `TextContainer.getLastContent()`

    - #### getLastContent

          TextFragment getLastContent()

      Gets the content of last segment of this container.
      Returns:
        the content of the last segment of this container.
      See Also:
        `getLastContent()`, `TextContainer.getFirstContent()`, `TextContainer.getFirstContent()`

    - #### getLast

          Segment getLast()

      Gets the last `Segment` of the container.
      Returns:
        the last Segment or null if no segment is found.

    - #### get

          Segment get(java.lang.String id)

      Gets the segment for a given identifier.
      Parameters:
        `id` - the identifier of the segment to retrieve.
      Returns:
        the segment for the given identifier or null if no segment is found.

    - #### get

          Segment get(int index)

      Gets the segment for a given segment index.
      Parameters:
        `index` - the index of the segment to retrieve. The first segment has the index 0, the second has the index 1, etc. Note that the index value used here is not necessarily the same index as for a part. That is: `getSegment(0)` returns the same segment as `getPart(0)` only if the first part of the container is a segment.
      Returns:
        the segment for the given index.

        Use `get(String)` to retrieve by segment identifier.

      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of bounds.
      See Also:
        `get(String)`, `#see {@link #iterator()}`

    - #### joinAll

          void joinAll()

      Merges back together all segments of this TextContainer object, and clear the list of segments. The content becomes a single segment content.
      See Also:
        `joinAll(List)`

    - #### joinAll

          void joinAll(java.util.List<Range> ranges)

      Merges back together all segments of this TextContainer object, and clear the list of segments. If required, the existing segment boundaries are saved in a given list of ranges. The content becomes a single segment content.
      Parameters:
        `ranges` - a list of Ranges where to save the segments ranges, use null to not save the ranges.

    - #### getRanges

          java.util.List<Range> getRanges()

      Gets the list of the boundaries for the current segments in this container.
      Returns:
        the list of the current segment boundaries.

    - #### joinWithNext

          int joinWithNext(int segmentIndex)

      Joins to a given segment all the parts between that segment and the next, as well as the next segment.

      For example for the content: " [seg1] [seg2] ", the call joinWithNext(0) will give the result: " [seg1 seg2] ". And the call joinWithNext(1) will give the result: " [seg1] [seg2] " (no change because there is no segment after the segment 1.

      Parameters:
        `segmentIndex` - index of the segment (not the part) where to append the next segment.
      Returns:
        the number of parts joined to the given segment (and removed from the list of parts).

    - #### getPartIndex

          int getPartIndex(int segIndex)

      Gets the part index for a given segment index.

      For example in the container "[segment1] [segment2] [segment3]" the segment index for "[segment2]" is 1 and its part index is 2 because there is one non-segment part before.

      Parameters:
        `segIndex` - the segment index to convert to part index.
      Returns:
        the index of the part for the given segment index, or -1 if the segment was not found.

    - #### getIndex

          int getIndex(java.lang.String segId)

      Gets the segment index for a given segment id.
      Parameters:
        `segId` - the id to search for.
      Returns:
        the segment index found or -1 if not found.

    - #### getAlignmentStatus

          AlignmentStatus getAlignmentStatus()

      Returns the `AlignmentStatus` for these segments.
      Returns:
        the `AlignmentStatus`

    - #### setAlignmentStatus

          void setAlignmentStatus(AlignmentStatus alignmentStatus)

      Sets the `AlignmentStatus` for these segments.
      Parameters:
        `alignmentStatus` - the new `AlignmentStatus` value.