regina::StrandRef Class Reference

A reference to one of the two strands of a link that pass each other at a crossing. More...

#include <link/link.h>

Public Member Functions
	StrandRef ()
	Initialises this to a null reference. More...
	StrandRef (Crossing *crossing, int strand)
	Initialises this to the given strand of the given crossing. More...
	StrandRef (const StrandRef &)=default
	Creates a new copy of the given strand reference. More...
Crossing *	crossing () const
	The crossing that this reference points to. More...
int	strand () const
	Indicates whether this reference points to the upper or lower strand of the relevant crossing. More...
ssize_t	id () const
	An integer that uniquely identifies this strand within the link. More...
bool	operator== (const StrandRef &rhs) const
	Tests whether this and the given reference are identical. More...
bool	operator!= (const StrandRef &rhs) const
	Tests whether this and the given reference are not identical. More...
StrandRef &	operator= (const StrandRef &)=default
	Sets this to be a copy of the given strand reference. More...
StrandRef &	operator++ ()
	Moves this reference forward along the direction of the link until it reaches the next crossing. More...
StrandRef	operator++ (int)
	Moves this reference forward along the direction of the link until it reaches the next crossing. More...
StrandRef &	operator-- ()
	Moves this reference backward against the direction of the link until it reaches the previous crossing. More...
StrandRef	operator-- (int)
	Moves this reference backward against the direction of the link until it reaches the previous crossing. More...
StrandRef	next () const
	Returns the crossing reference that comes immediately after this when walking forward along the direction of the link. More...
StrandRef	prev () const
	Returns the crossing reference that comes immediately before this when walking backward against the direction of the link. More...
void	jump ()
	Jumps to the other strand at the same crossing. More...
	operator bool () const
	Tests whether this is a non-null reference. More...

Friends
class	Link
class	ModelLinkGraph
class	Tangle

Detailed Description

A reference to one of the two strands of a link that pass each other at a crossing.

This class is a simple wrapper that stores (i) a pointer to the relevant crossing; and (ii) an integer to denote whether this refers to the upper strand (which passes over the crossing) or the lower strand (which passes under the crossing).

A "null reference" is one whose crossing is the null pointer.

This class can also be used to refer to an arc of a link; that is, a section of the link that runs from one crossing to the next. When used in this way:

• The arc referred to is the arc beginning at the given strand of the given crossing, and moving forwards along the orientation of the link to the next crossing.
• A null reference is used to refer to an entire zero-crossing unknot component (as opposed to a typical arc which has well-defined start and end points). Of course the link in question may not have such a component, or may have many such components; the behaviour of the code in such circumstances is documented in the individual routines that take arc references as arguments.
• The increment and decrement operators, as well as next() and prev(), behave as expected: they follow the link forward and backward respectively along its orientation.

These objects are small enough to pass by value and swap with std::swap(), with no need for any specialised move operations or swap functions.

Constructor & Destructor Documentation

StrandRef() [1/3]

regina::StrandRef::StrandRef ( )

inline

Initialises this to a null reference.

The pointer returned by crossing() will be null, and the integer returned by strand() will be 0.

StrandRef() [2/3]

regina::StrandRef::StrandRef ( Crossing *  crossing, int  strand  )

inline

Initialises this to the given strand of the given crossing.

The given crossing may be null, in which case this will become a null reference. If you are creating a null reference, then it is highly recommended that you pass strand as 0, so that comparison tests treat this null reference as equal to a null reference created by the zero-argument constructor.

Parameters

crossing	the crossing being identified.
strand	0 to denote the strand running under the crossing, or 1 to denote the strand running over the crossing.

StrandRef() [3/3]

regina::StrandRef::StrandRef ( const StrandRef &  )

default

Creates a new copy of the given strand reference.

Member Function Documentation

crossing()

Crossing * regina::StrandRef::crossing ( ) const

inline

The crossing that this reference points to.

The information returned by crossing() and strand() together pinpoint exactly which strand of the link this reference points to.

Returns

the crossing, or null if this is a null reference.

id()

ssize_t regina::StrandRef::id ( ) const

inline

An integer that uniquely identifies this strand within the link.

This integer will be 2c+s, where c is the index of the crossing, and s is 0 or 1 for the lower or upper strand respectively.

If this is a null reference, then id() will return -1.

A strand can be restored from its ID by calling Link::strand().

Returns

the unique ID of this strand within the link.

jump()

void regina::StrandRef::jump ( )

inline

Jumps to the other strand at the same crossing.

