KTextEditor::Range Class Reference

#include <range.h>

Inheritance diagram for KTextEditor::Range:

Public Member Functions
	Range ()
	Range (const Cursor &start, const Cursor &end)
	Range (const Cursor &start, int width)
	Range (const Cursor &start, int endLine, int endColumn)
	Range (int startLine, int startColumn, int endLine, int endColumn)
	Range (const Range &copy)
virtual	~Range ()
Range	encompass (const Range &range) const
Range	intersect (const Range &range) const
virtual bool	isSmartRange () const
virtual bool	isValid () const
Range &	operator= (const Range &rhs)
virtual SmartRange *	toSmartRange () const
Position
The following functions provide access to, and manipulation of, the range's position.
Cursor &	start ()
const Cursor &	start () const
Cursor &	end ()
const Cursor &	end () const
void	setBothLines (int line)
void	setBothColumns (int column)
virtual void	setRange (const Range &range)
void	setRange (const Cursor &start, const Cursor &end)
virtual bool	expandToRange (const Range &range)
virtual bool	confineToRange (const Range &range)
bool	onSingleLine () const
int	numberOfLines () const
int	columnWidth () const
bool	isEmpty () const
Comparison
The following functions perform checks against this range in comparison to other lines, columns, cursors, and ranges.
bool	contains (const Range &range) const
bool	contains (const Cursor &cursor) const
bool	containsLine (int line) const
bool	containsColumn (int column) const
bool	overlaps (const Range &range) const
bool	overlapsLine (int line) const
bool	overlapsColumn (int column) const
int	positionRelativeToCursor (const Cursor &cursor) const
int	positionRelativeToLine (int line) const
bool	boundaryAtCursor (const Cursor &cursor) const
bool	boundaryOnLine (int line) const
bool	boundaryOnColumn (int column) const

Static Public Member Functions
static Range	invalid ()

Protected Member Functions
	Range (Cursor *start, Cursor *end)
virtual void	rangeChanged (Cursor *cursor, const Range &from)

Protected Attributes
Cursor *	m_end
Cursor *	m_start

Friends
bool	operator!= (const Range &r1, const Range &r2)
Range	operator& (const Range &r1, const Range &r2)
Range &	operator&= (Range &r1, const Range &r2)
Range	operator+ (const Range &r1, const Range &r2)
Range &	operator+= (Range &r1, const Range &r2)
Range	operator- (const Range &r1, const Range &r2)
Range &	operator-= (Range &r1, const Range &r2)
bool	operator< (const Range &r1, const Range &r2)
QDebug	operator<< (QDebug s, const Range &range)
bool	operator== (const Range &r1, const Range &r2)
bool	operator> (const Range &r1, const Range &r2)

Detailed Description

An object representing a section of text, from one Cursor to another.

A Range is a basic class which represents a range of text with two Cursors, from a start() position to an end() position.

For simplicity and convenience, ranges always maintain their start position to be before or equal to their end position. Attempting to set either the start or end of the range beyond the respective end or start will result in both values being set to the specified position. In the constructor, the start and end will be swapped if necessary.

If you want additional functionality such as the ability to maintain position in a document, see SmartRange.

See also

SmartRange

Author

Hamish Rodda <rodda.nosp@m.@kde.nosp@m..org>

Definition at line 54 of file range.h.

Constructor & Destructor Documentation

Range::Range

(

)

Default constructor.

Creates a valid range from position (0, 0) to position (0, 0).

Definition at line 29 of file range.cpp.

Range::Range	(	const Cursor &	start,
		const Cursor &	end
	)

Constructor which creates a range from start to end.

If start is after end, they will be swapped.

Parameters

start	start position
end	end position

Definition at line 37 of file range.cpp.

Range::Range	(	const Cursor &	start,
		int	width
	)

Constructor which creates a single-line range from start, extending width characters along the same line.

Parameters

start	start position
width	width of this range in columns along the same line

Definition at line 52 of file range.cpp.

Range::Range	(	const Cursor &	start,
		int	endLine,
		int	endColumn
	)

Constructor which creates a range from start, to endLine, endColumn.

Parameters

start	start position
endLine	end line
endColumn	end column

Definition at line 60 of file range.cpp.

Range::Range	(	int	startLine,
		int	startColumn,
		int	endLine,
		int	endColumn
	)

Constructor which creates a range from startLine, startColumn to endLine, endColumn.

Parameters

startLine	start line
startColumn	start column
endLine	end line
endColumn	end column

