1 /*

     2  * Copyright (C) 2008, 2009 Apple Inc. All Rights Reserved.

     3  *

     4  * Redistribution and use in source and binary forms, with or without

     5  * modification, are permitted provided that the following conditions

     6  * are met:

     7  * 1. Redistributions of source code must retain the above copyright

     8  *    notice, this list of conditions and the following disclaimer.

     9  * 2. Redistributions in binary form must reproduce the above copyright

    10  *    notice, this list of conditions and the following disclaimer in the

    11  *    documentation and/or other materials provided with the distribution.

    12  *

    13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY

    14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

    15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR

    16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR

    17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

    18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

    19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

    20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY

    21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

    22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

    23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

    24  */

    25 

    26 #import <Foundation/Foundation.h>

    27 

    28 #if MAC_OS_X_VERSION_MAX_ALLOWED <= MAC_OS_X_VERSION_10_4

    29 #define WebNSUInteger unsigned int

    30 #else

    31 #define WebNSUInteger NSUInteger

    32 #endif

    33 

    34 @class DOMRange;

    35 @class DOMNode;

    36 @class WebTextIteratorPrivate;

    37 

    38 @interface WebTextIterator : NSObject {

    39 @private

    40     WebTextIteratorPrivate *_private;

    41 }

    42 

    43 - (id)initWithRange:(DOMRange *)range;

    44 

    45 /*!

    46  @method advance

    47  @abstract Moves the WebTextIterator to the next bit of text or boundary between runs of text.

    48  The iterator can break up runs of text however it finds convenient, so clients need to handle

    49  text runs that are broken up into arbitrary pieces.

    50  */

    51 - (void)advance;

    52 

    53 /*!

    54  @method atEnd

    55  @result YES if the WebTextIterator has reached the end of the DOMRange.

    56  */

    57 - (BOOL)atEnd;

    58 

    59 /*!

    60  @method currentTextLength

    61  @result Length of the current text. Length of zero means that the iterator is at a boundary,

    62  such as an image, that separates runs of text.

    63  */

    64 - (WebNSUInteger)currentTextLength;

    65 

    66 /*!

    67  @method currentTextPointer

    68  @result A pointer to the current text. Like the WebTextIterator itself, the pointer becomes

    69  invalid after any modification is made to the document; it must be used before the document

    70  is changed or the iterator is advanced.

    71  */

    72 - (const unichar *)currentTextPointer;

    73 

    74 /*!

    75  @method currentRange

    76  @abstract A function that identifies the specific document range that text corresponds to.

    77  This can be quite costly to compute for non-text items, so when possible this should only

    78  be called once the caller has determined that the text is text it wants to process. If you

    79  call currentRange every time you advance the iterator, performance will be extremely slow

    80  due to the cost of computing a DOM range.

    81  @result A DOM range indicating the position within the document of the current text.

    82  */

    83 - (DOMRange *)currentRange;

    84 

    85 @end

    86 

    87 @interface WebTextIterator (WebTextIteratorDeprecated)

    88 

    89 /*!

    90  @method currentNode

    91  @abstract A convenience method that finds the first node in currentRange; it's almost always better to use currentRange instead.

    92  @result The current DOMNode in the WebTextIterator

    93  */

    94 - (DOMNode *)currentNode;

    95 

    96 /*!

    97  @method currentText

    98  @abstract A convenience method that makes an NSString out of the current text; it's almost always better to use currentTextPointer and currentTextLength instead.

    99  @result The current text in the WebTextIterator.

   100  */

   101 - (NSString *)currentText;

   102 

   103 @end

   104 

   105 #undef WebNSUInteger