Package net.sourceforge.pmd.lang.document

Class 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 Detail

      • 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
        endOffset - End offset
        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.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object