Class Range

  • Direct Known Subclasses:
    CharacterRun, Paragraph, Section, Table, TableCell, TableRow

    public class Range
    extends java.lang.Object
    This class is the central class of the HWPF object model. All properties that apply to a range of characters in a Word document extend this class. It is possible to insert text and/or properties at the beginning or end of a range. Ranges are only valid if there hasn't been an insert in a prior Range since the Range's creation. Once an element (text, paragraph, etc.) has been inserted into a Range, subsequent Ranges become unstable.
    Author:
    Ryan Ackley
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.List<CHPX> _characters
      All CharacterRuns that belong to the document this Range belongs to.
      protected int _charEnd
      The end index in the characterRuns list for this Range.
      protected boolean _charRangeFound
      Have we loaded the characterRun indexes yet.
      protected int _charStart
      The start index in the characterRuns list for this Range
      protected HWPFDocumentCore _doc
      The document this range belongs to.
      protected int _end
      The ending character offset of this range.
      protected java.util.List<PAPX> _paragraphs
      All paragraphs that belong to the document this Range belongs to.
      protected int _parEnd
      The end index in the paragraphs list for this Range, exclusive
      protected boolean _parRangeFound
      Have we loaded the paragraph indexes yet.
      protected int _parStart
      The start index in the paragraphs list for this Range, inclusive
      protected int _sectionEnd
      The end index in the sections list for this Range.
      protected java.util.List<SEPX> _sections
      All sections that belong to the document this Range belongs to.
      protected int _sectionStart
      The start index in the sections list for this Range
      protected int _start
      The starting character offset of this range.
      protected java.lang.StringBuilder _text  
      static int TYPE_CHARACTER
      Deprecated.
      POI 3.8 beta 5
      static int TYPE_LISTENTRY
      Deprecated.
      POI 3.8 beta 5
      static int TYPE_PARAGRAPH
      Deprecated.
      POI 3.8 beta 5
      static int TYPE_SECTION
      Deprecated.
      POI 3.8 beta 5
      static int TYPE_TABLE
      Deprecated.
      POI 3.8 beta 5
      static int TYPE_TEXT
      Deprecated.
      POI 3.8 beta 5
      static int TYPE_UNDEFINED
      Deprecated.
      POI 3.8 beta 5
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        Range​(int start, int end, HWPFDocumentCore doc)
      Used to construct a Range from a document.
      protected Range​(int start, int end, Range parent)
      Used to create Ranges that are children of other Ranges.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void adjustFIB​(int adjustment)
      Adjust the value of the various FIB character count fields, eg FIB.CCPText after an insert or a delete...
      void delete()  
      CharacterRun getCharacterRun​(int index)
      Gets the character run at index.
      protected HWPFDocumentCore getDocument()  
      int getEndOffset()  
      Paragraph getParagraph​(int index)
      Gets the paragraph at index.
      Section getSection​(int index)
      Gets the section at index.
      int getStartOffset()  
      Table getTable​(Paragraph paragraph)
      Gets the table that starts with paragraph.
      protected void initAll()
      loads all of the list indexes.
      CharacterRun insertAfter​(java.lang.String text)
      Inserts text onto the end of this range
      CharacterRun insertBefore​(java.lang.String text)
      Inserts text into the front of this range.
      Table insertTableBefore​(short columns, int rows)
      Inserts a simple table into the beginning of this range.
      int numCharacterRuns()  
      int numParagraphs()
      Used to get the number of paragraphs in a range.
      int numSections()
      Used to get the number of sections in a range.
      void replaceText​(java.lang.String newText, boolean addAfter)
      Replace range text with new one, adding it to the range and deleting original text from document
      void replaceText​(java.lang.String pPlaceHolder, java.lang.String pValue)
      Replace (all instances of) a piece of text with another...
      void replaceText​(java.lang.String pPlaceHolder, java.lang.String pValue, int pOffset)
      Replace (one instance of) a piece of text with another...
      protected void reset()
      resets the list indexes.
      boolean sanityCheck()
      Method for debug purposes.
      static java.lang.String stripFields​(java.lang.String text)
      Removes any fields (eg macros, page markers etc) from the string.
      java.lang.String text()
      Gets the text that this Range contains.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • TYPE_PARAGRAPH

        @Deprecated
        public static final int TYPE_PARAGRAPH
        Deprecated.
        POI 3.8 beta 5
        See Also:
        Constant Field Values
      • TYPE_CHARACTER

        @Deprecated
        public static final int TYPE_CHARACTER
        Deprecated.
        POI 3.8 beta 5
        See Also:
        Constant Field Values
      • TYPE_SECTION

        @Deprecated
        public static final int TYPE_SECTION
        Deprecated.
        POI 3.8 beta 5
        See Also:
        Constant Field Values
      • TYPE_TEXT

        @Deprecated
        public static final int TYPE_TEXT
        Deprecated.
        POI 3.8 beta 5
        See Also:
        Constant Field Values
      • TYPE_LISTENTRY

        @Deprecated
        public static final int TYPE_LISTENTRY
        Deprecated.
        POI 3.8 beta 5
        See Also:
        Constant Field Values
      • TYPE_TABLE

        @Deprecated
        public static final int TYPE_TABLE
        Deprecated.
        POI 3.8 beta 5
        See Also:
        Constant Field Values
      • TYPE_UNDEFINED

        @Deprecated
        public static final int TYPE_UNDEFINED
        Deprecated.
        POI 3.8 beta 5
        See Also:
        Constant Field Values
      • _start

        protected final int _start
        The starting character offset of this range.
      • _end

        protected int _end
        The ending character offset of this range.
      • _doc

        protected final HWPFDocumentCore _doc
        The document this range belongs to.
      • _sections

        protected final java.util.List<SEPX> _sections
        All sections that belong to the document this Range belongs to.
      • _sectionStart

        protected int _sectionStart
        The start index in the sections list for this Range
      • _sectionEnd

        protected int _sectionEnd
        The end index in the sections list for this Range.
      • _parRangeFound

        protected boolean _parRangeFound
        Have we loaded the paragraph indexes yet.
      • _paragraphs

        protected final java.util.List<PAPX> _paragraphs
        All paragraphs that belong to the document this Range belongs to.
      • _parStart

        protected int _parStart
        The start index in the paragraphs list for this Range, inclusive
      • _parEnd

        protected int _parEnd
        The end index in the paragraphs list for this Range, exclusive
      • _charRangeFound

        protected boolean _charRangeFound
        Have we loaded the characterRun indexes yet.
      • _characters

        protected java.util.List<CHPX> _characters
        All CharacterRuns that belong to the document this Range belongs to.
      • _charStart

        protected int _charStart
        The start index in the characterRuns list for this Range
      • _charEnd

        protected int _charEnd
        The end index in the characterRuns list for this Range.
      • _text

        protected java.lang.StringBuilder _text
    • Constructor Detail

      • Range

        public Range​(int start,
                     int end,
                     HWPFDocumentCore doc)
        Used to construct a Range from a document. This is generally used to create a Range that spans the whole document, or at least one whole part of the document (eg main text, header, comment)
        Parameters:
        start - Starting character offset of the range.
        end - Ending character offset of the range.
        doc - The HWPFDocument the range is based on.
      • Range

        protected Range​(int start,
                        int end,
                        Range parent)
        Used to create Ranges that are children of other Ranges.
        Parameters:
        start - Starting character offset of the range.
        end - Ending character offset of the range.
        parent - The parent this range belongs to.
    • Method Detail

      • text

        public java.lang.String text()
        Gets the text that this Range contains.
        Returns:
        The text for this range.
      • stripFields

        public static java.lang.String stripFields​(java.lang.String text)
        Removes any fields (eg macros, page markers etc) from the string. Normally used to make some text suitable for showing to humans, and the resultant text should not normally be saved back into the document!
      • numSections

        public int numSections()
        Used to get the number of sections in a range. If this range is smaller than a section, it will return 1 for its containing section.
        Returns:
        The number of sections in this range.
      • numParagraphs

        public int numParagraphs()
        Used to get the number of paragraphs in a range. If this range is smaller than a paragraph, it will return 1 for its containing paragraph.
        Returns:
        The number of paragraphs in this range.
      • numCharacterRuns

        public int numCharacterRuns()
        Returns:
        The number of characterRuns in this range.
      • insertBefore

        public CharacterRun insertBefore​(java.lang.String text)
        Inserts text into the front of this range.
        Parameters:
        text - The text to insert
        Returns:
        The character run that text was inserted into.
      • insertAfter

        public CharacterRun insertAfter​(java.lang.String text)
        Inserts text onto the end of this range
        Parameters:
        text - The text to insert
        Returns:
        The character run the text was inserted into.
      • delete

        public void delete()
      • insertTableBefore

        public Table insertTableBefore​(short columns,
                                       int rows)
        Inserts a simple table into the beginning of this range.
        Parameters:
        columns - The number of columns
        rows - The number of rows.
        Returns:
        The empty Table that is now part of the document.
      • replaceText

        public void replaceText​(java.lang.String newText,
                                boolean addAfter)
        Replace range text with new one, adding it to the range and deleting original text from document
        Parameters:
        newText - The text to be replaced with
        addAfter - if true the text will be added at the end of current range, otherwise to the beginning
      • replaceText

        @Internal
        public void replaceText​(java.lang.String pPlaceHolder,
                                java.lang.String pValue,
                                int pOffset)
        Replace (one instance of) a piece of text with another...
        Parameters:
        pPlaceHolder - The text to be replaced (e.g., "${organization}")
        pValue - The replacement text (e.g., "Apache Software Foundation")
        pOffset - The offset or index where the text to be replaced begins (relative to/within this Range)
      • replaceText

        public void replaceText​(java.lang.String pPlaceHolder,
                                java.lang.String pValue)
        Replace (all instances of) a piece of text with another...
        Parameters:
        pPlaceHolder - The text to be replaced (e.g., "${organization}")
        pValue - The replacement text (e.g., "Apache Software Foundation")
      • getCharacterRun

        public CharacterRun getCharacterRun​(int index)
        Gets the character run at index. The index is relative to this range.
        Parameters:
        index - The index of the character run to get.
        Returns:
        The character run at the specified index in this range.
      • getSection

        public Section getSection​(int index)
        Gets the section at index. The index is relative to this range.
        Parameters:
        index - The index of the section to get.
        Returns:
        The section at the specified index in this range.
      • getParagraph

        public Paragraph getParagraph​(int index)
        Gets the paragraph at index. The index is relative to this range.
        Parameters:
        index - The index of the paragraph to get.
        Returns:
        The paragraph at the specified index in this range.
      • getTable

        public Table getTable​(Paragraph paragraph)
        Gets the table that starts with paragraph. In a Word file, a table consists of a group of paragraphs with certain flags set.
        Parameters:
        paragraph - The paragraph that is the first paragraph in the table.
        Returns:
        The table that starts with paragraph
      • initAll

        protected void initAll()
        loads all of the list indexes.
      • reset

        protected void reset()
        resets the list indexes.
      • adjustFIB

        protected void adjustFIB​(int adjustment)
        Adjust the value of the various FIB character count fields, eg FIB.CCPText after an insert or a delete... Works on all CCP fields from this range onwards
        Parameters:
        adjustment - The (signed) value that should be added to the FIB CCP fields
      • getStartOffset

        public int getStartOffset()
        Returns:
        Starting character offset of the range
      • getEndOffset

        public int getEndOffset()
        Returns:
        The ending character offset of this range
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • sanityCheck

        public boolean sanityCheck()
        Method for debug purposes. Checks that all resolved elements are inside of current range. Throws IllegalArgumentException if checks fail.