Definition at line 74 of file range.cpp.

Range::Range

(

const Range &

copy

)

Copy constructor.

Parameters

copy	the range from which to copy the start and end position.

Definition at line 102 of file range.cpp.

Range::~Range ( )

virtual

Virtual destructor.

Definition at line 110 of file range.cpp.

Range::Range ( Cursor *  start, Cursor *  end  )

protected

Constructor for advanced cursor types.

Creates a range from start to end. Takes ownership of start and end.

Parameters

start	the start cursor.
end	the end cursor.

Definition at line 88 of file range.cpp.

Member Function Documentation

bool Range::boundaryAtCursor

(

const Cursor &

cursor

)

const

Check whether cursor is located at either of the start() or end() boundaries.

Parameters

cursor

cursor to check

Returns

true if the cursor is equal to start() or end(), otherwise false.

Definition at line 182 of file range.cpp.

bool KTextEditor::Range::boundaryOnColumn

(

int

column

)

const

Check whether column is on the same column as either of the start() or end() boundaries.

Parameters

column

column to check

Returns

true if column is on the same column as either of the boundaries, otherwise false

bool Range::boundaryOnLine

(

int

line

)

const

Check whether line is on the same line as either of the start() or end() boundaries.

Parameters

line	line to check

Returns

true if line is on the same line as either of the boundaries, otherwise false

Definition at line 187 of file range.cpp.

int KTextEditor::Range::columnWidth

(

)

const

Returns the number of columns separating the start() and end() positions.

Returns

the number of columns separating the start() and end() positions; 0 if the start and end columns are the same.

Definition at line 244 of file range.cpp.

bool Range::confineToRange ( const Range &  range )

virtual

Confine this range if necessary to fit within range.

Parameters

range

range which should contain this range

Returns

true if confinement occurred, false otherwise

Reimplemented in KTextEditor::SmartRange.

Definition at line 192 of file range.cpp.

bool Range::contains

(

const Range &

range

)

const

Check whether the this range wholly encompasses range.

Parameters

range

range to check

Returns

true, if this range contains range, otherwise false

Definition at line 160 of file range.cpp.

bool Range::contains

(

const Cursor &

cursor

)

const

Check to see if cursor is contained within this range, ie >= start() and < end().

Parameters

cursor

the position to test for containment

Returns

true if the cursor is contained within this range, otherwise false.

Definition at line 155 of file range.cpp.

bool Range::containsColumn

(

int

column

)

const

Check whether the range contains column.

Parameters

column

column to check

Returns

true if the range contains column, otherwise false

Definition at line 165 of file range.cpp.

bool Range::containsLine

(

int

line

)

const

Returns true if this range wholly encompasses line.

Parameters

line	line to check

Returns

true if the line is wholly encompassed by this range, otherwise false.

Definition at line 140 of file range.cpp.

Range KTextEditor::Range::encompass

(

const Range &

range

)

const

Returns the smallest range which encompasses this range and the supplied range.

Parameters

range

other range to encompass

Returns

the smallest range which contains this range and the supplied range.

Definition at line 324 of file range.cpp.

Cursor & KTextEditor::Range::end

(

)

Get the end position of this range.

This will always be >= start().

This non-const function allows direct manipulation of the end position, while still retaining notification support.

If end is set to a position before start, start will be moved to the same position as end, as ranges are not allowed to have start() > end().

Note

If you want to change both start() and end() simultaneously, you should use setRange(), for several reasons:

• otherwise, the rule preventing start() > end() may alter your intended change
• any notifications needed will be performed multiple times for no benefit

Returns

a reference to the end position of this range.

this function is virtual to allow for covariant return of SmartCursors.

Definition at line 306 of file range.cpp.

const Cursor & KTextEditor::Range::end

(

)

const

Get the end position of this range.

This will always be >= start().

Returns

a const reference to the end position of this range.

this function is virtual to allow for covariant return of SmartCursors.

Definition at line 311 of file range.cpp.

bool Range::expandToRange ( const Range &  range )

virtual

Expand this range if necessary to contain range.

Parameters

range

range which this range should contain

Returns

true if expansion occurred, false otherwise

Reimplemented in KTextEditor::SmartRange.

Definition at line 207 of file range.cpp.

Range KTextEditor::Range::intersect

(

const Range &

range

)

const

Intersects this range with another, returning the shared area of the two ranges.

Parameters

range

other range to intersect with this

Returns

