net.sf.okapi.common.resource

## Class Segments

- java.lang.Object
- - net.sf.okapi.common.resource.Segments

- All Implemented Interfaces:
    java.lang.Iterable<Segment>, ISegments

      public class Segments
      extends java.lang.Object
      implements ISegments

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Segments(TextContainer parent)` Creates an uninitialised Segments object.

  - ### 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` | `setParts(java.util.List<TextPart> parts)` Sets the list of TextPart objects in which the segments for this Segments object are located.
    `void` | `swap(int segIndex1, int segIndex2)` Swaps two segments in this container.
    `void` | `validateSegmentId(Segment seg)` Checks if the id of a given segment is empty, null or a duplicate.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Segments

          public Segments(TextContainer parent)

      Creates an uninitialised Segments object.

      IMPORTANT: setParts() must be called with a non-null argument before calling any other methods.

  - ### Method Detail

    - #### setParts

          public void setParts(java.util.List<TextPart> parts)

      Sets the list of TextPart objects in which the segments for this Segments object are located. Parts must be set after construction before any other methods are invoked.
      Parameters:
        `parts` - the list of `TextPart`s where the segments are stored.

    - #### iterator

          public java.util.Iterator<Segment> iterator()

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

    - #### asList

          public java.util.List<Segment> asList()

      Description copied from interface: `ISegments`
      Get all segments. Excludes inter-segment parts.
      Specified by:
        `asList` in interface `ISegments`
      Returns:
        List of segments.

    - #### swap

          public void swap(int segIndex1,
                  int segIndex2)

      Description copied from interface: `ISegments`
      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.

      Specified by:
        `swap` in interface `ISegments`
      Parameters:
        `segIndex1` - the segment index of the first segment to swap.
        `segIndex2` - the segment index of the second segment to swap.

    - #### append

          public void append(Segment segment,
                    boolean collapseIfPreviousEmpty)

      Description copied from interface: `ISegments`
      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.
      Specified by:
        `append` in interface `ISegments`
      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

          public void append(Segment segment)

      Description copied from interface: `ISegments`
      Appends a segment at the end of this container.

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

      Specified by:
        `append` in interface `ISegments`
      Parameters:
        `segment` - the segment to append.

    - #### append

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

      Description copied from interface: `ISegments`
      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.

      Specified by:
        `append` in interface `ISegments`
      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

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

      Description copied from interface: `ISegments`
      Appends a segment at the end of this container, with an optional non-segment part just before.

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

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

    - #### append

          public void append(TextFragment fragment,
                    boolean collapseIfPreviousEmpty)

      Description copied from interface: `ISegments`
      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.

      Specified by:
        `append` in interface `ISegments`
      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

          public void append(TextFragment fragment)

      Description copied from interface: `ISegments`
      Appends a TextFragment as a segment at the end of this container.

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

      Specified by:
        `append` in interface `ISegments`
      Parameters:
        `fragment` - the fragment to append as a segment.

    - #### set

          public void set(int index,
                 Segment seg)

      Description copied from interface: `ISegments`
      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.

      Specified by:
        `set` in interface `ISegments`
      Parameters:
        `index` - the segment index position.
        `seg` - the new segment.

    - #### insert

          public void insert(int index,
                    Segment seg)

      Description copied from interface: `ISegments`
      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.

      Specified by:
        `insert` in interface `ISegments`
      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 `ISegments.append(Segment, boolean)` with collapseIfPreviousEmpty set to true.
        `seg` - the segment to insert.

    - #### create

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

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

    - #### create

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

      Description copied from interface: `ISegments`
      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.
      Specified by:
        `create` in interface `ISegments`
      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

          public int create(int start,
                   int end)

      Description copied from interface: `ISegments`
      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".
      Specified by:
        `create` in interface `ISegments`
      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

          public int count()

      Description copied from interface: `ISegments`
      Gets the number of segments in this container. This method always returns at least 1.
      Specified by:
        `count` in interface `ISegments`
      Returns:
        the number of segments in the container.
      See Also:
        `TextContainer.count()`

    - #### getFirstContent

          public TextFragment getFirstContent()

      Description copied from interface: `ISegments`
      Gets the content of the first segment of this container.
      Specified by:
        `getFirstContent` in interface `ISegments`
      Returns:
        the content of the first segment of this container.
      See Also:
        `TextContainer.getFirstContent()`, `ISegments.getLastContent()`, `TextContainer.getLastContent()`

    - #### getLastContent

          public TextFragment getLastContent()

      Description copied from interface: `ISegments`
      Gets the content of last segment of this container.
      Specified by:
        `getLastContent` in interface `ISegments`
      Returns:
        the content of the last segment of this container.
      See Also:
        `ISegments.getLastContent()`, `TextContainer.getFirstContent()`, `TextContainer.getFirstContent()`

    - #### getLast

          public Segment getLast()

      Description copied from interface: `ISegments`
      Gets the last `Segment` of the container.
      Specified by:
        `getLast` in interface `ISegments`
      Returns:
        the last Segment or null if no segment is found.

    - #### get

          public Segment get(java.lang.String id)

      Description copied from interface: `ISegments`
      Gets the segment for a given identifier.
      Specified by:
        `get` in interface `ISegments`
      Parameters:
        `id` - the identifier of the segment to retrieve.
      Returns:
        the segment for the given identifier or null if no segment is found.

    - #### get

          public Segment get(int index)

      Description copied from interface: `ISegments`
      Gets the segment for a given segment index.
      Specified by:
        `get` in interface `ISegments`
      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 `ISegments.get(String)` to retrieve by segment identifier.

      See Also:
        `ISegments.get(String)`, `#see {@link #iterator()}`

    - #### joinAll

          public void joinAll()

      Description copied from interface: `ISegments`
      Merges back together all segments of this TextContainer object, and clear the list of segments. The content becomes a single segment content.
      Specified by:
        `joinAll` in interface `ISegments`
      See Also:
        `ISegments.joinAll(List)`

    - #### joinAll

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

      Description copied from interface: `ISegments`
      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.
      Specified by:
        `joinAll` in interface `ISegments`
      Parameters:
        `ranges` - a list of Ranges where to save the segments ranges, use null to not save the ranges.

    - #### getRanges

          public java.util.List<Range> getRanges()

      Description copied from interface: `ISegments`
      Gets the list of the boundaries for the current segments in this container.
      Specified by:
        `getRanges` in interface `ISegments`
      Returns:
        the list of the current segment boundaries.

    - #### joinWithNext

          public int joinWithNext(int segmentIndex)

      Description copied from interface: `ISegments`
      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.

      Specified by:
        `joinWithNext` in interface `ISegments`
      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

          public int getPartIndex(int segIndex)

      Description copied from interface: `ISegments`
      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.

      Specified by:
        `getPartIndex` in interface `ISegments`
      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

          public int getIndex(java.lang.String segId)

      Description copied from interface: `ISegments`
      Gets the segment index for a given segment id.
      Specified by:
        `getIndex` in interface `ISegments`
      Parameters:
        `segId` - the id to search for.
      Returns:
        the segment index found or -1 if not found.

    - #### getAlignmentStatus

          public AlignmentStatus getAlignmentStatus()

      Description copied from interface: `ISegments`
      Returns the `AlignmentStatus` for these segments.
      Specified by:
        `getAlignmentStatus` in interface `ISegments`
      Returns:
        the `AlignmentStatus`

    - #### setAlignmentStatus

          public void setAlignmentStatus(AlignmentStatus alignmentStatus)

      Description copied from interface: `ISegments`
      Sets the `AlignmentStatus` for these segments.
      Specified by:
        `setAlignmentStatus` in interface `ISegments`

    - #### validateSegmentId

          public void validateSegmentId(Segment seg)

      Checks if the id of a given segment is empty, null or a duplicate. If it is, the id is automatically set to a new value auto-generated.
      Parameters:
        `seg` - the segment to verify and possibly modify.