Range (POI API Documentation)

java.lang.Object
- org.apache.poi.hwpf.usermodel.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 and 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 and 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 and 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
  - getDocument
```
protected HWPFDocumentCore getDocument()
```
  - 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.

Class Range

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TYPE_PARAGRAPH

TYPE_CHARACTER

TYPE_SECTION

TYPE_TEXT

TYPE_LISTENTRY

TYPE_TABLE

TYPE_UNDEFINED

_start

_end

_doc

_sections

_sectionStart

_sectionEnd

_parRangeFound

_paragraphs

_parStart

_parEnd

_charRangeFound

_characters

_charStart

_charEnd

_text

Constructor Detail

Range

Range

Method Detail

text

stripFields

numSections

numParagraphs

numCharacterRuns

insertBefore

insertAfter

delete

insertTableBefore

replaceText

replaceText

replaceText

getCharacterRun

getSection

getParagraph

getTable

initAll

reset

adjustFIB

getStartOffset

getEndOffset

getDocument

toString

sanityCheck