the intersection of this range and the supplied range.

Definition at line 316 of file range.cpp.

Range Range::invalid ( )

static

Returns an invalid range.

Definition at line 121 of file range.cpp.

bool KTextEditor::Range::isEmpty

(

)

const

Returns true if this range contains no characters, ie.

the start() and end() positions are the same.

Returns

true if the range contains no characters, otherwise false

Definition at line 254 of file range.cpp.

bool KTextEditor::Range::isSmartRange ( ) const

virtual

Returns whether this range is a SmartRange.

Reimplemented in KTextEditor::SmartRange.

Definition at line 286 of file range.cpp.

bool Range::isValid ( ) const

virtual

Validity check.

In the base class, returns true unless the range starts before (0,0).

Definition at line 116 of file range.cpp.

int KTextEditor::Range::numberOfLines

(

)

const

Returns the number of lines separating the start() and end() positions.

Returns

the number of lines separating the start() and end() positions; 0 if the start and end lines are the same.

Definition at line 249 of file range.cpp.

bool KTextEditor::Range::onSingleLine

(

)

const

Check whether this range is wholly contained within one line, ie.

if the start() and end() positions are on the same line.

Returns

true if both the start and end positions are on the same line, otherwise false

Definition at line 239 of file range.cpp.

Range& KTextEditor::Range::operator= ( const Range &  rhs )

inline

Assignment operator.

Same as setRange().

Parameters

rhs	range to assign to this range.

Returns

a reference to this range, after assignment has occurred.

See also

setRange()

Definition at line 452 of file range.h.

bool Range::overlaps

(

const Range &

range

)

const

Check whether the this range overlaps with range.

Parameters

range

range to check against

Returns

true, if this range overlaps with range, otherwise false

Definition at line 170 of file range.cpp.

bool Range::overlapsColumn

(

int

column

)

const

Check to see if this range overlaps column; that is, if column is between start().column() and end().column().

This function is most likely to be useful in relation to block text editing.

Parameters

column

the column to test

Returns

true if the column is between the range's starting and ending columns, otherwise false.

Definition at line 150 of file range.cpp.

bool Range::overlapsLine

(

int

line

)

const

Check whether the range overlaps at least part of line.

Parameters

line	line to check

Returns

true, if the range overlaps at least part of line, otherwise false

Definition at line 145 of file range.cpp.

int Range::positionRelativeToCursor

(

const Cursor &

cursor

)

const

Determine where cursor is positioned in relationship to this range.

Equivalency (a return value of 0) is returned when cursor is contained within the range, not when overlapped - i.e., cursor may be on a line which is also partially occupied by this range, but the position may not be eqivalent. For overlap checking, use positionRelativeToLine().

Parameters

cursor

position to check

Returns

-1 if before, +1 if after, and 0 if cursor is contained within the range.

See also

positionRelativeToLine()

Definition at line 259 of file range.cpp.

int Range::positionRelativeToLine

(

int

line

)

const

Determine where line is positioned in relationship to this range.

Equivalency (a return value of 0) is returned when line is overlapped within the range, not when contained - i.e., this range may not cover an entire line, but line's position will still be eqivalent. For containment checking, use positionRelativeToCursor().

Parameters

line	line to check

Returns

-1 if before, +1 if after, and 0 if line is overlapped by this range.

See also

positionRelativeToCursor()

Definition at line 270 of file range.cpp.

void Range::rangeChanged ( Cursor *  cursor, const Range &  from  )

protectedvirtual

Notify this range that one or both of the cursors' position has changed directly.

Parameters

cursor	the cursor that changed. If 0L, both cursors have changed.
from	the previous position of this range

Reimplemented in KTextEditor::SmartRange.

Definition at line 222 of file range.cpp.

void KTextEditor::Range::setBothColumns

(

int

column

)

Convenience function.

Set the start and end columns to column.

Parameters

column

the column number to assign to start() and end()

Definition at line 281 of file range.cpp.

void Range::setBothLines

(

int

line

)

Convenience function.

Set the start and end lines to line.

Parameters

line	the line number to assign to start() and end()

Definition at line 234 of file range.cpp.

void Range::setRange ( const Range &  range )

virtual

Set the start and end cursors to range.start() and range.end() respectively.

Parameters

range

range to assign to this range

Reimplemented in KTextEditor::SmartRange.

Definition at line 126 of file range.cpp.

