KTextEditor::Cursor

Search for usage in LXR

#include <KTextEditor/Cursor>

Public Member Functions

constexpr Cursor () Q_DECL_NOEXCEPT
 
constexpr Cursor (int line, int column) Q_DECL_NOEXCEPT
 
constexpr bool isValid () const Q_DECL_NOEXCEPT
 
QString toString () const
 
Position

The following functions provide access to, and manipulation of, the cursor's position.

void setPosition (const Cursor &position) Q_DECL_NOEXCEPT
 
void setPosition (int line, int column) Q_DECL_NOEXCEPT
 
constexpr int line () const Q_DECL_NOEXCEPT
 
void setLine (int line) Q_DECL_NOEXCEPT
 
constexpr int column () const Q_DECL_NOEXCEPT
 
void setColumn (int column) Q_DECL_NOEXCEPT
 
constexpr bool atStartOfLine () const Q_DECL_NOEXCEPT
 
constexpr bool atStartOfDocument () const Q_DECL_NOEXCEPT
 
void position (int &line, int &column) const Q_DECL_NOEXCEPT
 

Static Public Member Functions

static Cursor fromString (const QString &str) Q_DECL_NOEXCEPT
 
static Cursor fromString (const QStringRef &str) Q_DECL_NOEXCEPT
 
static Cursor fromString (QStringView str) Q_DECL_NOEXCEPT
 
static constexpr Cursor invalid () Q_DECL_NOEXCEPT
 
static constexpr Cursor start () Q_DECL_NOEXCEPT
 

Friends

