# Function Reference

# _Word_DocFind

Runs or repeats the specified find operation

#include <Word.au3>
_Word_DocFind ( $oDoc [, $sFindText = "" [, $vSearchRange = 0 [, $oFindRange = Default [, $bForward = True [, $bMatchCase = False [, $bMatchWholeWord = False [, $bMatchWildcards = False [, $bMatchSoundsLike = False [, $bMatchAllWordForms = False [, $bFormat = False]]]]]]]]]] )

## Parameters

$oDoc | Word document object
$sFindText | [optional] The text to be searched for. Use an empty string ("") to search for formatting only. You can search for special characters by specifying appropriate character codes. For example, "^p" corresponds to a paragraph mark and "^t" corresponds to a tab character (default = "")
$vSearchRange | [optional] Specifies the selection or range to search. Can be: -1 - Specifies the current selection 0 - Specifies the entire document (default) Any Word range object
$oFindRange | [optional] Specifies the range returned by the last call to _Word_DocFind(). This is required if you want to search for the next or previous occurrence of $sFindText. If set to Default then the search starts at the start of the $vSearchRange (default)
$bForward | [optional] True to search forward (toward the end of the document) (default = True)
$bMatchCase | [optional] If True the find is case sensitive (default = False)
$bMatchWholeWord | [optional] If True only find entire words (default = False)
$bMatchWildcards | [optional] If True the find text has special search operators (default = False)
$bMatchSoundsLike | [optional] If True finds words that sound similar to the find text (default = False)
$bMatchAllWordForms | [optional] If True finds all forms of the find text (e.g. "sit" locates "sitting" and "sat") (default = False)
$bFormat | [optional] True to have the find operation locate formatting in addition to or instead of the find text (default = False)

## Return Value

Success: | a range object for the found text.
Failure: | 0 and sets the @error flag to non-zero.
@error: | 1 - $oDoc is not an object 2 - $vSearchRange is not an object 3 - $oFindRange is not an object 4 - $sFindText could not be found. @extended is set to the COM error code

## Related

_Word_DocFindReplace

## Example

### Example 1

    #include "Extras\HelpFileInternals.au3"

    #include <MsgBoxConstants.au3>
    #include <Word.au3>

    ; Create application object
    Local $oWord = _Word_Create()
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error creating the Word application object." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    ; Open test document read-only
    Local $oDoc = _Word_DocOpen($oWord, _Extras_PathFull("Test.doc"), Default, Default, True)
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error opening '.\Extras\Test.doc'." & @CRLF & "@error = " & @error & ", @extended = " & @extended)

    ; Find the last text "test document" in the document and mark it bold.
    Local $oRangeFound
    #forceref $oRangeFound
    $oRangeFound = _Word_DocFind($oDoc, "test document", 0, Default, False)
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error locating the specified text in the document." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    $oRangeFound.Bold = True
    MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Last occurrence of string 'test document' in the document marked as bold.")

### Example 2

    #include "Extras\HelpFileInternals.au3"

    #include <MsgBoxConstants.au3>
    #include <Word.au3>

    ; Create application object
    Local $oWord = _Word_Create()
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error creating the Word application object." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    ; Open test document read-only
    Local $oDoc = _Word_DocOpen($oWord, _Extras_PathFull("Test.doc"), Default, Default, True)
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error opening '.\Extras\Test.doc'." & @CRLF & "@error = " & @error & ", @extended = " & @extended)

    ; Underline text "line" in lines 2-4.
    Local $oRangeFound, $oSearchRange
    $oSearchRange = _Word_DocRangeSet($oDoc, -1, $wdParagraph, 1, $wdParagraph, 3)
    $oRangeFound = _Word_DocFind($oDoc, "line", $oSearchRange)
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error locating the specified text in the document." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    $oRangeFound.Underline = True
    While 1
        $oRangeFound = _Word_DocFind($oDoc, "line", $oSearchRange, $oRangeFound)
        If @error Then ExitLoop
        $oRangeFound.Underline = True
    WEnd
    MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "All occurrences of string 'line' in paragraphs 2-4 marked as underlined.")

### Example 3

    #include "Extras\HelpFileInternals.au3"

    #include <MsgBoxConstants.au3>
    #include <Word.au3>

    ; Create application object
    Local $oWord = _Word_Create()
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error creating the Word application object." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    ; Open test document read-only
    Local $oDoc = _Word_DocOpen($oWord, _Extras_PathFull("Test.doc"), Default, Default, True)
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error opening '.\Extras\Test.doc'." & @CRLF & "@error = " & @error & ", @extended = " & @extended)

    ; Search for text "line" in lines 2-4 and mark the following number as bold.
    ; If the number is "3" insert text before text "line".
    Local $oRangeFound, $oSearchRange, $oRangeText
    $oSearchRange = _Word_DocRangeSet($oDoc, -1, $wdParagraph, 1, $wdParagraph, 3)
    $oRangeFound = _Word_DocFind($oDoc, "line", $oSearchRange)
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error locating the specified text in the document." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    ; Mark the line number as bold. Create a new range moved one word to the right
    $oRangeText = _Word_DocRangeSet($oDoc, $oRangeFound, Default, 1, Default, 1)
    $oRangeText.Bold = True
    While 1
        $oRangeFound = _Word_DocFind($oDoc, "line", $oSearchRange, $oRangeFound)
        If @error Then ExitLoop
        ; Mark the line number as bold. Create a new range (duplicate to not alter the result of the find operating) and move it one word to the right
        $oRangeText = $oRangeFound.Duplicate
        $oRangeText = _Word_DocRangeSet($oDoc, $oRangeText, Default, 1, Default, 1)
        $oRangeText.Bold = True
        ; Insert text if linenumber = 3
        If StringStripWS($oRangeText.Text, 8) = "3" Then $oRangeFound.InsertBefore("(maybe) ")
    WEnd
    MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "All line numbers in paragraphs 2-4 marked as bold." & @CRLF & "Text inserted before 'line 3'.")

### Example 4

    #include "Extras\HelpFileInternals.au3"

    #include <MsgBoxConstants.au3>
    #include <Word.au3>

    ; Create application object
    Local $oWord = _Word_Create()
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error creating the Word application object." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    ; Open test document read-only
    Local $oDoc = _Word_DocOpen($oWord, _Extras_PathFull("Test.doc"), Default, Default, True)
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error opening '.\Extras\Test.doc'." & @CRLF & "@error = " & @error & ", @extended = " & @extended)

    ; Replace paragraph control character with paragraph + text + paragraph.
    ; Only change first occurence.
    Local $oRangeFound
    $oRangeFound = _Word_DocFind($oDoc, "^p")
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error locating paragraph control character in the document." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    $oRangeFound.InsertAfter("[New Line] ")
    If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", _
            "Error inserting text after the paragraph control character in the document." & @CRLF & "@error = " & @error & _
            ", @extended = " & @extended)
    MsgBox($MB_SYSTEMMODAL, "Word UDF: _Word_DocFind Example", "Paragraph control character successfully replaced." & @CRLF & _
            "Text inserted in paragraph 2.")