Class PDFNet.TextSearch
PDFNet.TextSearch
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
TextSearch searches through a PDF document for a user-given search pattern.
|
| Method Attributes | Method Name and Description |
|---|---|
|
begin({PDFDoc}, {string}, {number}, {number}, {number})
Initialize for search process.
|
|
| <static> |
PDFNet.TextSearch.create()
Constructor and destructor.
|
|
destroy()
Frees the native memory of the object.
|
|
|
Retrieve the number of the current page that is searched in.
|
|
|
getMode()
Retrieve the current search mode.
|
|
|
run()
Runs a search on the document for a certain string.
|
|
|
setMode(mode)
set the current search mode.
|
|
|
setPattern(pattern)
Set the current search pattern.
|
|
|
setRightToLeftLanguage(flag)
Tells TextSearch that language is from right to left.
|
Class Detail
PDFNet.TextSearch(id)
TextSearch searches through a PDF document for a user-given search pattern.
The current implementation supports both verbatim search and the search
using regular expressions, whose detailed syntax can be found at:
http://www.boost.org/doc/libs/release/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html
TextSearch also provides users with several useful search modes and extra
information besides the found string that matches the pattern. TextSearch
can either keep running until a matched string is found or be set to return
periodically in order for the caller to perform any necessary updates
(e.g., UI updates). It is also worth mentioning that the search modes can be
changed on the fly while searching through a document.
Possible use case scenarios for TextSearch include:
- Guide users of a PDF viewer (e.g. implemented by PDFViewCtrl) to places
where they are intersted in;
- Find interested PDF documents which contain certain patterns;
- Extract interested information (e.g., credit card numbers) from a set of files;
- Extract Highlight information (refer to the Highlights class for details) from
files for external use.
Note:
- Since hyphens ('-') are frequently used in PDF documents to concatenate the two
broken pieces of a word at the end of a line, for example
"TextSearch is powerful for finding patterns in PDF files; yes, it is really pow-
erful."
a search for "powerful" should return both instances. However, not all end-of-line
hyphens are hyphens added to connect a broken word; some of them could be "real"
hyphens. In addition, an input search pattern may also contain hyphens that complicate
the situation. To tackle this problem, the following conventions are adopted:
a)When in the verbatim search mode and the pattern contains no hyphen, a matching
string is returned if it is exactly the same or it contains end-of-line
or start-of-line hyphens. For example, as mentioned above, a search for "powerful"
would return both instances.
b)When in verbatim search mode and the pattern contains one or multiple hyphens, a
matching string is returned only if the string matches the pattern exactly. For
example, a search for "pow-erful" will only return the second instance, and a search
for "power-ful" will return nothing.
c)When searching using regular expressions, hyphens are not taken care implicitly.
Users should take care of it themselves. For example, in order to find both the
"powerful" instances, the input pattern can be "pow-{0,1}erful".
A sample use case (in C++):
- Parameters:
- id
Method Detail
{boolean}
begin({PDFDoc}, {string}, {number}, {number}, {number})
Initialize for search process. This should be called before starting the actual search
with method Run().
- Parameters:
- {PDFDoc [Y]} {PDFDoc}
- doc the PDF document to search in.
- {string} {string}
- pattern the pattern to search for. When regular expression is used, it contains the expression, and in verbatim mode, it is the exact string to search for.
- {number} {number}
- mode the mode of the search process.
- {number} {number}
- [start_page=-1] start_page the start page of the page range to search in. The default value is -1 indicating the range starts from the first page.
- {number} {number}
- [end_page=-1] end_page the end page of the page range to search in. The default value is -1 indicating the range ends at the last page.
- Returns:
- {boolean} A promise that resolves to true if the initialization has succeeded.
<static>
{TextSearch}
PDFNet.TextSearch.create()
Constructor and destructor.
- Returns:
- {TextSearch} A promise that resolves to an object of type: "TextSearch" (generated documentation)
destroy()
Frees the native memory of the object.
{number}
getCurrentPage()
Retrieve the number of the current page that is searched in.
If the returned value is -1, it indicates the search process has not been initialized
(e.g., Begin() is not called yet); if the returned value is 0, it indicates the search
process has finished, and if the returned value is positive, it is a valid page number.
- Returns:
- {number} A promise that resolves to the current page number.
{number}
getMode()
Retrieve the current search mode.
- Returns:
- {number} A promise that resolves to the current search mode.
{custom_obj}
run()
Runs a search on the document for a certain string. Make sure to call
TextSearch.begin(doc, pattern, mode) with the proper parameters
before calling TextSearch.run()
The resolved object that TextSearch.run() returns contains the following objects:
page_num - The number of the page with the match
out_str - The string that matches the search parameter
ambient_str - The ambient string of the found string (computed only if e_ambient_string is set)
highlights - The Highlights info associated with the match (computed only if 'e_highlight' is set)
code - Number representing the status of the search.
0 - e_done, reached end of document.
1 - e_page, reached end of page. (if set to return by specifying mode 'e_page_stop')
2 - e_found, found an instance matching the search pattern
- Returns:
- {custom_obj} A promise that resolves to an object containing the page_num, out_str ambient_str, highlights, and result code.
setMode(mode)
set the current search mode. For example, the following code turns on the regular
expressions:
TextSearch ts;
...
TextSearch::Mode mode = ts.GetMode();
mode |= TextSearch::e_reg_expression;
ts.SetMode(mode);
...
- Parameters:
- {number} mode
- the search mode to set.
{boolean}
setPattern(pattern)
Set the current search pattern. Note that it is not necessary to call this method since
the search pattern is already set when calling the Begin() method. This method is provided
for users to change the search pattern while searching through a document.
- Parameters:
- {string} pattern
- the search pattern to set.
- Returns:
- {boolean} A promise that resolves to true if the setting has succeeded.
setRightToLeftLanguage(flag)
Tells TextSearch that language is from right to left.
- Parameters:
- {boolean} flag
- Set to true if the language is right to left.