void Range::setRange	(	const Cursor &	start,
		const Cursor &	end
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Set the start and end cursors to start and end respectively.

Note

If start is after end, they will be reversed.

Parameters

start	start cursor
end	end cursor

Definition at line 132 of file range.cpp.

Cursor & KTextEditor::Range::start

(

)

Get the start position of this range.

This will always be <= end().

This non-const function allows direct manipulation of the start position, while still retaining notification support.

If start is set to a position after end, end will be moved to the same position as start, as ranges are not allowed to have start() > end().

Note

If you want to change both start() and end() simultaneously, you should use setRange(), for several reasons:

• otherwise, the rule preventing start() > end() may alter your intended change
• any notifications needed will be performed multiple times for no benefit

Returns

a reference to the start position of this range.

Definition at line 296 of file range.cpp.

const Cursor & KTextEditor::Range::start

(

)

const

Get the start position of this range.

This will always be <= end().

Returns

a const reference to the start position of this range.

this function is virtual to allow for covariant return of SmartCursors.

Definition at line 301 of file range.cpp.

SmartRange * KTextEditor::Range::toSmartRange ( ) const

virtual

Returns this range as a SmartRange, if it is one.

Reimplemented in KTextEditor::SmartRange.

Definition at line 291 of file range.cpp.

Friends And Related Function Documentation

bool operator!= ( const Range &  r1, const Range &  r2  )

friend

Inequality operator.

Parameters

r1	first range to compare
r2	second range to compare

Returns

true if r1 and r2 do not equal, otherwise false

Definition at line 541 of file range.h.

Range operator& ( const Range &  r1, const Range &  r2  )

friend

Intersects r1 and r2.

Parameters

r1	the first range
r2	the second range

Returns

the intersected range, invalid() if there is no overlap

Definition at line 508 of file range.h.

Range& operator&= ( Range &  r1, const Range &  r2  )

friend

Intersects r1 with r2 and assigns the result to r1.

Parameters

r1	the range to assign the intersection to
r2	the range to intersect r1 with

Returns

a reference to this range, after the intersection has taken place

Definition at line 519 of file range.h.

Range operator+ ( const Range &  r1, const Range &  r2  )

friend

Addition operator.

Takes two ranges and returns their summation.

Parameters

r1	the first range
r2	the second range

Returns

a the summation of the two input ranges

Definition at line 463 of file range.h.

Range& operator+= ( Range &  r1, const Range &  r2  )

friend

Addition assignment operator.

Adds r2 to this range.

Parameters

r1	the first range
r2	the second range

Returns

a reference to the cursor which has just been added to

Definition at line 474 of file range.h.

Range operator- ( const Range &  r1, const Range &  r2  )

friend

Subtraction operator.

Takes two ranges and returns the subtraction of r2 from r1.

Parameters

r1	the first range
r2	the second range

Returns

a range representing the subtraction of r2 from r1

Definition at line 486 of file range.h.

Range& operator-= ( Range &  r1, const Range &  r2  )

friend

Subtraction assignment operator.

Subtracts r2 from r1.

Parameters

r1	the first range
r2	the second range

Returns

a reference to the range which has just been subtracted from

Definition at line 497 of file range.h.

bool operator< ( const Range &  r1, const Range &  r2  )

friend

Less than operator.

Looks only at the position of the two ranges, does not consider their size.

Parameters

r1	first range to compare
r2	second range to compare

Returns

true if r1 ends before r2 begins, otherwise false

Definition at line 565 of file range.h.

QDebug operator<< ( QDebug  s, const Range &  range  )

friend

kDebug() stream operator.

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

Definition at line 571 of file range.h.

bool operator== ( const Range &  r1, const Range &  r2  )

friend

Equality operator.

Parameters

r1	first range to compare
r2	second range to compare

Returns

true if r1 and r2 equal, otherwise false

Definition at line 530 of file range.h.

bool operator> ( const Range &  r1, const Range &  r2  )

friend

Greater than operator.

Looks only at the position of the two ranges, does not consider their size.

Parameters

r1	first range to compare
r2	second range to compare

Returns

true if r1 starts after where r2 ends, otherwise false

Definition at line 553 of file range.h.

Member Data Documentation

Cursor* KTextEditor::Range::m_end

protected

This range's end cursor pointer.

Definition at line 612 of file range.h.

Cursor* KTextEditor::Range::m_start

protected

This range's start cursor pointer.

Definition at line 605 of file range.h.

---

The documentation for this class was generated from the following files:

• range.h
• range.cpp