net.sf.okapi.common.resource

## Interface IAlignedSegments

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

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

  Provides the methods to access all the source and target `Segment`s of a `ITextUnit`.

  Several methods of this interface use flags to determine which sources and targets to modify during segment operations. `IAlignedSegments.VariantOptions` (in conjunction with a `LocaleId`) and `IAlignedSegments.CopyOptions` will determine which sources and targets are modified and whether new Segments will contain content. These flags are passed in an `EnumSet`. IAlignedSegments.MODIFY_AS_VARIANT is recommended in order to maintain alignment between each target and its associated source.

  To create an instance of this interface, use the method `ITextUnit.getAlignedSegments()`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `IAlignedSegments.CopyOptions` Flag to indicate which segments should contain content when new or copied segments are created.
    `static class` | `IAlignedSegments.VariantOptions` Flag used to determine the containers that will have segments modified by an operation.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.util.EnumSet<IAlignedSegments.CopyOptions>` | `COPY_TO_ALL` Copy to all `TextContainer`s in this `ITextUnit`.
    `static java.util.EnumSet<IAlignedSegments.CopyOptions>` | `COPY_TO_NONE` No new segments should contain any content
    `static java.util.EnumSet<IAlignedSegments.CopyOptions>` | `COPY_TO_SOURCE_AND_TARGET` Source and target for the given locale should contain content.
    `static java.util.EnumSet<IAlignedSegments.VariantOptions>` | `MODIFY_ALL` Modify all `TextContainer`s in the parent `ITextUnit`.
    `static java.util.EnumSet<IAlignedSegments.VariantOptions>` | `MODIFY_AS_VARIANT` MODIFY_SOURCE + MODIFY_TARGET + CREATE_VARIANT_IF_MULTIPLE_TARGETS
    `static java.util.EnumSet<IAlignedSegments.VariantOptions>` | `MODIFY_ONLY_IF_ALONE` MODIFY_SOURCE + MODIFY_TARGET + CANCEL_IF_MULTIPLE_TARGETS
    `static java.util.EnumSet<IAlignedSegments.VariantOptions>` | `MODIFY_SOURCE_AND_ASSOCIATED_TARGET` MODIFY_SOURCE + MODIFY_TARGET
    `static java.util.EnumSet<IAlignedSegments.VariantOptions>` | `MODIFY_SOURCE_AND_ASSOCIATED_TARGETS` MODIFY_SOURCE + MODIFY_TARGET + MODIFY_TARGETS_WITH_SAME_SOURCE

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `align(java.util.List<AlignedPair> alignedSegmentPairs, LocaleId trgLoc)` Aligns all the segments listed in the aligned pairs for given locale.
    `void` | `align(LocaleId trgLoc)` Aligns all the target segments with the source segments for the given locale.
    `void` | `alignCollapseAll(LocaleId trgLoc, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions)` Aligns all the segments for the specified sources and targets by collapsing all segments into one.
    `void` | `append(Segment srcSeg, Segment trgSeg, LocaleId trgLoc, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions, java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)` Adds given source and target segments to the end of the content.
    `AlignmentStatus` | `getAlignmentStatus()` Gets the status of the alignment for this entire text unit.
    `AlignmentStatus` | `getAlignmentStatus(LocaleId trgLoc)` Gets the status of the alignment the given target locale in this text unit.
    `Segment` | `getCorrespondingSource(Segment trgSeg, LocaleId trgLoc)` Gets the source segment corresponding to a given target segment given the most common use case of one source and one target.
    `Segment` | `getCorrespondingSource(Segment trgSeg, LocaleId trgLoc, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions, java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)` Gets the source segment corresponding to a given target segment.
    `Segment` | `getCorrespondingTarget(Segment seg, LocaleId trgLoc)` Gets the target segment corresponding to a given source segment given the most common use case of one source and one target.
    `Segment` | `getCorrespondingTarget(Segment seg, LocaleId trgLoc, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions, java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)` Gets the target segment corresponding to a given source segment.
    `Segment` | `getSource(int index, LocaleId trgLoc)` Gets the source segment for the given target locale at a given position.
    `void` | `insert(int index, Segment srcSeg, Segment trgSeg, LocaleId trgLoc, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions, java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)` Inserts given source and target segments at the specified position in the list of segments.
    `java.util.Iterator<Segment>` | `iterator()` Gets an iterator for the default source segments of this text unit.
    `java.util.Iterator<Segment>` | `iterator(LocaleId trgLoc)` Gets an iterator for the source of the specified target locale.
    `void` | `joinAll(LocaleId trgLoc, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions)` Joins all segments for the specified sources and targets.
    `void` | `joinWithNext(Segment seg, LocaleId trgLoc, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions)` Joins the segment for a given segment's id to the next segment, including all the parts between the two segments.
    `boolean` | `remove(Segment seg, LocaleId trgLoc, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions)` Removes the given segment and any segments with the same id from the specified sources and targets.
    `void` | `segmentSource(ISegmenter segmenter, LocaleId targetLocale)` Segments the source content used for the given target locale based on the rules provided by a given `ISegmenter`.
    `void` | `segmentTarget(ISegmenter segmenter, LocaleId targetLocale)` Segments the specified target content based on the rules provided by a given `ISegmenter`.
    `void` | `setSegment(int index, Segment seg, LocaleId trgLoc, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions, java.util.EnumSet<IAlignedSegments.VariantOptions> idUpdateOptions)` Replaces a segment at a given position with a clone of the given segment.
    `Segment` | `splitSource(LocaleId trgLoc, Segment srcSeg, int splitPos, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions, java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)` Splits a given source segment into two.
    `Segment` | `splitTarget(LocaleId trgLoc, Segment trgSeg, int splitPos, java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions, java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)` Splits a given target segment into two.

- - ### Field Detail

    - #### MODIFY_ONLY_IF_ALONE

          static final java.util.EnumSet<IAlignedSegments.VariantOptions> MODIFY_ONLY_IF_ALONE

      MODIFY_SOURCE + MODIFY_TARGET + CANCEL_IF_MULTIPLE_TARGETS
      See Also:
        `IAlignedSegments.VariantOptions`

    - #### MODIFY_AS_VARIANT

          static final java.util.EnumSet<IAlignedSegments.VariantOptions> MODIFY_AS_VARIANT

      MODIFY_SOURCE + MODIFY_TARGET + CREATE_VARIANT_IF_MULTIPLE_TARGETS
      See Also:
        `IAlignedSegments.VariantOptions`

    - #### MODIFY_SOURCE_AND_ASSOCIATED_TARGETS

          static final java.util.EnumSet<IAlignedSegments.VariantOptions> MODIFY_SOURCE_AND_ASSOCIATED_TARGETS

      MODIFY_SOURCE + MODIFY_TARGET + MODIFY_TARGETS_WITH_SAME_SOURCE
      See Also:
        `IAlignedSegments.VariantOptions`

    - #### MODIFY_SOURCE_AND_ASSOCIATED_TARGET

          static final java.util.EnumSet<IAlignedSegments.VariantOptions> MODIFY_SOURCE_AND_ASSOCIATED_TARGET

      MODIFY_SOURCE + MODIFY_TARGET
      See Also:
        `IAlignedSegments.VariantOptions`

    - #### MODIFY_ALL

          static final java.util.EnumSet<IAlignedSegments.VariantOptions> MODIFY_ALL

      Modify all `TextContainer`s in the parent `ITextUnit`. MODIFY_SOURCE + MODIFY_TARGET + MODIFY_TARGETS_WITH_SAME_SOURCE + MODIFY_VARIANT_SOURCES + MODIFY_TARGETS_OF_VARIANT_SOURCES
      See Also:
        `IAlignedSegments.VariantOptions`

    - #### COPY_TO_NONE

          static final java.util.EnumSet<IAlignedSegments.CopyOptions> COPY_TO_NONE

      No new segments should contain any content
      See Also:
        `IAlignedSegments.CopyOptions`

    - #### COPY_TO_SOURCE_AND_TARGET

          static final java.util.EnumSet<IAlignedSegments.CopyOptions> COPY_TO_SOURCE_AND_TARGET

      Source and target for the given locale should contain content.

      COPY_TO_SOURCE + COPY_TO_TARGET

      See Also:
        `IAlignedSegments.CopyOptions`

    - #### COPY_TO_ALL

          static final java.util.EnumSet<IAlignedSegments.CopyOptions> COPY_TO_ALL

      Copy to all `TextContainer`s in this `ITextUnit`.
      See Also:
        `IAlignedSegments.CopyOptions`

  - ### Method Detail

    - #### iterator

          java.util.Iterator<Segment> iterator()

      Gets an iterator for the default source segments of this text unit. This iterator does not iterate through non-segment parts of the content.
      Specified by:
        `iterator` in interface `java.lang.Iterable<Segment>`
      Returns:
        an iterator for the source segments of this text unit.

    - #### iterator

          java.util.Iterator<Segment> iterator(LocaleId trgLoc)

      Gets an iterator for the source of the specified target locale. This iterator does not iterate through non-segment parts of the content.
      Parameters:
        `trgLoc` - the target locale for the source to iterate over.
      Returns:
        an iterator for the source segments used for trgLoc.

    - #### append

          void append(Segment srcSeg,
                    Segment trgSeg,
                    LocaleId trgLoc,
                    java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions,
                    java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)

      Adds given source and target segments to the end of the content.

      If srcSeg is non-null, the content of srcSeg will be used for any new segments that are not empty, otherwise the content of trgSeg will be used. srcSeg and trgSeg cannot both be null.

      Parameters:
        `srcSeg` - the source segment to add.
        `trgSeg` - the target segment to add. Null to use a clone of srcSeg instead.
        `trgLoc` - the target locale for which to append segments
        `variantOptions` - determines which sources and targets will have segments added. See `IAlignedSegments.VariantOptions`.
        `copyOptions` - determines whether to use the content of srcSeg or an empty segment for any segments that are added. See `IAlignedSegments.CopyOptions`.
      Throws:
        `java.lang.IllegalArgumentException` - if srcSeg and trgSeg are both null

    - #### insert

          void insert(int index,
                    Segment srcSeg,
                    Segment trgSeg,
                    LocaleId trgLoc,
                    java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions,
                    java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)

      Inserts given source and target segments at the specified position in the list of segments.

      If the same segment content is to be used in multiple sources or targets, the content of the given source segment will be used.

      The validated id (after insertion) of srcSeg will be applied to all other inserted segments, including trgSeg.

      Parameters:
        `index` - the segment index position.
        `srcSeg` - the source segment to insert.
        `trgSeg` - the target segment to insert. Null to use srcSeg instead.
        `trgLoc` - the target locale for which to insert the segment
        `variantOptions` - determines which sources and targets will have a segment inserted. See `IAlignedSegments.VariantOptions`.
        `copyOptions` - determines whether to use the content of srcSeg or an empty segment for any segments that are inserted. See `IAlignedSegments.CopyOptions`.
      Throws:
        `java.lang.IllegalArgumentException` - if srcSeg is null

    - #### setSegment

          void setSegment(int index,
                        Segment seg,
                        LocaleId trgLoc,
                        java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions,
                        java.util.EnumSet<IAlignedSegments.VariantOptions> idUpdateOptions)

      Replaces a segment at a given position with a clone of the given segment.

      The segment id is determined by the segment at the position of index in the source for trgLoc, the segment id is then used to locate the segments in other sources and targets to replace.

      If the id of the new segment is different from the current one, the new id will be propagated to all other sources and targets indicated by idUpdateOptions.

      Parameters:
        `index` - the segment index position
        `seg` - the new segment to place at the position
        `trgLoc` - the locale used to specify the target and source to use
        `variantOptions` - determines which targets and sources will have a segment replaced. See `IAlignedSegments.VariantOptions`.
        `idUpdateOptions` - determines which targets and sources will have their id updated. See `IAlignedSegments.VariantOptions`.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of bounds.
        `java.lang.IllegalArgumentException` - if seg is null

    - #### remove

          boolean remove(Segment seg,
                       LocaleId trgLoc,
                       java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions)

      Removes the given segment and any segments with the same id from the specified sources and targets.
      Parameters:
        `seg` - the segment to remove.
        `trgLoc` - the locale used in specifying which sources and targets to use.
        `variantOptions` - determines which sources and targets will have a segment removed. See `IAlignedSegments.VariantOptions`.
      Returns:
        true if remove success

    - #### getSource

          Segment getSource(int index,
                          LocaleId trgLoc)

      Gets the source segment for the given target locale at a given position.

      The first segment has the index 0, the second has the index 1, etc.

      Parameters:
        `index` - the segment index of the segment to retrieve.
        `trgLoc` - the target locale for the source from which to retrieve the indicated segment.
      Returns:
        the segment at the given position.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of bounds.

    - #### getCorrespondingTarget

          Segment getCorrespondingTarget(Segment seg,
                                       LocaleId trgLoc,
                                       java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions,
                                       java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)

      Gets the target segment corresponding to a given source segment.

      This always returns a segment: If the target does not exists one is created. If the segment does not exists one is created at the end of the target content.

      Parameters:
        `seg` - the source (or other target) segment for which a corresponding target segment is requested.
        `trgLoc` - the target to look up.
        `variantOptions` - determines which sources and targets will have a segment added if the segment does not exist. The option for the target of trgLoc (i.e. MODIFY_TARGET) is ignored so that a segment can always be returned. See `IAlignedSegments.VariantOptions`.
        `copyOptions` - determines whether newly created segments will contain the content of seg. See `IAlignedSegments.CopyOptions`.
      Returns:
        the corresponding target `Segment` (may be empty).

    - #### getCorrespondingTarget

          Segment getCorrespondingTarget(Segment seg,
                                       LocaleId trgLoc)

      Gets the target segment corresponding to a given source segment given the most common use case of one source and one target. Same as calling with `IAlignedSegments.VariantOptions` MODIFY_SOURCE_AND_ASSOCIATED_TARGET and `IAlignedSegments.CopyOptions` COPY_TO_NONE

      This always returns a segment: If the target does not exists one is created. If the segment does not exists one is created at the end of the target content.

      Parameters:
        `seg` - the source (or other target) segment for which a corresponding target segment is requested.
        `trgLoc` - the target to look up.
      Returns:
        the corresponding target `Segment` (may be empty).

    - #### getCorrespondingSource

          Segment getCorrespondingSource(Segment trgSeg,
                                       LocaleId trgLoc,
                                       java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions,
                                       java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)

      Gets the source segment corresponding to a given target segment.

      If no corresponding source segment is found a new one is added at the end of the container and returned as the new corresponding segment.

      Parameters:
        `trgSeg` - the target segment for which the corresponding source segment is requested.
        `trgLoc` - the target locale of the source to look up.
        `variantOptions` - determines which sources and targets will have a segment added if the segment does not exist. The options for the source of trgLoc are ignored so that a segment can always be returned. See `IAlignedSegments.VariantOptions`.
        `copyOptions` - determines whether newly created segments will contain the content of trgSeg. See `IAlignedSegments.CopyOptions`.
      Returns:
        the corresponding source segment.

    - #### getCorrespondingSource

          Segment getCorrespondingSource(Segment trgSeg,
                                       LocaleId trgLoc)

      Gets the source segment corresponding to a given target segment given the most common use case of one source and one target. Same as calling with `IAlignedSegments.VariantOptions` MODIFY_SOURCE_AND_ASSOCIATED_TARGET and `IAlignedSegments.CopyOptions` COPY_TO_NONE

      If no corresponding source segment is found a new one is added at the end of the container and returned as the new corresponding segment.

      Parameters:
        `trgSeg` - the target segment for which the corresponding source segment is requested.
        `trgLoc` - the target locale of the source to look up.

    - #### align

          void align(java.util.List<AlignedPair> alignedSegmentPairs,
                   LocaleId trgLoc)

      Aligns all the segments listed in the aligned pairs for given locale.

      This will replace any content in the target and variant source for the given target locale (if either are not present they will be created).

      The target for the given locale will be considered aligned with its source when this operation is complete.

      Parameters:
        `alignedSegmentPairs` - the list of pairs to align
        `trgLoc` - the target locale to work with.

    - #### align

          void align(LocaleId trgLoc)

      Aligns all the target segments with the source segments for the given locale.

      Assumes the same number of source and target segments otherwise an exception is thrown.

      Parameters:
        `trgLoc` - the locale of the target to work with.
      Throws:
        `OkapiMisAlignmentException` - if there are a different number of source and target segments.

    - #### alignCollapseAll

          void alignCollapseAll(LocaleId trgLoc,
                              java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions)

      Aligns all the segments for the specified sources and targets by collapsing all segments into one.

      variantOptions determines which targets and sources will be collapsed, and targets will be considered aligned with their sources only if both the source and target for that locale are collapsed.

      Parameters:
        `trgLoc` - the target locale of the target (and its corresponding source) to collapse.
        `variantOptions` - determines which targets and sources will be collapsed to a single segment. See `IAlignedSegments.VariantOptions`.

    - #### splitSource

          Segment splitSource(LocaleId trgLoc,
                            Segment srcSeg,
                            int splitPos,
                            java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions,
                            java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)

      Splits a given source segment into two.

      New segments are created to match the given source in any sources and targets indicated by variantOptions, with content either empty or copied from the new source segment as indicated by copyOptions.

      Alignment statuses are updated for all locales that have been modified.

      Parameters:
        `trgLoc` - the target locale that uses the source in which the segment is to be split
        `srcSeg` - the source segment to split.
        `splitPos` - the position where to split.
        `variantOptions` - determines which sources and targets will have new segments added. See `IAlignedSegments.VariantOptions`
        `copyOptions` - determines whether the content of new segments will be empty or the same as the new segment. See `IAlignedSegments.CopyOptions`.
      Returns:
        the new source segment created, or null if none was created.

    - #### splitTarget

          Segment splitTarget(LocaleId trgLoc,
                            Segment trgSeg,
                            int splitPos,
                            java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions,
                            java.util.EnumSet<IAlignedSegments.CopyOptions> copyOptions)

      Splits a given target segment into two.

      New segments are created to match the given target in any sources and targets indicated by variantOptions, with content either empty or copied from the new target segment as indicated by copyOptions.

      Alignment statuses are updated for all locales that have been modified.

      Parameters:
        `trgLoc` - the target locale to work on.
        `trgSeg` - the targets segment.
        `splitPos` - the position where to split.
        `variantOptions` - determines which sources and targets will have new segments added. See `IAlignedSegments.VariantOptions`.
        `copyOptions` - determines whether the content of new segments will be empty or the same as the new segment. See `IAlignedSegments.CopyOptions`.
      Returns:
        the new target segment created, or null if none was created.

    - #### joinWithNext

          void joinWithNext(Segment seg,
                          LocaleId trgLoc,
                          java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions)

      Joins the segment for a given segment's id to the next segment, including all the parts between the two segments.
      Parameters:
        `seg` - a segment holding the id to use for the join.
        `trgLoc` - the target locale used with variantOptions to determine which sources and targets will have segments joined.
        `variantOptions` - determines which sources and targets will have segments joined. See `IAlignedSegments.VariantOptions`.

    - #### joinAll

          void joinAll(LocaleId trgLoc,
                     java.util.EnumSet<IAlignedSegments.VariantOptions> variantOptions)

      Joins all segments for the specified sources and targets. The content becomes a single segment.
      Parameters:
        `trgLoc` - the target locale used with variantOptions to determine which sources and targets will have all segments joined.
        `variantOptions` - determines which sources and targets will have all segments joined. See `IAlignedSegments.VariantOptions`.

    - #### getAlignmentStatus

          AlignmentStatus getAlignmentStatus()

      Gets the status of the alignment for this entire text unit. The status will be NOT_ALIGNED if any of the targets in the parent TextUnit have a status of NOT_ALIGNED
      Returns:
        the status of the alignment for this text unit.

    - #### getAlignmentStatus

          AlignmentStatus getAlignmentStatus(LocaleId trgLoc)

      Gets the status of the alignment the given target locale in this text unit.
      Parameters:
        `trgLoc` - the target locale for which to get the alignment status.
      Returns:
        the status of the alignment for this text unit.

    - #### segmentSource

          void segmentSource(ISegmenter segmenter,
                           LocaleId targetLocale)

      Segments the source content used for the given target locale based on the rules provided by a given `ISegmenter`.

      No associated targets are modified.

      Parameters:
        `segmenter` - the segmenter to use to create the segments.
        `targetLocale` - the target locale that uses the source to segment.

    - #### segmentTarget

          void segmentTarget(ISegmenter segmenter,
                           LocaleId targetLocale)

      Segments the specified target content based on the rules provided by a given `ISegmenter`.

      If the given target does not exist one is created.

      Parameters:
        `segmenter` - the segmenter to use to create the segments.
        `targetLocale` - `LocaleId` of the target we want to segment.