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).