I think the definition of getText should be like the
OS read() methods: the length parameter is a suggestion,
and you get told how many actually got read.  This would
allow representations like GapContent to *never* allocate
memory.  As it is, if you're writing a search routine
(like me) and you try something foolish like getText(0,doc.getLength(),segment)
GapContent will make a full copy of the document!  What's worse,
there's no real way to avoid this since you can't tell where
the split in GapContent's buffer is (I now do getText's in
small chunks so that I avoid the huge allocation).

It may be that you actually want a new method, getTextPartial(...)
but I do believe these partial result semantics are *essential* for
a wide variety of purposes.

N/A

This should be added for merlin.  By adding a flag to Segment, the method
could support partial returns without compatibility problems.

  xxxxx@xxxxx   2000-11-19

Added the following API change, javadoc changes, and GapContent now supports
the partial return flag:

The addition of a flag on the javax.swing.text.Segment class to indicate
that partial returns are ok.

  /** 
   * Flag to indicate that partial returns are valid.  If the flag is true, 
   * an implementation of the interface method Document.getText(position,length,Segment) 
   * should return as much text as possible without making a copy.  The default 
   * state of the flag is false which will cause Document.getText(position,length,Segment) 
   * to provide the same return behavior it currently does, which may or may not 
   * make a copy of the text depending upon the request.   
   * 
   * @param p whether or not partial returns are valid.
   * @since 1.4
   */
  void setPartialReturn(boolean b) {
  }

  /**
   * Flag to indicate that partial returns are valid. 
   *
   * @return whether or not partial returns are valid.
   * @since 1.4
   */
  boolean isPartialReturn() {
  }

The javadoc for the Document.getText method will be changed to indicate
the new functionality.

    /**
     * Fetches the text contained within the given portion 
     * of the document.
     * <p>
     * If the partialReturn property on the txt parameter is false, the
     * data returned in the Segment will be the entire length requested and
     * may or may not be a copy depending upon how the data was stored.
     * If the partialReturn property is true, only the amount of text that
     * can be returned without creating a copy is returned.  Using partial
     * returns will give better performance for situations where large 
     * parts of the document are being scanned.  The following is an example
     * of using the partial return:
     * <p>
     * <pre><code>
     *
     * &nbsp; int nleft = doc.getLength();
     * &nbsp; Segment text = new Segment();
     * &nbsp; int offs = 0;
     * &nbsp; text.setPartialReturn(true);   
     * &nbsp; while (nleft > 0) {
     * &nbsp;     doc.getText(offs, nleft, text);
     * &nbsp;     // do someting with text
     * &nbsp;     nleft -= text.count;
     * &nbsp;     offs += text.count;
     * &nbsp; }
     *
     * </code></pre>
     *
     * @param offset  the offset into the document representing the desired 
     *   start of the text >= 0
     * @param length  the length of the desired string >= 0
     * @param txt the Segment object to return the text in
     *
     * @exception BadLocationException  Some portion of the given range
     *   was not a valid part of the document.  The location in the exception
     *   is the first bad position encountered.
     */
    public void getText(int offset, int length, Segment txt) throws BadLocationException;

The javadoc for AbstractDocument.getText has also been changed.

  xxxxx@xxxxx   2000-11-30