001: /*
002: * Sun Public License Notice
003: *
004: * The contents of this file are subject to the Sun Public License
005: * Version 1.0 (the "License"). You may not use this file except in
006: * compliance with the License. A copy of the License is available at
007: * http://www.sun.com/
008: *
009: * The Original Code is NetBeans. The Initial Developer of the Original
010: * Code is Sun Microsystems, Inc. Portions Copyright 1997-2000 Sun
011: * Microsystems, Inc. All Rights Reserved.
012: */
013:
014: package org.netbeans.editor;
015:
016: /**
017: * Finders are used to find some information in document without creating copy
018: * of the data. They are used as arguments for <CODE>DocCache.find()</CODE>.
019: * During the find operation the <CODE>find()</CODE> method of the finder is
020: * called with some buffer of character data and some additional information.
021: * There are two possible search directions and therefore there are two finder
022: * types: Forward Finders (FwdFinder) and Backward Finders (BwdFinder)
023: *
024: * @author Miloslav Metelka
025: * @version 1.00
026: */
027:
028: public interface Finder {
029:
030: /**
031: * Reset method is used to initialize finder. It is called once at the
032: * begining of find. To be most effective <CODE>reset()</CODE> is called
033: * after both <CODE>setForward()</CODE> and <CODE>setLimitPos()</CODE>
034: * had been called.
035: */
036: public void reset();
037:
038: /**
039: * This is the most important function in finder. It can be called several
040: * times if the whole search area doesn't fit in the cache buffer. Usual
041: * forward search should look like this: <CODE> int offset = reqPos -
042: * bufferStartPos; while (offset < offset2) { if
043: * (buffer[offset]-meets-condition) { set-found-flag return offset +
044: * bufferStartPos; } offset++; } return offset + bufferStartPos;</CODE>
045: * Bakward search follows: <CODE> int offset = reqPos - bufferStartPos while
046: * (offset >= offset1) { if (buffer[offset]-meets-condition) {
047: * set-found-flag return offset + bufferStartPos; } offset--; } return
048: * offset + bufferStartPos;</CODE> Caution! Nothing can be written to the
049: * data comming in buffer to <CODE>find()</CODE> method because of
050: * performance reasons these are primary document data, not a copy. Buffer
051: * is always guaranteed to have at least one char - it is char standing at
052: * reqPos. However there can be calls to <CODE>find()</CODE> when there
053: * will be only that one character, so <CODE>find()</CODE> must must be
054: * prepared for this. Unlike calling <CODE>DocCache.find()</CODE> the
055: * offset1 < offset2 even for backward searches.
056: *
057: * @param bufferStartPos
058: * begining position of the buffer (not search area).
059: * @param buffer
060: * buffer with chars to be searched
061: * @param offset1
062: * offset of begining of searchable area in buffer. No searching
063: * below this offset can be performed.
064: * @param offset2
065: * offset of end of searchable area in buffer. No searching
066: * beyond this offset can be performed.
067: * @param reqPos
068: * required position. Initially it is the begining search
069: * position requested by caller. In subsequent calls it is the
070: * same value as returned from previous call to <CODE>find()</CODE>
071: * method.
072: * @param limitPos
073: * is filled with position beyond which search cannot go. (i.e.
074: * forward: pos < limitPos and backward: pos >= limitPos)
075: * Some finders i.e. finder that tries to find some word with
076: * whole-words-only flag turned on can benefit from this
077: * information. If the searched word is at the very end of the
078: * document the finder wouldn't normally find it as it would
079: * request the next buffer even when the whole word was matched
080: * because the finder needs to find white space to know the word
081: * ended there. However this would be beyond the search area so
082: * EOT exception would be raised. To correctly manage this
083: * situation finder must care for limitPos. When it sees the word
084: * and knows this is the last text in document it signals that it
085: * found the word.
086: * @return in case the string was found, <CODE>find()</CODE> method
087: * returns the position (not offset) where the string starts (and
088: * must also set some flag resulting to that <CODE>isFound()</CODE>
089: * method will return true). If the string was not yet found, the
090: * function should return position (not offset) where the next
091: * search should continue. If this position is greater or equal than
092: * limit position (lower than limit position for backward search),
093: * searching will stop resulting in -1 as returned position. The
094: * position returned will be passed as <CODE>reqPos</CODE> in next
095: * call to <CODE>find()</CODE> method.
096: */
097: public int find(int bufferStartPos, char buffer[], int offset1,
098: int offset2, int reqPos, int limitPos);
099:
100: /**
101: * Using this function caller determines if finder found desired string. The
102: * returned position of <CODE>find</CODE> method gives the position where
103: * the string occurs.
104: */
105: public boolean isFound();
106:
107: }
|