\inmodule QtCore More...

#include <qtextboundaryfinder.h>

Collaboration diagram for QTextBoundaryFinder:

Public Types
enum	BoundaryType { Grapheme , Word , Sentence , Line }
	\value Grapheme Finds a grapheme which is the smallest boundary. More...

enum	BoundaryReason { NotAtBoundary = 0 , BreakOpportunity = 0x1f , StartOfItem = 0x20 , EndOfItem = 0x40 , MandatoryBreak = 0x80 , SoftHyphen = 0x100 }
	\value NotAtBoundary The boundary finder is not at a boundary position. More...

Public Member Functions
	QTextBoundaryFinder ()
	Constructs an invalid QTextBoundaryFinder object.

	QTextBoundaryFinder (const QTextBoundaryFinder &other)
	Copies the QTextBoundaryFinder object, other.

QTextBoundaryFinder &	operator= (const QTextBoundaryFinder &other)
	Assigns the object, other, to another QTextBoundaryFinder object.

	~QTextBoundaryFinder ()
	Destructs the QTextBoundaryFinder object.

	QTextBoundaryFinder (BoundaryType type, const QString &string)
	Creates a QTextBoundaryFinder object of type operating on string.

	QTextBoundaryFinder (BoundaryType type, const QChar chars, qsizetype length, unsigned char buffer=nullptr, qsizetype bufferSize=0)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.The same as QTextBoundaryFinder(type, QStringView(chars, length), buffer, bufferSize).

	QTextBoundaryFinder (BoundaryType type, QStringView str, unsigned char *buffer=nullptr, qsizetype bufferSize=0)
	Creates a QTextBoundaryFinder object of type operating on string.

bool	isValid () const
	Returns `true` if the text boundary finder is valid; otherwise returns `false`.

BoundaryType	type () const
	Returns the type of the QTextBoundaryFinder.

QString	string () const
	Returns the string the QTextBoundaryFinder object operates on.

void	toStart ()
	Moves the finder to the start of the string.

void	toEnd ()
	Moves the finder to the end of the string.

qsizetype	position () const
	Returns the current position of the QTextBoundaryFinder.

void	setPosition (qsizetype position)
	Sets the current position of the QTextBoundaryFinder to position.

qsizetype	toNextBoundary ()
	Moves the QTextBoundaryFinder to the next boundary position and returns that position.

qsizetype	toPreviousBoundary ()
	Moves the QTextBoundaryFinder to the previous boundary position and returns that position.

bool	isAtBoundary () const
	Returns `true` if the object's position() is currently at a valid text boundary.

BoundaryReasons	boundaryReasons () const
	Returns the reasons for the boundary finder to have chosen the current position as a boundary.

Detailed Description

\inmodule QtCore

The QTextBoundaryFinder class provides a way of finding Unicode text boundaries in a string.

Since: 4.4

\reentrant

