QTextBoundaryFinder Class

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

Header	`#include <QTextBoundaryFinder>`
CMake	`target_link_libraries(app PRIVATE Nt::Core)`
Module	Nt Core C++ Classes
Since	4.4

List of all members, including inherited members

Public Types

enum	BoundaryType
enum	BoundaryReason
typedef	BoundaryReasons

Public Functions

	QTextBoundaryFinder()
	QTextBoundaryFinder(BoundaryType type, const QString &string)
	QTextBoundaryFinder(BoundaryType type, QStringView string, unsigned char *buffer = nullptr, qsizetype bufferSize = 0)
	QTextBoundaryFinder(BoundaryType type, const QChar *chars, qsizetype length, unsigned char *buffer = nullptr, qsizetype bufferSize = 0)
	QTextBoundaryFinder(const QTextBoundaryFinder &other)
	QTextBoundaryFinder(QTextBoundaryFinder &&other)
QTextBoundaryFinder &	operator=(const QTextBoundaryFinder &other)
QTextBoundaryFinder &	operator=(QTextBoundaryFinder &&other)
	~QTextBoundaryFinder()
bool	isValid() const
BoundaryType	type() const
QString	string() const
void	toStart()
void	toEnd()
qsizetype	position() const
void	setPosition(qsizetype position)
qsizetype	toNextBoundary()
qsizetype	toPreviousBoundary()
bool	isAtBoundary() const
BoundaryReasons	boundaryReasons() const

Detailed Description

A QTextBoundaryFinder finds the positions in a string where a grapheme cluster (a user-perceived character), a word or a sentence starts or ends, or where a line may be broken. Positions are UTF-16 indexes between characters, from 0 to the length of the string.

QTextBoundaryFinder finder(QTextBoundaryFinder::Word, text);
for (qsizetype start = 0, end; (end = finder.toNextBoundary()) != -1; start = end)
    if (finder.boundaryReasons() & QTextBoundaryFinder::EndOfItem)
        words << text.mid(start, end - start);

See also QString.

Differences from Qt

The rules are simplified versions of Unicode Standard Annex #29 (grapheme clusters, words, sentences) and #14 (line breaking), using the general category of each character instead of the dedicated break properties. There is no dictionary-based word breaking for Thai or similar scripts, and ideographs are broken one by one. The optional work buffer of the constructor is ignored.

Member Type Documentation

enum QTextBoundaryFinder::BoundaryReason

Constant	Description
`QTextBoundaryFinder::NotAtBoundary`	The position is not a boundary.
`QTextBoundaryFinder::BreakOpportunity`	The position is a boundary.
`QTextBoundaryFinder::StartOfItem`	An item (a grapheme cluster, word or sentence) starts at the position.
`QTextBoundaryFinder::EndOfItem`	An item ends at the position.
`QTextBoundaryFinder::MandatoryBreak`	A line must be broken at the position.
`QTextBoundaryFinder::SoftHyphen`	A line may be broken at the position after a soft hyphen, which should then be shown as a hyphen.

typedef QTextBoundaryFinder::BoundaryReasons

The BoundaryReasons type is a typedef for QFlags<BoundaryReason>. It stores an OR combination of BoundaryReason values.

enum QTextBoundaryFinder::BoundaryType

Constant	Description
`QTextBoundaryFinder::Grapheme`	Boundaries between user-perceived characters.
`QTextBoundaryFinder::Word`	Boundaries between words and the text between them.
`QTextBoundaryFinder::Sentence`	Boundaries between sentences.
`QTextBoundaryFinder::Line`	Positions where a line may be broken.

Member Function Documentation

QTextBoundaryFinder::QTextBoundaryFinder()

Constructs an invalid finder.

See also isValid().

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

Constructs a finder of boundaries of type in string. The position is at the start of the string.

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

This is an overloaded function.

Constructs a finder of boundaries of type in the text viewed by string. The text is copied. buffer and bufferSize are ignored.

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

This is an overloaded function.

Constructs a finder of boundaries of type in the length characters at chars. The text is copied. buffer and bufferSize are ignored.

QTextBoundaryFinder::QTextBoundaryFinder(const QTextBoundaryFinder &other)

Constructs a copy of other.

QTextBoundaryFinder::QTextBoundaryFinder(QTextBoundaryFinder &&other)

Move-constructs a finder from other, which becomes invalid.

QTextBoundaryFinder::~QTextBoundaryFinder()

Destroys the finder.

BoundaryReasons QTextBoundaryFinder::boundaryReasons() const

Returns the reasons why the current position is a boundary, or NotAtBoundary.

See also isAtBoundary().

bool QTextBoundaryFinder::isAtBoundary() const

Returns true if the current position is a boundary; otherwise returns false.

See also boundaryReasons().

bool QTextBoundaryFinder::isValid() const

Returns true if the finder was constructed with a string; otherwise returns false.

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

Assigns other to this finder and returns a reference to it.

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

Move-assigns other to this finder and returns a reference to it.

qsizetype QTextBoundaryFinder::position() const

Returns the current position, or -1 after moving past the last (or before the first) boundary.

See also setPosition().

void QTextBoundaryFinder::setPosition(qsizetype position)

Sets the current position to position, clamped to the range from 0 to the length of the string.

See also position().

QString QTextBoundaryFinder::string() const

Returns the string the finder works on.

void QTextBoundaryFinder::toEnd()

Moves the finder to the end of the string.

See also toStart().

qsizetype QTextBoundaryFinder::toNextBoundary()

Moves to the next boundary and returns its position. Returns -1, and makes the position -1, if there is none.

See also toPreviousBoundary().

qsizetype QTextBoundaryFinder::toPreviousBoundary()

Moves to the previous boundary and returns its position. Returns -1, and makes the position -1, if there is none.

See also toNextBoundary().

void QTextBoundaryFinder::toStart()

Moves the finder to the start of the string, position 0.

See also toEnd().

BoundaryType QTextBoundaryFinder::type() const

Returns the type of boundaries the finder looks for.