# Class GcPdfSearcher

PDF document searcher. Generates asynchronous search results (see search method). The GcPdfSearcher API was designed to be used internally with Search Panel UI.

#### Hierarchy

- GcPdfSearcher

#### Implements

- IPdfSearcher

#####
Index

### Methods

_calculatePhraseMatch
_extractText
_isEntireWord
_prepareMatches
applyHighlight
cancel
createHighlightFromTextSegment
fetchPageContent
fetchPageContentLineEndings
fetchPageTextRects
getContentSnippet
hashSearchResultId
highlight
isResultSelected
nextSearchResult
resetResults
search
toggle
updateAllPages

### Accessors

_query
highlightAll
selectedSearchResult
selectedSearchResultIndex
state
totalResultsCount
totalResultsCountPromise

## Methods

### _calculatePhraseMatch

- _calculatePhraseMatch(query: string, pageContentsEndings: { [x: number]: boolean }, pageContent: string, entireWord: boolean, startsWith: boolean, endsWith: boolean, wildcards: boolean): { matches: number[]; matchesLength: number[] }

- Calculates the phrase matches in the given page content based on the specified query and matching options.

  ### Returns

  An object containing the matches and their lengths.

  ### Returns

  matches - An array of character indices (character indices) on the page where matches were found.

  ### Returns

  matchesLength - An array of lengths for each matched text.

  #### Parameters

  - ##### query: string

    The query string to search for.

  - ##### pageContentsEndings: { [x: number]: boolean }

    An object representing the line endings on the page, where keys are character indices and values indicate line endings.

    - ##### [x: number]: boolean

  - ##### pageContent: string

    The content of the page.

  - ##### entireWord: boolean

    Whether to match the entire word only.

  - ##### startsWith: boolean

    Whether the query should match phrases that start with the query string.

  - ##### endsWith: boolean

    Whether the query should match phrases that end with the query string.

  - ##### wildcards: boolean

    Whether the query allows wildcards for matching.

  #### Returns { matches: number[]; matchesLength: number[] }

  - ##### matches: number[]

  - ##### matchesLength: number[]

### _extractText

- _extractText(): void

- Extract all text from pdf document once.

  #### Returns void

### _isEntireWord

- _isEntireWord(content: any, lineEndings: { [x: number]: boolean }, startIdx: any, length: any): boolean

- Determine if the search query constitutes a "whole word", by comparing the first/last character type with the preceding/following character type.

  #### Parameters

  - ##### content: any

  - ##### lineEndings: { [x: number]: boolean }

    - ##### [x: number]: boolean

  - ##### startIdx: any

  - ##### length: any

  #### Returns boolean

### _prepareMatches

- _prepareMatches(matchesWithLength: any, matches: any, matchesLength: any): void

- Helper for multi-term search that fills the `matchesWithLength` array and handles cases where one search term includes another search term (for example, "tamed tame" or "this is"). It looks for intersecting terms in the `matches` and keeps elements with a longer match length.

  #### Parameters

  - ##### matchesWithLength: any

  - ##### matches: any

  - ##### matchesLength: any

  #### Returns void

### applyHighlight

- applyHighlight(): void

- Render highlight for the current search result.

  #### Returns void

### cancel

- cancel(): void

- Cancel search task.

  ### Example

      // Open the document, find the text 'wildlife' and highlight the first result:
      async function loadPdfViewer(selector) {
           var viewer = new GcPdfViewer(selector, { restoreViewStateOnLoad: false });
           viewer.addDefaultPanels();
           var afterOpenPromise = new Promise((resolve)=>{ viewer.onAfterOpen.register(()=>{ resolve(); }); });
           await viewer.open('wetlands.pdf');
           await afterOpenPromise;
           var findOptions = { Text: 'wildlife' };
           var searchIterator = await viewer.searcher.search(findOptions);
           var searchResult = await searchIterator.next();
        viewer.searcher.cancel();
        viewer.searcher.highlight(searchResult.value);
      }
      loadPdfViewer('#root');

  #### Returns void

### createHighlightFromTextSegment

- createHighlightFromTextSegment(pageIndex: number, startCharIndex: number, endCharIndex: number, args?: { borderColor?: string; borderWidth?: number; color?: string; paintHandler?: any }): Promise<null | ICustomHighlight>

- Highlights a specified portion of text on a given page.

  ### Returns

  A promise that resolves to `true` if the text was successfully highlighted, otherwise `false`.

  ### Example

      // Highlight the text from character 10 to character 20 on the first page with custom highlight colors.
      viewer.highlightTextSegment(0, 10, 20, {
          color: 'rgba(173, 216, 230, 0.5)', // semi-transparent light blue
          borderColor: 'blue', // named color for the border
          borderWidth: 4, // custom border width
          clearPrevious: true
      });

  #### Parameters

  - ##### pageIndex: number

    The index of the page where the text is located (0-based).

  - ##### startCharIndex: number

    The starting character index (0-based) of the text segment to highlight.

  - ##### endCharIndex: number

    The ending character index (0-based) of the text segment to highlight. The character at this index will be excluded from the highlight.

  - ##### `Optional` args: { borderColor?: string; borderWidth?: number; color?: string; paintHandler?: any }

    Optional parameters to customize the highlight, such as color, border color, and width.

    - ##### `Optional` borderColor?: string

    - ##### `Optional` borderWidth?: number

      The width of the highlight border in pixels (default is 2 pixels).

    - ##### `Optional` color?: string

    - ##### `Optional` paintHandler?: any

      A custom function for handling the painting of the highlight (optional).

  #### Returns Promise<null | ICustomHighlight>

