Package opennlp.tools.util.normalizer

# Class Alignment

java.lang.Object
opennlp.tools.util.normalizer.Alignment

@ThreadSafe public final class Alignment extends Object
A bidirectional alignment between an original text and a normalized form of it.

Normalization edits text in ways that move character offsets: a run of whitespace collapses to one space, a supplementary dash folds to a single ASCII hyphen, a case fold can grow text (German `eszett` to `ss`), and trimming or stripping deletes characters outright. An `Alignment` records those edits as a sequence of equal runs (text copied through unchanged in length) and replace runs (a block of original characters that produced a block of normalized characters), so any span in either form can be mapped to the other.

Because it represents deletions as gaps and expansions as shared blocks (rather than storing a single original offset per normalized character, which would assume the normalized text contiguously covers the original), mapping is done span to span (`toOriginalSpan(int, int)` / `toNormalizedSpan(int, int)`) so a match that ends next to deleted text reports a tight span rather than over-covering the deletion. Two alignments compose with `andThen(Alignment)`, which is what lets a multi-stage normalization pipeline still map a result all the way back to the original.

Instances are immutable and thread-safe; build one with `Alignment.Builder`.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `Alignment.Builder`
  Builds an `Alignment` as the normalized text is produced, by recording each edit in order.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Alignment`
  `andThen(Alignment next)`
  Composes this alignment with one that further normalizes this alignment's normalized text.
  `int`
  `normalizedLength()`
  Returns the length of the normalized text this alignment was built for.
  `int`
  `originalLength()`
  Returns the length of the original text this alignment was built for.
  `Span`
  `toNormalizedSpan(int originalStartOffset, int originalEndOffset)`
  Maps a half-open span of the original text to the half-open span of the normalized text that covers it.
  `int`
  `toOriginalOffset(int normalizedOffset)`
  Maps a normalized offset to the original offset where its character begins (start semantics).
  `Span`
  `toOriginalSpan(int normalizedStart, int normalizedEnd)`
  Maps a half-open span of the normalized text to the tightest half-open span of the original text that produced it.

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

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

- ## Method Details

  - ### normalizedLength

    public int normalizedLength()
    Returns the length of the normalized text this alignment was built for.
    Returns:
      the length of the normalized text this alignment was built for

  - ### originalLength

    public int originalLength()
    Returns the length of the original text this alignment was built for.
    Returns:
      the length of the original text this alignment was built for

  - ### toOriginalSpan

    public Span toOriginalSpan(int normalizedStart, int normalizedEnd)
    Maps a half-open span of the normalized text to the tightest half-open span of the original text that produced it.
    Parameters:
      `normalizedStart` - The inclusive start offset, in `[0, normalizedLength()]`.
      `normalizedEnd` - The exclusive end offset, in `[normalizedStart, normalizedLength()]`.
    Returns:
      The corresponding original span.
    Throws:
      `IndexOutOfBoundsException` - Thrown if the offsets are out of range or inverted.

  - ### toNormalizedSpan

    public Span toNormalizedSpan(int originalStartOffset, int originalEndOffset)
    Maps a half-open span of the original text to the half-open span of the normalized text that covers it. Original characters that were deleted map to an empty span at the point where they were removed.
    Parameters:
      `originalStartOffset` - The inclusive start offset, in `[0, originalLength()]`.
      `originalEndOffset` - The exclusive end offset, in `[originalStartOffset, originalLength()]`.
    Returns:
      The corresponding normalized span.
    Throws:
      `IndexOutOfBoundsException` - Thrown if the offsets are out of range or inverted.

  - ### toOriginalOffset

    public int toOriginalOffset(int normalizedOffset)
    Maps a normalized offset to the original offset where its character begins (start semantics). Prefer `toOriginalSpan(int, int)` for mapping a match, since a single offset cannot distinguish the start and end of a span across a deletion.
    Parameters:
      `normalizedOffset` - An offset in `[0, normalizedLength()]`.
    Returns:
      The corresponding original offset.
    Throws:
      `IndexOutOfBoundsException` - Thrown if `normalizedOffset` is out of range.

  - ### andThen

    public Alignment andThen(Alignment next)
    Composes this alignment with one that further normalizes this alignment's normalized text.

    If this maps `original -> middle` and `next` maps `middle -> final`, the result maps `original -> final` directly, so a span found in the final text can be mapped straight back to the original without keeping the intermediate stages.

    Parameters:
      `next` - The next stage, whose original side is this stage's normalized text.
    Returns:
      The composed alignment.
    Throws:
      `IllegalArgumentException` - Thrown if `next.originalLength()` does not equal this `normalizedLength()` (the stages do not line up).