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

#include <qtextboundaryfinder.h>

Public Types
enum	BoundaryReason { NotAtBoundary = 0, StartWord = 1, EndWord = 2 }

enum	BoundaryType { Grapheme, Word, Line, Sentence }

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

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

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

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

int	position () const
	Returns the current position of the QTextBoundaryFinder. More...

	QTextBoundaryFinder ()
	Constructs an invalid QTextBoundaryFinder object. More...

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

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

	QTextBoundaryFinder (BoundaryType type, const QChar chars, int length, unsigned char buffer=0, int bufferSize=0)
	Creates a QTextBoundaryFinder object of type operating on chars with length. More...

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

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

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

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

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

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

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

	~QTextBoundaryFinder ()
	Destructs the QTextBoundaryFinder object. More...

Properties
const QChar *	chars

QTextBoundaryFinderPrivate *	d

uint	freePrivate: 1

int	length

int	pos

QString	s

BoundaryType	t

uint	unused: 31

Detailed Description

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

Since: 4.4

Note: This class or function is reentrant.

QTextBoundaryFinder allows to find Unicode text boundaries in a string, similar to the Unicode text boundary specification (see http://www.unicode.org/reports/tr29/tr29-11.html).

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.

Word boundaries are there to locate the start and end of what a language considers to be a word.

Line break boundaries give possible places where a line break might happen and sentence boundaries will show the beginning and end of whole sentences.

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 56 of file qtextboundaryfinder.h.

Enumerations

◆ BoundaryReason

enum QTextBoundaryFinder::BoundaryReason

NotAtBoundary The boundary finder is not at a boundary position.
StartWord The boundary finder is at the start of a word.
EndWord The boundary finder is at the end of a word.

Enumerator
NotAtBoundary
StartWord
EndWord

Definition at line 71 of file qtextboundaryfinder.h.

                         {
         NotAtBoundary = 0,
         StartWord = 1,
         EndWord = 2
         //Hyphen
     };

◆ BoundaryType

enum QTextBoundaryFinder::BoundaryType

Grapheme Finds a grapheme which is the smallest boundary. It including letters, punctation marks, numerals and more.
Word Finds a word.
Line Finds possible positions for breaking the text into multiple lines.
Sentence Finds sentence boundaries. These include periods, question marks etc.

Enumerator
Grapheme
Word
Line
Sentence

Definition at line 64 of file qtextboundaryfinder.h.

                       {
         Grapheme,
         Word,
         Line,
         Sentence
     };

Constructors and Destructors

◆ QTextBoundaryFinder() [1/4]

QTextBoundaryFinder::QTextBoundaryFinder ( )

Constructs an invalid QTextBoundaryFinder object.

Definition at line 167 of file qtextboundaryfinder.cpp.

     : t(Grapheme)
     , chars(0)
     , length(0)
     , freePrivate(true)
     , d(0)
 {
 }

◆ QTextBoundaryFinder() [2/4]

QTextBoundaryFinder::QTextBoundaryFinder ( const QTextBoundaryFinder & other )

Copies the QTextBoundaryFinder object, other.

Definition at line 179 of file qtextboundaryfinder.cpp.

     : t(other.t)
     , s(other.s)
     , chars(other.chars)
     , length(other.length)
     , pos(other.pos)
     , freePrivate(true)
 {
     d = (QTextBoundaryFinderPrivate *) malloc(length*sizeof(HB_CharAttributes));
     Q_CHECK_PTR(d);
     memcpy(d, other.d, length*sizeof(HB_CharAttributes));
 }

◆ ~QTextBoundaryFinder()

QTextBoundaryFinder::~QTextBoundaryFinder ( )

Destructs the QTextBoundaryFinder object.

Definition at line 219 of file qtextboundaryfinder.cpp.

 {
     if (freePrivate)
         free(d);
 }

◆ QTextBoundaryFinder() [3/4]

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

Creates a QTextBoundaryFinder object of type operating on string.

Definition at line 228 of file qtextboundaryfinder.cpp.

     : t(type)
     , s(string)
     , chars(string.unicode())
     , length(string.length())
     , pos(0)
     , freePrivate(true)
 {
     d = (QTextBoundaryFinderPrivate *) malloc(length*sizeof(HB_CharAttributes));
     Q_CHECK_PTR(d);
     init(t, chars, length, d->attributes);
 }

◆ QTextBoundaryFinder() [4/4]

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

Creates a QTextBoundaryFinder object of type operating on chars with length.

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, it will use this instead of allocating its own buffer.

Warning: QTextBoundaryFinder does not create a copy of chars. 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 254 of file qtextboundaryfinder.cpp.

     : t(type)
     , chars(chars)
     , length(length)
     , pos(0)
 {
     if (buffer && (uint)bufferSize >= length*sizeof(HB_CharAttributes)) {
         d = (QTextBoundaryFinderPrivate *)buffer;
         freePrivate = false;
     } else {
         d = (QTextBoundaryFinderPrivate *) malloc(length*sizeof(HB_CharAttributes));
         Q_CHECK_PTR(d);
         freePrivate = true;
     }
     init(t, chars, length, d->attributes);
 }

Functions

◆ 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 458 of file qtextboundaryfinder.cpp.

Referenced by QDeclarativeTextInput::moveCursorSelection().

 {
     if (!d)
         return NotAtBoundary;
     if (! isAtBoundary())
         return NotAtBoundary;
     if (pos == 0) {
         if (d->attributes[pos].whiteSpace)
             return NotAtBoundary;
         return StartWord;
     }
     if (pos == length) {
         if (d->attributes[length-1].whiteSpace)
             return NotAtBoundary;
         return EndWord;
     }
 
     const bool nextIsSpace = d->attributes[pos].whiteSpace;
     const bool prevIsSpace = d->attributes[pos - 1].whiteSpace;
 
     if (prevIsSpace && !nextIsSpace)
         return StartWord;
     else if (!prevIsSpace && nextIsSpace)
         return EndWord;
     else if (!prevIsSpace && !nextIsSpace)
         return BoundaryReasons(StartWord | EndWord);
     else
         return NotAtBoundary;
 }

◆ isAtBoundary()

bool QTextBoundaryFinder::isAtBoundary ( ) const

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

Definition at line 434 of file qtextboundaryfinder.cpp.

Referenced by boundaryReasons(), qTextAtOffsetFromString(), and qTextBeforeOffsetFromString().

 {
     if (!d || pos < 0)
         return false;
 
     if (pos == length)
         return true;
 
     switch(t) {
     case Grapheme:
         return d->attributes[pos].charStop;
     case Word:
         return d->attributes[pos].wordBoundary;
     case Line:
         return (pos > 0) ? d->attributes[pos-1].lineBreakType >= HB_Break : true;
     case Sentence:
         return d->attributes[pos].sentenceBoundary;
     }
     return false;
 }

◆ 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 82 of file qtextboundaryfinder.h.

82 { return d; }

QTextBoundaryFinder::d

QTextBoundaryFinderPrivate * d

Definition: qtextboundaryfinder.h:106

◆ operator=()

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

Assigns the object, other, to another QTextBoundaryFinder object.

Definition at line 195 of file qtextboundaryfinder.cpp.

 {
     if (&other == this)
         return *this;
 
     t = other.t;
     s = other.s;
     chars = other.chars;
     length = other.length;
     pos = other.pos;
 
     QTextBoundaryFinderPrivate *newD = (QTextBoundaryFinderPrivate *)
         realloc(freePrivate ? d : 0, length*sizeof(HB_CharAttributes));
     Q_CHECK_PTR(newD);
     freePrivate = true;
     d = newD;
     memcpy(d, other.d, length*sizeof(HB_CharAttributes));
 
     return *this;
 }

◆ position()

int 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 299 of file qtextboundaryfinder.cpp.

Referenced by QDeclarativeTextInput::moveCursorSelection(), qTextAfterOffsetFromString(), qTextAtOffsetFromString(), and qTextBeforeOffsetFromString().

 {
     return pos;
 }

◆ setPosition()

void QTextBoundaryFinder::setPosition ( int 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.

See also: position()

Definition at line 313 of file qtextboundaryfinder.cpp.

Referenced by QDeclarativeTextInput::moveCursorSelection(), qTextAfterOffsetFromString(), qTextAtOffsetFromString(), and qTextBeforeOffsetFromString().

 {
     pos = qBound(0, position, length);
 }

◆ string()

QString QTextBoundaryFinder::string ( ) const

Returns the string the QTextBoundaryFinder object operates on.

Definition at line 338 of file qtextboundaryfinder.cpp.

 {
     if (chars == s.unicode() && length == s.length())
         return s;
     return QString(chars, length);
 }

◆ toEnd()

void QTextBoundaryFinder::toEnd ( )

Moves the finder to the end of the string.

This is equivalent to setPosition(string.length()).

See also: setPosition(), position()

Definition at line 286 of file qtextboundaryfinder.cpp.

 {
     pos = length;
 }

◆ toNextBoundary()

int QTextBoundaryFinder::toNextBoundary ( )

Moves the QTextBoundaryFinder to the next boundary position and returns that position.

Returns -1 if there is no next boundary.

Definition at line 351 of file qtextboundaryfinder.cpp.

Referenced by QDeclarativeTextInput::moveCursorSelection(), qTextAfterOffsetFromString(), qTextAtOffsetFromString(), and qTextBeforeOffsetFromString().

 {
     if (!d) {
         pos = -1;
         return pos;
     }
 
     if (pos < 0 || pos >= length) {
         pos = -1;
         return pos;
     }
     ++pos;
     if (pos == length)
         return pos;
     
     switch(t) {
     case Grapheme:
         while (pos < length && !d->attributes[pos].charStop)
             ++pos;
         break;
     case Word:
         while (pos < length && !d->attributes[pos].wordBoundary)
             ++pos;
         break;
     case Sentence:
         while (pos < length && !d->attributes[pos].sentenceBoundary)
             ++pos;
         break;
     case Line:
         Q_ASSERT(pos);
         while (pos < length && d->attributes[pos-1].lineBreakType < HB_Break)
             ++pos;
         break;
     }
 
     return pos;
 }

◆ toPreviousBoundary()

int QTextBoundaryFinder::toPreviousBoundary ( )

Moves the QTextBoundaryFinder to the previous boundary position and returns that position.

Returns -1 if there is no previous boundary.

Definition at line 394 of file qtextboundaryfinder.cpp.

Referenced by QDeclarativeTextInput::moveCursorSelection(), qTextAtOffsetFromString(), and qTextBeforeOffsetFromString().

 {
     if (!d) {
         pos = -1;
         return pos;
     }
 
     if (pos <= 0 || pos > length) {
         pos = -1;
         return pos;
     }
     --pos;
     if (pos == 0)
         return pos;
 
     switch(t) {
     case Grapheme:
         while (pos > 0 && !d->attributes[pos].charStop)
             --pos;
         break;
     case Word:
         while (pos > 0 && !d->attributes[pos].wordBoundary)
             --pos;
         break;
     case Sentence:
         while (pos > 0 && !d->attributes[pos].sentenceBoundary)
             --pos;
         break;
     case Line:
         while (pos > 0 && d->attributes[pos-1].lineBreakType < HB_Break)
             --pos;
         break;
     }
 
     return pos;
 }