### fetchPageContent

- fetchPageContent(pageIndex: number): Promise<string>

- Retrieves the content of a specific page.

  ### Returns

  The content of the specified page.

  #### Parameters

  - ##### pageIndex: number

    The index of the page.

  #### Returns Promise<string>

### fetchPageContentLineEndings

- fetchPageContentLineEndings(pageIndex: number): Promise<{ [x: number]: boolean }>

- Retrieves the line endings of the content of a specific page.

  ### Returns

  The line endings of the content of the specified page.

  #### Parameters

  - ##### pageIndex: number

    The index of the page.

  #### Returns Promise<{ [x: number]: boolean }>

### fetchPageTextRects

- fetchPageTextRects(pageIndex: number): Promise<{ items: IGcTextRect[]; styles: any[] }>

- Retrieves the text rectangles and styles of a specific page.

  ### Returns

  The text rectangles and styles of the specified page.

  #### Parameters

  - ##### pageIndex: number

    The index of the page.

  #### Returns Promise<{ items: IGcTextRect[]; styles: any[] }>

### getContentSnippet

- getContentSnippet(startInd: number, endInd: number, pageContent: string, pageContentsEndings: { [x: number]: boolean }, fillLineEndingsWithSpaces??: boolean): string

- Extracts a substring from `pageContent` between `startInd` and `endInd`, and optionally fills line endings with spaces based on `pageContentsEndings` mapping.

  ### Returns

  The substring with optional spaces inserted at line breaks.

  #### Parameters

  - ##### startInd: number

    The start index of the substring in `pageContent`.

  - ##### endInd: number

    The end index of the substring in `pageContent`.

  - ##### pageContent: string

    The full content of the page from which the substring is extracted.

  - ##### pageContentsEndings: { [x: number]: boolean }

    A mapping indicating where line endings occur.

    - ##### [x: number]: boolean

  - ##### `Optional` fillLineEndingsWithSpaces: boolean = true

    Whether to fill line endings with spaces if they don't already exist.

  #### Returns string

### hashSearchResultId

- hashSearchResultId(searchResult: SearchResult): string

- Generates a unique hash ID for the given search result.

  ### Returns

  A unique hash ID based on the properties of the search result.

  #### Parameters

  - ##### searchResult: SearchResult

    The search result object to generate a hash ID for.

  #### Returns string

### highlight

- highlight(searchResult: null | SearchResult, pageIndex?: number): Promise<void>

- Navigates to a page containing the result and highlights found text.

  ### Example

      // Open the document, find the text 'wildlife' and highlight the first result:
      async function loadPdfViewer(selector) {
           var viewer = new GcPdfViewer(selector, { restoreViewStateOnLoad: false });
           viewer.addDefaultPanels();
           var afterOpenPromise = new Promise((resolve)=>{ viewer.onAfterOpen.register(()=>{ resolve(); }); });
           await viewer.open('wetlands.pdf');
           await afterOpenPromise;
           var findOptions = { Text: 'wildlife' };
           var searchIterator = await viewer.searcher.search(findOptions);
           var searchResult = await searchIterator.next();
        viewer.searcher.cancel();
        viewer.searcher.highlight(searchResult.value);
      }
      loadPdfViewer('#root');

  #### Parameters

  - ##### searchResult: null | SearchResult

  - ##### `Optional` pageIndex: number

  #### Returns Promise<void>

### isResultSelected

- isResultSelected(result: SearchResult): boolean

- Checks whether a specific search result is currently selected.

  ### Returns

  A boolean indicating whether the provided search result is currently selected.

  #### Parameters

  - ##### result: SearchResult

    The search result to be checked for selection.

  #### Returns boolean

### nextSearchResult

- nextSearchResult(result: SearchResult, cancellation: any): Promise<SearchResult>

- Issues the next search result, primarily used internally by the PDF Searcher.

  ### Returns

  A Promise that resolves with the processed search result.

  #### Parameters

  - ##### result: SearchResult

    The search result to be processed.

  - ##### cancellation: any

    The cancellation token to handle the possibility of cancellation.

  #### Returns Promise<SearchResult>

### resetResults

- resetResults(): void

- Clear search results. This method must be called when the SearchPanel is closed.

  #### Returns void

### search

- search(options: FindOptions): AsyncIterableIterator<SearchResult>