constexpr friend bool operator!= (const Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 
constexpr friend Cursor operator+ (const Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 
Cursoroperator+= (Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 
constexpr friend Cursor operator- (const Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 
Cursoroperator-= (Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 
constexpr friend bool operator< (const Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 
QDebug operator<< (QDebug s, const Cursor &cursor)
 
constexpr friend bool operator<= (const Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 
constexpr friend bool operator== (const Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 
constexpr friend bool operator> (const Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 
constexpr friend bool operator>= (const Cursor &c1, const Cursor &c2) Q_DECL_NOEXCEPT
 

Detailed Description

The Cursor represents a position in a Document.

Introduction

A Cursor represents a position in a Document through a tuple of two ints, namely the line() and column(). A Cursor maintains no affiliation with a particular Document, meaning that it remains constant if not changed through the Cursor API.

Important Notes

Working with a cursor, one should be aware of the following notes:

  • Lines and columns start a 0.
  • The Cursor class is designed to be passed by value (only 8 Bytes).
  • Think of cursors as having their position at the start of a character, not in the middle of one.
  • invalid() Cursors are located at (-1, -1). In addition, a Cursor is invalid(), if either its line() and/or its column() is arbitrarily negative, i.e. < 0.
  • All Cursors with line() >= 0 and column() >= 0 are valid. In this case isValid() returns true.
  • A Cursor has a non-virtual destructor. Hence, you cannot derive from Cursor.

Cursor Efficiency

The Cursor consists of just two ints, the line() and the column(). Therefore, a Cursor instance takes 8 Bytes of memory. Further, a Cursor is a non-virtual class, turning it into a primitive old data type (POD). Thus, it can be moved and copied very efficiently.

Additional Concepts

In addition to the Cursor, the KTextEditor API provides advanced concepts:

See also
DocumentCursor, MovingCursor, Range

Definition at line 71 of file cursor.h.

Constructor & Destructor Documentation

constexpr KTextEditor::Cursor::Cursor ( )
inline

The default constructor creates a cursor at position (0, 0).

Definition at line 77 of file cursor.h.

constexpr KTextEditor::Cursor::Cursor ( int  line,
int  column 
)
inline

This constructor creates a cursor initialized with line and column.

Parameters
lineline for cursor
columncolumn for cursor

Definition at line 87 of file cursor.h.

Member Function Documentation

constexpr bool KTextEditor::Cursor::atStartOfDocument ( ) const
inline

Determine if this cursor is located at the start of a document (= at position (0, 0)).

Returns
true if the cursor is situated at the start of the document, false if it isn't.

Definition at line 240 of file cursor.h.

constexpr bool KTextEditor::Cursor::atStartOfLine ( ) const
inline

Determine if this cursor is located at the start of a line (= at column 0).

Returns
true if the cursor is situated at the start of the line, false if it isn't.

Definition at line 231 of file cursor.h.

constexpr int KTextEditor::Cursor::column ( ) const
inline

Retrieve the column on which this cursor is situated.

Returns
column number, where 0 is the first column.

Definition at line 213 of file cursor.h.

static Cursor KTextEditor::Cursor::fromString ( const QString str)
inlinestatic

Returns a Cursor created from the string str containing the format "(line, column)".

In case the string cannot be parsed, Cursor::invalid() is returned.

See also
toString()

Definition at line 138 of file cursor.h.

static Cursor KTextEditor::Cursor::fromString ( const QStringRef str)
static

Returns a Cursor created from the string str containing the format "(line, column)".

In case the string cannot be parsed, Cursor::invalid() is returned.

See also
toString()
static Cursor KTextEditor::Cursor::fromString ( QStringView  str)
static

Returns a Cursor created from the string str containing the format "(line, column)".

In case the string cannot be parsed, Cursor::invalid() is returned.

See also
toString()
static constexpr Cursor KTextEditor::Cursor::invalid ( )
inlinestatic

Returns an invalid cursor.

The returned cursor position is set to (-1, -1).

See also
isValid()

Definition at line 109 of file cursor.h.

constexpr bool KTextEditor::Cursor::isValid ( ) const
inline

Returns whether the current position of this cursor is a valid position (line + column must both be >= 0).

Note
If you want to check, whether a cursor position is a valid text-position, use DocumentCursor::isValidTextPosition(), or Document::isValidTextPosition().

Definition at line 99 of file cursor.h.

constexpr int KTextEditor::Cursor::line ( ) const
inline

Retrieve the line on which this cursor is situated.

Returns
line number, where 0 is the first line.

Definition at line 195 of file cursor.h.

void KTextEditor::Cursor::position ( int &  line,
int &  column 
) const
inline

Get both the line and column of the cursor position.

Parameters
linewill be filled with current cursor line
columnwill be filled with current cursor column

Definition at line 250 of file cursor.h.

void KTextEditor::Cursor::setColumn ( int  column)
inline

Set the cursor column to column.

Parameters
columnnew cursor column

Definition at line 222 of file cursor.h.

void KTextEditor::Cursor::setLine ( int  line)
inline

Set the cursor line to line.

Parameters
linenew cursor line

Definition at line 204 of file cursor.h.

void KTextEditor::Cursor::setPosition ( const Cursor position)
inline

Set the current cursor position to position.

Parameters
positionnew cursor position

Definition at line 171 of file cursor.h.

void KTextEditor::Cursor::setPosition ( int  line,
int  column 
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Set the cursor position to line and column.

Parameters
linenew cursor line
columnnew cursor column

Definition at line 185 of file cursor.h.

static constexpr Cursor KTextEditor::Cursor::start ( )
inlinestatic

Returns a cursor representing the start of any document - i.e., line 0, column 0.

Definition at line 117 of file cursor.h.

QString KTextEditor::Cursor::toString ( ) const
inline

Returns the cursor position as string in the format "(line, column)".

See also
fromString()

Definition at line 126 of file cursor.h.

Friends And Related Function Documentation

constexpr friend bool operator!= ( const Cursor c1,
const Cursor c2 
)
friend

Inequality operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's and c2's line and column are not equal.

Definition at line 326 of file cursor.h.

constexpr friend Cursor operator+ ( const Cursor c1,
const Cursor c2 
)
friend

Addition operator.

Takes two cursors and returns their summation.

Parameters
c1the first position
c2the second position
Returns
a the summation of the two input cursors

Definition at line 263 of file cursor.h.

Cursor& operator+= ( Cursor c1,
const Cursor c2 
)
friend

Addition assignment operator.

Adds c2 to this cursor.

Parameters
c1the cursor being added to
c2the position to add
Returns
a reference to the cursor which has just been added to

Definition at line 274 of file cursor.h.

constexpr friend Cursor operator- ( const Cursor c1,
const Cursor c2 
)
friend

Subtraction operator.

Takes two cursors and returns the subtraction of c2 from c1.

Parameters
c1the first position
c2the second position
Returns
a cursor representing the subtraction of c2 from c1

Definition at line 288 of file cursor.h.

Cursor& operator-= ( Cursor c1,
const Cursor c2 
)
friend

Subtraction assignment operator.

Subtracts c2 from c1.

Parameters
c1the cursor being subtracted from
c2the position to subtract
Returns
a reference to the cursor which has just been subtracted from

Definition at line 299 of file cursor.h.

constexpr friend bool operator< ( const Cursor c1,
const Cursor c2 
)
friend

Less than operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's position is greater than or equal to c2's position, otherwise false.

Definition at line 362 of file cursor.h.

QDebug operator<< ( QDebug  s,
const Cursor cursor 
)
friend

qDebug() stream operator.

Writes this cursor to the debug output in a nicely formatted way.

Definition at line 382 of file cursor.h.

constexpr friend bool operator<= ( const Cursor c1,
const Cursor c2 
)
friend

Less than or equal to operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's position is lesser than or equal to c2's position, otherwise false.

Definition at line 374 of file cursor.h.

constexpr friend bool operator== ( const Cursor c1,
const Cursor c2 
)
friend

Equality operator.

Note
comparison between two invalid cursors is undefined. comparison between and invalid and a valid cursor will always be false.
Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's and c2's line and column are equal.

Definition at line 315 of file cursor.h.

constexpr friend bool operator> ( const Cursor c1,
const Cursor c2 
)
friend

Greater than operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's position is greater than c2's position, otherwise false.

Definition at line 338 of file cursor.h.

constexpr friend bool operator>= ( const Cursor c1,
const Cursor c2 
)
friend

Greater than or equal to operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's position is greater than or equal to c2's position, otherwise false.

Definition at line 350 of file cursor.h.


The documentation for this class was generated from the following file:
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Jul 26 2021 22:58:06 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.