This reference will be changed directly. The crossing will remain the same, but the strand will switch from lower to upper or vice versa.

next()

StrandRef regina::StrandRef::next ( ) const

inline

Returns the crossing reference that comes immediately after this when walking forward along the direction of the link.

Equivalently, this routine returns the reference that would be obtained by calling the increment (++) operator (but, unlike the increment operator, this routine does not actually change the current reference).

Precondition

This is not a null reference, i.e., crossing() does not return null.

Returns

the crossing reference that follows this.

operator bool()

regina::StrandRef::operator bool ( ) const

inline

Tests whether this is a non-null reference.

Returns

true if this is not a null reference (i.e., crossing() does not return a null pointer), or false if this is a null reference.

operator!=()

bool regina::StrandRef::operator!= ( const StrandRef &  rhs ) const

inline

Tests whether this and the given reference are not identical.

Two references are identical if and only if they return the same values for both crossing() and strand().

Warning

If you create a null reference by calling StrandRef(null, 1) then this will not be considered equal to the null reference created by calling StrandRef(), since the latter is equivalent to calling StrandRef(null, 0).

true if and only if this and rhs are not identical.

operator++() [1/2]

StrandRef & regina::StrandRef::operator++ ( )

inline

Moves this reference forward along the direction of the link until it reaches the next crossing.

(Of course, if the link contains a trivial twist then this may in fact return to the same crossing but the other strand).

This is a preincrement operator: the object will be changed, and then a reference to it will be returned.

Precondition

This is not a null reference, i.e., crossing() does not return null.

Python

Not present. The postincrement operator is available in Python under the name inc().

Returns

a reference to this object.

operator++() [2/2]

StrandRef regina::StrandRef::operator++ ( int  )

inline

Moves this reference forward along the direction of the link until it reaches the next crossing.

(Of course, if the link contains a trivial twist then this may in fact return to the same crossing but the other strand).

This is a postincrement operator: the object will be changed, but a copy of the original reference will be returned.

Precondition

This is not a null reference, i.e., crossing() does not return null.

Python

This routine is available under the name inc().

Returns

a copy of this object before the change took place.

operator--() [1/2]

StrandRef & regina::StrandRef::operator-- ( )

inline

Moves this reference backward against the direction of the link until it reaches the previous crossing.

(Of course, if the link contains a trivial twist then this may in fact return to the same crossing but the other strand).

This is a preincrement operator: the object will be changed, and then a reference to it will be returned.

Precondition

This is not a null reference, i.e., crossing() does not return null.

Python

Not present. The postincrement operator is available in Python under the name dec().

Returns

a reference to this object.

operator--() [2/2]

StrandRef regina::StrandRef::operator-- ( int  )

inline

Moves this reference backward against the direction of the link until it reaches the previous crossing.

(Of course, if the link contains a trivial twist then this may in fact return to the same crossing but the other strand).

This is a postincrement operator: the object will be changed, but a copy of the original reference will be returned.

Precondition

This is not a null reference, i.e., crossing() does not return null.

Python

This routine is available under the name dec().

Returns

a copy of this object before the change took place.

operator=()

StrandRef & regina::StrandRef::operator= ( const StrandRef &  )

default

Sets this to be a copy of the given strand reference.

Returns

a reference to this object.

operator==()

bool regina::StrandRef::operator== ( const StrandRef &  rhs ) const

inline

Tests whether this and the given reference are identical.

Two references are identical if and only if they return the same values for both crossing() and strand().

Warning

If you create a null reference by calling StrandRef(null, 1) then this will not be considered equal to the null reference created by calling StrandRef(), since the latter is equivalent to calling StrandRef(null, 0).

true if and only if this and rhs are identical.

prev()

StrandRef regina::StrandRef::prev ( ) const

inline

Returns the crossing reference that comes immediately before this when walking backward against the direction of the link.

Equivalently, this routine returns the reference that would be obtained by calling the decrement (–) operator (but, unlike the decrement operator, this routine does not actually change the current reference).

Precondition

This is not a null reference, i.e., crossing() does not return null.

Returns

the crossing reference that precedes this.

strand()

int regina::StrandRef::strand ( ) const

inline

Indicates whether this reference points to the upper or lower strand of the relevant crossing.

A value of 1 denotes the upper strand (which passes over the crossing), and a value of 0 denotes the lower strand (which passes under the crossing).

The information returned by crossing() and strand() together pinpoint exactly which strand of the link this reference points to.

Returns

either 0 or 1 to indicate the strand.

---

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

• link/link.h