- Asynchronously generates search results based on the provided search options.

  ### Example

       // Highlight all search results without opening SearchPanel.
       const searchIterator = viewer.searcher.search({ Text: "test", MatchCase: true, HighlightAll: true });
       searchIterator.next();
       searcher.applyHighlight();

  ### Example

       // Iterate all search results
       const searcher = viewer.searcher;
       var searchResults = [];
       const searchIterator = searcher.search({ Text: textToSearch, MatchCase: true });
       var searchResult = await searchIterator.next();
       if (searchResult.value)
           searcher.highlight(searchResult.value)
       while (searchResult.value && !searchResult.done) {
           const searchResultValue = searchResult.value;
           searchResults.push(`index: ${searchResultValue.ItemIndex}, text: ${searchResultValue.DisplayText}, pageIndex: ${searchResultValue.PageIndex}`);
           searchResult = await searchIterator.next();
       }
       console.log("Search results: " + (searchResults.length ? searchResults.join("; ") : "No search results"));

  ### Example

      // Open the document, find the text 'wildlife' and highlight the first result:
      async function loadPdfViewer(selector) {
           var viewer = new DsPdfViewer(selector, { restoreViewStateOnLoad: false });
           viewer.addDefaultPanels();
           var afterOpenPromise = new Promise((resolve)=>{ viewer.onAfterOpen.register(()=>{ resolve(); }); });
           await viewer.open('wetlands.pdf');
           await afterOpenPromise;
           var findOptions = { Text: 'wildlife' };
           var searchIterator = await viewer.searcher.search(findOptions);
           var searchResult = await searchIterator.next();
        viewer.searcher.cancel();
        viewer.searcher.highlight(searchResult.value);
      }
      loadPdfViewer('#root');

  ### Example

  // Open the document, find the text 'wildlife' and print search results to the console:

       async function loadPdfViewer(selector) {
           var viewer = new DsPdfViewer(selector);
            viewer.addDefaultPanels();
            await viewer.open('wetlands.pdf');
            await (new Promise((resolve)=>{
                viewer.onAfterOpen.register(()=>{
                    resolve();
                });
            }));
            var findOptions = {
                Text: 'wildlife',
                MatchCase: true,
                WholeWord: true,
                StartsWith: false,
                EndsWith: false,
                Wildcards: false,
                Proximity: false,
                SearchBackward: false,
                HighlightAll: true
            };
            var searcher = viewer.searcher;
            var searchIterator = await searcher.search(findOptions);
            var resultsCount = 0;
            var searchResult;
            do {
                searchResult = await searchIterator.next();
                if (searchResult.value) {
                    // this could be either result or progress message (ItemIndex < 0)
                    if(searchResult.value.ItemIndex >= 0) {
                        console.log('next search result:');
                        console.log(searchResult.value);
                        resultsCount++;
                    } else {
                        const pageCount = _doc.pageCount.totalPageCount || _doc.pageCount.renderedSoFar;
                        console.log('search progress, page index is ' + searchResult.value.PageIndex);
                    }
                }
                else {
                    console.log("Search completed");
                    break;
                }
            }
            while(!searchResult.done);
            console.log('Total results count is ' + resultsCount);
       }

  ### Returns

  An asynchronous iterable iterator that yields search results.

  #### Parameters

  - ##### options: FindOptions

    Search options to customize the search.

  #### Returns AsyncIterableIterator<SearchResult>

### toggle

- toggle(forceExpand??: boolean, replaceMode??: boolean): void

- Toggles the visibility of the Search UI.

  #### Parameters

  - ##### `Optional` forceExpand: boolean = true

    Indicates whether to force expanding the Search UI. Default is true.

  - ##### `Optional` replaceMode: boolean = false

    Enables the replace mode in the Search UI. Default is false.

  #### Returns void

  Implementation of IPdfSearcher.toggle

### updateAllPages

- updateAllPages(): void

- Repaint highlight for visible pages.

  #### Returns void

## Accessors

### _query

- get _query(): string

- ### Returns

  The (current) normalized search query.

  #### Returns string

### highlightAll

- get highlightAll(): boolean

- Gets highlightAll option.

  #### Returns boolean

- set highlightAll(checked: boolean): void

- Sets highlightAll option.

  #### Parameters

  - ##### checked: boolean

  #### Returns void

### selectedSearchResult

- get selectedSearchResult(): undefined | SearchResult

- Gets selected search result.

  #### Returns undefined | SearchResult

### selectedSearchResultIndex

- get selectedSearchResultIndex(): number

- Gets selected search result index. Returns -1 if nothing is selected.

  #### Returns number

### state

- get state(): PdfSearcherOptions

- Retrieves non-empty searcher options.

  ### Returns

  The current state of the PDF searcher options, ensuring that it is a valid object.

  #### Returns PdfSearcherOptions

### totalResultsCount

- get totalResultsCount(): number

- Gets total search results count.

  #### Returns number

### totalResultsCountPromise

- get totalResultsCountPromise(): null | Promise<number>

- Gets total search results count promise.

  #### Returns null | Promise<number>