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
recognizeHTML
true
, 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
When the parameter is true
:
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.
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
:
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 '<'
)
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.
Let's assume the parameter text
contains the following string:
<p><i>First sentence & more.</i> Blah-blah
firstSentence(text)
firstSentence(text, true)
firstSentence(text, true, true)
<i>First sentence & more.</i>
firstSentence(text, true, false)
First sentence & more.
firstSentence(text, false, true)
<p><i>First sentence &amp; more.
firstSentence(text, false)
firstSentence(text, false, false)
<p><i>First sentence & more.