Package net.sourceforge.pmd.lang.document

Class TextRegion

java.lang.Object
net.sourceforge.pmd.lang.document.TextRegion
All Implemented Interfaces:
Comparable<TextRegion>
public final class TextRegion extends Object implements Comparable<TextRegion>
A contiguous range of text in a TextDocument. Empty regions may be thought of like caret positions in an IDE. An empty region at offset n does not contain the character at offset n in the document, but if it were a caret, typing a character c would make c the character at offset n in the document.

Line and column information may be added by TextDocument.toLocation(TextRegion).

Regions are not bound to a specific document, keeping a reference to them does not prevent the document from being garbage-collected.

Regions are represented as a simple offset+length tuple. In a document, valid start offsets range from 0 to TextDocument.getLength() (inclusive). The sum startOffset + length must range from startOffset to getLength() (inclusive).

Those rules make the region starting at TextDocument.getLength() with length 0 a valid region (the caret position at the end of the document).

For example, for a document of length 1 ("c"), there are only three valid regions: 


 [[c     : caret position at offset 0 (empty region)
  [c[    : range containing the character
   c[[   : caret position at offset 1 (empty region)

  • Method Details

    • getStartOffset

      public int getStartOffset()
      0-based, inclusive index.

    • getEndOffset

      public int getEndOffset()
      0-based, exclusive index.

    • getLength

      public int getLength()
      Returns the length of the region in characters. This is the difference between start offset and end offset. All characters have length 1, including '\t'. The sequence "\r\n" has length 2 and not 1.

    • isEmpty

      public boolean isEmpty()
      Returns true if the region contains no characters. In that case it can be viewed as a caret position, and e.g. used for text insertion.

    • contains

      public boolean contains(int offset)
      Returns true if this region contains the character at the given offset. Note that a region with length zero does not even contain the character at its start offset.
      Parameters:
      offset - Offset of a character

    • contains

      public boolean contains(TextRegion other)
      Returns true if this region contains the entirety of the other region. Any region contains itself.
      Parameters:
      other - Other region

    • overlaps

      public boolean overlaps(TextRegion other)
      Returns true if this region overlaps the other region by at least one character. This is a symmetric, reflexive relation.
      Parameters:
      other - Other region

    • growLeft

      public TextRegion growLeft(int delta)
      Returns a region that ends at the same point, but starts 'delta' characters before this region. If the delta is negative, then this shifts the start of the region to the right (but the end stays fixed).
      Throws:
      AssertionError - If the parameter cannot produce a valid region

    • growRight

      public TextRegion growRight(int delta)
      Returns a region that starts at the same point, but ends 'delta' characters after this region. If the delta is negative, then this shifts the end of the region to the left (but the start stays fixed).
      Throws:
      AssertionError - If the delta is negative and less than the length of this region

    • intersect

      public static @Nullable TextRegion intersect(TextRegion r1, TextRegion r2)
      Computes the intersection of this region with the other. This is the largest region that this region and the parameter both contain. It may have length zero, or not exist (if the regions are completely disjoint).
      Returns:
      The intersection, if it exists

    • union

      public static TextRegion union(TextRegion r1, TextRegion r2)
      Computes the union of this region with the other. This is the smallest region that contains both this region and the parameter.
      Returns:
      The union of both regions

    • fromOffsetLength

      public static TextRegion fromOffsetLength(int startOffset, int length)
      Builds a new region from offset and length.
      Throws:
      AssertionError - If either parameter is negative

    • fromBothOffsets

      public static TextRegion fromBothOffsets(int startOffset, int endOffset)
      Builds a new region from start and end offset.
      Parameters:
      startOffset - Start offset (inclusive)
      endOffset - End offset (exclusive)
      Throws:
      AssertionError - If either offset is negative, or the two offsets are not ordered

    • caretAt

      public static TextRegion caretAt(int startOffset)
      Builds a new region with zero length and placed at the given offset.
      Parameters:
      startOffset - Offset for start and end of the position.
      Throws:
      AssertionError - If the offset is negative

    • isValidRegion

      public static boolean isValidRegion(int startOffset, int endOffset, TextDocument doc)
      Checks that the parameters are a valid region, this is provided to debug, will be a noop unless assertions are enabled.

    • compareTo

      public int compareTo(@NonNull TextRegion o)
      Compares the start offset, then the length of a region.
      Specified by:
      compareTo in interface Comparable<TextRegion>

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object