QTextBoundaryFinder allows to find Unicode text boundaries in a string, accordingly to the Unicode text boundary specification (see \l{https://www.unicode.org/reports/tr14/}{Unicode Standard Annex #14} and \l{https://www.unicode.org/reports/tr29/}{Unicode Standard Annex #29}).

QTextBoundaryFinder can operate on a QString in four possible modes depending on the value of BoundaryType.

Units of Unicode characters that make up what the user thinks of as a character or basic unit of the language are here called Grapheme clusters. The two unicode characters 'A' + diaeresis do for example form one grapheme cluster as the user thinks of them as one character, yet it is in this case represented by two unicode code points (see \l{https://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries}).

Word boundaries are there to locate the start and end of what a language considers to be a word (see \l{https://www.unicode.org/reports/tr29/#Word_Boundaries}).

Line break boundaries give possible places where a line break might happen and sentence boundaries will show the beginning and end of whole sentences (see \l{https://www.unicode.org/reports/tr29/#Sentence_Boundaries} and \l{https://www.unicode.org/reports/tr14/}).

The first position in a string is always a valid boundary and refers to the position before the first character. The last position at the length of the string is also valid and refers to the position after the last character.

Definition at line 15 of file qtextboundaryfinder.h.

Member Enumeration Documentation

◆ BoundaryReason

enum QTextBoundaryFinder::BoundaryReason

\value NotAtBoundary The boundary finder is not at a boundary position.

\value BreakOpportunity The boundary finder is at a break opportunity position. Such a break opportunity might also be an item boundary (either StartOfItem, EndOfItem, or combination of both), a mandatory line break, or a soft hyphen. \value [since 5.0] StartOfItem The boundary finder is at the start of a grapheme, a word, a sentence, or a line. \value [since 5.0] EndOfItem The boundary finder is at the end of a grapheme, a word, a sentence, or a line. \value [since 5.0] MandatoryBreak The boundary finder is at the end of line (can occur for a Line boundary type only). \value SoftHyphen The boundary finder is at the soft hyphen (can occur for a Line boundary type only).

Enumerator
NotAtBoundary
BreakOpportunity
StartOfItem
EndOfItem
MandatoryBreak
SoftHyphen

Definition at line 30 of file qtextboundaryfinder.h.

◆ BoundaryType

enum QTextBoundaryFinder::BoundaryType

\value Grapheme Finds a grapheme which is the smallest boundary.

It including letters, punctuation marks, numerals and more. \value Word Finds a word. \value Line Finds possible positions for breaking the text into multiple lines. \value Sentence Finds sentence boundaries. These include periods, question marks etc.

Enumerator
Grapheme
Word
Sentence
Line

Definition at line 23 of file qtextboundaryfinder.h.

Constructor & Destructor Documentation

◆ QTextBoundaryFinder() [1/5]

QTextBoundaryFinder::QTextBoundaryFinder ( )

Constructs an invalid QTextBoundaryFinder object.

Definition at line 103 of file qtextboundaryfinder.cpp.

◆ QTextBoundaryFinder() [2/5]

QTextBoundaryFinder::QTextBoundaryFinder ( const QTextBoundaryFinder & other )

Copies the QTextBoundaryFinder object, other.

Definition at line 111 of file qtextboundaryfinder.cpp.

References other(), Q_ASSERT, Q_CHECK_PTR(), and QStringView::size().

Here is the call graph for this function:

◆ ~QTextBoundaryFinder()

QTextBoundaryFinder::~QTextBoundaryFinder ( )

Destructs the QTextBoundaryFinder object.

Definition at line 162 of file qtextboundaryfinder.cpp.

References Q_UNUSED.

◆ QTextBoundaryFinder() [3/5]

QTextBoundaryFinder::QTextBoundaryFinder	(	BoundaryType	type,
		const QString &	string )

Creates a QTextBoundaryFinder object of type operating on string.

Definition at line 172 of file qtextboundaryfinder.cpp.

References init(), Q_CHECK_PTR(), and QStringView::size().

Here is the call graph for this function:

◆ QTextBoundaryFinder() [4/5]

QTextBoundaryFinder::QTextBoundaryFinder	(	BoundaryType	type,
		const QChar *	chars,
		qsizetype	length,
		unsigned char *	buffer = nullptr,
		qsizetype	bufferSize = 0 )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.The same as QTextBoundaryFinder(type, QStringView(chars, length), buffer, bufferSize).

Definition at line 41 of file qtextboundaryfinder.h.

◆ QTextBoundaryFinder() [5/5]

QTextBoundaryFinder::QTextBoundaryFinder	(	BoundaryType	type,
		QStringView	string,
		unsigned char *	buffer = nullptr,
		qsizetype	bufferSize = 0 )

Creates a QTextBoundaryFinder object of type operating on string.

Since: 6.0

buffer is an optional working buffer of size bufferSize you can pass to the QTextBoundaryFinder. If the buffer is large enough to hold the working data required (bufferSize >= length + 1), it will use this instead of allocating its own buffer.

Warning: QTextBoundaryFinder does not create a copy of string. It is the application programmer's responsibility to ensure the array is allocated for as long as the QTextBoundaryFinder object stays alive. The same applies to buffer.

Definition at line 206 of file qtextboundaryfinder.cpp.

References init(), QStringView::isEmpty(), Q_CHECK_PTR(), and QStringView::size().

Here is the call graph for this function:

Member Function Documentation

◆ boundaryReasons()

QTextBoundaryFinder::BoundaryReasons QTextBoundaryFinder::boundaryReasons ( ) const

Returns the reasons for the boundary finder to have chosen the current position as a boundary.

Definition at line 387 of file qtextboundaryfinder.cpp.

References BreakOpportunity, EndOfItem, Grapheme, QCharAttributes::graphemeBoundary, Line, QCharAttributes::lineBreak, MandatoryBreak, QCharAttributes::mandatoryBreak, NotAtBoundary, Sentence, QCharAttributes::sentenceBoundary, QStringView::size(), SoftHyphen, StartOfItem, Word, QCharAttributes::wordBreak, QCharAttributes::wordEnd, and QCharAttributes::wordStart.

Referenced by QWindowsInputContext::reconvertString().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isAtBoundary()

bool QTextBoundaryFinder::isAtBoundary ( ) const

Returns true if the object's position() is currently at a valid text boundary.

Definition at line 365 of file qtextboundaryfinder.cpp.

References Grapheme, QCharAttributes::graphemeBoundary, Line, QCharAttributes::lineBreak, Sentence, QCharAttributes::sentenceBoundary, QStringView::size(), Word, and QCharAttributes::wordBreak.

Here is the call graph for this function:

◆ isValid()

bool QTextBoundaryFinder::isValid ( ) const

inline

Returns true if the text boundary finder is valid; otherwise returns false.

A default QTextBoundaryFinder is invalid.

Definition at line 46 of file qtextboundaryfinder.h.

◆ operator=()

QTextBoundaryFinder & QTextBoundaryFinder::operator= ( const QTextBoundaryFinder & other )

Assigns the object, other, to another QTextBoundaryFinder object.

Definition at line 129 of file qtextboundaryfinder.cpp.

References other(), Q_ASSERT, Q_CHECK_PTR(), and QStringView::size().

Here is the call graph for this function:

◆ position()

qsizetype QTextBoundaryFinder::position ( ) const

Returns the current position of the QTextBoundaryFinder.

The range is from 0 (the beginning of the string) to the length of the string inclusive.

See also: setPosition()

Definition at line 251 of file qtextboundaryfinder.cpp.

Referenced by QWindowsInputContext::reconvertString(), and setPosition().

Here is the caller graph for this function:

◆ setPosition()

void QTextBoundaryFinder::setPosition ( qsizetype position )

Sets the current position of the QTextBoundaryFinder to position.

If position is out of bounds, it will be bound to only valid positions. In this case, valid positions are from 0 to the length of the string inclusive.