This function may be used to extract the brief annotation from a long description text to be placed in a summary table.
The function returns the first sentence of the specified text.
The sentence boundary is found using a default instance of java.text.BreakIterator
class (returned by its getSentenceInstance()
method).
The particular implementation depends on the current locale.
However, for most locales, it typically assumes that sentences end
with dots ('.'
).
Parameters:
text
The full text from which the first sentence is to be extracted.
recognizeHTML
When this parameter istrue
, the passed string is assumed to be as a piece of HTML (that is, it may contain HTML tags and entities).In that case, the function parses the HTML markup and finds the first sentence boundary according to the pure text extracted from the initial string (i.e. without HTML tags).
In addition, it stops on any HTML flow-breaking tag (such as <p> or <hr>), except heading tags <h1>...<h6> and <br>, when there is some non-blank text preceding it.
Note that processing of HTML markup will take more resources!
When the parameter is
false
, the passed string will be treated simply as a plain text.Note: When this parameter is omitted, its value is assumed to be
true
.
reproduceHTML
This parameter controls whether to include the original HTML markup in the returned result string and to encode markup characters in the text.When the parameter is
true
:When the parameter is
- If
recognizeHTML == true
, once the end position of the first sentence is found, the function cuts the rest of the initial string, removes any HTML block tags and adds the end tags corresponding the HTML elements started before and not closed yet. Any HTML markup characters (except quotes) in the text will be encoded back into the corresponding HTML entities.- Otherwise (
recognizeHTML == false
), the initial string will be treated as a plain text, the first sentence extracted and all HTML markup characters (except quotes) in the result string will be encoded into the corresponding HTML entities.false
:Note: When this parameter is omitted, its value is assumed to be equal to the value of
- If
recognizeHTML == true
, only the pure text of the extracted first sentence will be returned. All HTML tags will be removed and all HTML entities will be converted to the corresponding characters (e.g.'<'
will be converted to'<'
)- Otherwise (
recognizeHTML == false
), the initial string will be treated as a plain text, the first sentence extracted and returned as is (without any encoding).recognizeHTML
parameter.
Examples:
Let's assume the parameter text
contains the following string:
<p><i>First sentence & more.</i> Blah-blah
will returnfirstSentence(text)
firstSentence(text, true)
firstSentence(text, true, true)
<i>First sentence & more.</i>
The call
firstSentence(text, true, false)
returns
First sentence & more.
The call
firstSentence(text, false, true)
returns
<p><i>First sentence &amp; more.
The calls
returnsfirstSentence(text, false)
firstSentence(text, false, false)
<p><i>First sentence & more.