LibSgfcPlusPlus::SgfcNode Class Reference

The SgfcNode class provides an implementation of the ISgfcNode interface. See the interface header file for documentation. More...

#include <SgfcNode.h>

Inheritance diagram for LibSgfcPlusPlus::SgfcNode:

Public Member Functions
	SgfcNode ()
	Initializes a newly constructed SgfcNode object. The node has no parent, children or siblings.
virtual	~SgfcNode ()
	Destroys and cleans up the SgfcNode object.
virtual std::shared_ptr< ISgfcNode >	GetFirstChild () const override
	Returns the node's first child node. Returns nullptr if the node has no children.
void	SetFirstChild (std::shared_ptr< ISgfcNode > node)
	Sets the node's first child node to node, overwriting the previously set first child node. This method performs no relinking of any kind.
virtual std::shared_ptr< ISgfcNode >	GetLastChild () const override
	Returns the node's last child node. Returns nullptr if the node has no children.
virtual std::vector< std::shared_ptr< ISgfcNode > >	GetChildren () const override
	Returns a collection of child nodes of the node. The collection is ordered, beginning with the first child node and ending with the last child node. The collection is empty if the node has no children.
virtual bool	HasChildren () const override
	Returns true if the node has one or more children. Returns false if the node has no children.
virtual std::shared_ptr< ISgfcNode >	GetNextSibling () const override
	Returns the node's next sibling node. Returns nullptr if the node has no next sibling node, i.e. if the node is the last child of its parent.
void	SetNextSibling (std::shared_ptr< ISgfcNode > node)
	Sets the node's next sibling node to node, overwriting the previously set next sibling node. This method performs no relinking of any kind.
virtual bool	HasNextSibling () const override
	Returns true if the node has a next sibling node. Returns false if the node has no next sibling node, i.e. if the node is the last child of its parent.
virtual std::shared_ptr< ISgfcNode >	GetPreviousSibling () const override
	Returns the node's previous sibling node. Returns nullptr if the node has no previous sibling node, i.e. if the node is the first child of its parent.
virtual bool	HasPreviousSibling () const override
	Returns true if the node has a previous sibling node. Returns false if the node has no previous sibling node, i.e. if the node is the first child of its parent.
virtual std::shared_ptr< ISgfcNode >	GetParent () const override
	Returns the node's parent node. Returns nullptr if the node has no parent node, i.e. if the node is the root node of a game tree.
void	SetParent (std::shared_ptr< ISgfcNode > node)
	Sets the node's parent node to node, overwriting the previously set parent node. This method performs no relinking of any kind.
virtual bool	HasParent () const override
	Returns true if the node has a parent node. Returns false if the node has no parent node, i.e. if the node is the root node of a game tree.
virtual bool	IsDescendantOf (std::shared_ptr< ISgfcNode > node) const override
	Returns true if the node is a descendant of node, i.e. if the node is anywhere below node in the game tree. Returns false if the node is not a descendant of node.
virtual bool	IsAncestorOf (std::shared_ptr< ISgfcNode > node) const override
	Returns true if the node is an ancestor of node, i.e. if the node is a direct or indirect parent of node. Returns false if the node is not an ancestor of node.
virtual bool	IsRoot () const override
	Returns true if the node is the root node of a game tree. Returns false if the node is not the root node of a game tree.
virtual SgfcNodeTraits	GetTraits () const override
	Returns the node's traits.
virtual bool	HasTrait (SgfcNodeTrait trait) const override
	Returns true if the node has the trait trait. Returns false if the node does not have the trait trait.
virtual std::shared_ptr< ISgfcNode >	GetRoot () const override
	Returns the root node of the game tree that contains the node. Returns the node itself if the node has no parent, i.e. if it is itself the root node.
virtual std::shared_ptr< ISgfcNode >	GetGameInfoNode () const override
	Returns the first node among the node itself and its ancestors that has the trait SgfcNodeTrait::GameInfo. Returns nullptr if there is no such node.
virtual std::vector< std::shared_ptr< ISgfcNode > >	GetMainVariationNodes () const override
	Returns an ordered collection of nodes that consists of the node's ancestors up to the root node, the node itself, and the main variation of game play found on the node's first child descendants.
virtual std::shared_ptr< ISgfcGameInfo >	CreateGameInfo () const override
	Returns a newly constructed ISgfcGameInfo object with values taken from the properties in the root node that GetRoot() returns and the game info node that GetGameInfoNode() returns.
virtual void	WriteGameInfo (std::shared_ptr< ISgfcGameInfo > gameInfo) const override
	Writes all root property values in gameInfo to the corresponding properties in the root node that GetRoot() returns, and all game info property values in gameInfo to the game info node that GetGameInfoNode() returns.
virtual bool	HasProperties () const override
	Returns true if the node has one or more properties. Returns false if the node has no properties.
virtual std::vector< std::shared_ptr< ISgfcProperty > >	GetProperties () const override
	Returns a collection with the properties of the node. The collection is empty if the node has no properties. The collection has no particular order.
virtual void	SetProperties (const std::vector< std::shared_ptr< ISgfcProperty > > &properties) override
	Sets the properties of the node to the collection properties. The collection may be empty. The order in which properties appear in the collection is irrelevant. No SgfcPropertyType except SgfcPropertyType::Unknown may appear more than once in the collection. No property name may appear more than once in the collection.
virtual void	SetProperty (std::shared_ptr< ISgfcProperty > property) override
	Adds property as the last property to the node's collection of properties. If the collection already contains a duplicate property that duplicate is removed first. property may not be nullptr.
virtual void	AppendProperty (std::shared_ptr< ISgfcProperty > property) override
	Adds property as the last property to the node's collection of properties. property may not be nullptr.
virtual void	RemoveProperty (std::shared_ptr< ISgfcProperty > property) override
	Removes property from the node's collection of properties.
virtual void	RemoveAllProperties () override
	Removes all properties from the node's collection of properties.
virtual std::shared_ptr< ISgfcProperty >	GetProperty (SgfcPropertyType propertyType) const override
	Returns the property with the specified type propertyType if the node has such a property. Returns nullptr if the node has no such property.
virtual std::shared_ptr< ISgfcProperty >	GetProperty (const std::string &propertyName) const override
	Returns the property with the specified name propertyName if the node has such a property. Returns nullptr if the node has no such property.
virtual std::vector< std::shared_ptr< ISgfcProperty > >	GetProperties (SgfcPropertyCategory propertyCategory) const override
	Returns a collection with the properties of the node that are classified as propertyCategory. The collection is empty if the node has no properties with the requested category. The collection has no particular order.
virtual std::vector< std::shared_ptr< ISgfcProperty > >	GetInheritedProperties () const override
	Returns a collection with the most recent occurrence of each property that has the trait SgfcPropertyTrait::Inheritable, when found on the node itself and its ancestors. The collection is empty if no properties were found. The collection has no particular order.
Public Member Functions inherited from LibSgfcPlusPlus::ISgfcNode
	ISgfcNode ()
	Initializes a newly constructed ISgfcNode object.
virtual	~ISgfcNode ()
	Destroys and cleans up the ISgfcNode object.

Detailed Description

The SgfcNode class provides an implementation of the ISgfcNode interface. See the interface header file for documentation.

The SgfcNode class inherits from std::enable_shared_from_this so that it can return a std::shared_ptr for itself (using the "this" pointer) from some of its methods. This only works if the SgfcNode object is owned by another external std::shared_ptr somewhere. If there is no such external std::shared_ptr the method in question will throw std::bad_weak_ptr. This is documented on the public interface for all affected methods.

The implementation of this class must take special care when it internally invokes one of the above-mentioned methods:

• If the calling method A is const
• And if the called method B is also const
• And if the called method B returns a non-const object
• Then the calling method A must not do anything non-const with the returned non-const object The reason: The returned non-const object is actually the same object that invoked method B, so the const method A would do something non-const to itself. See GetRoot() for an example where const'ness is removed to open open the described hazard.

Member Function Documentation

AppendProperty()

void LibSgfcPlusPlus::SgfcNode::AppendProperty ( std::shared_ptr< ISgfcProperty > property )

overridevirtual

Adds property as the last property to the node's collection of properties. property may not be nullptr.

Exceptions

std::invalid_argument

Is thrown if property is nullptr, if property is already in the node's collection of properties, or the node's collection of properties already contains another property with the same SgfcPropertyType (except SgfcPropertyType::Unknown which may appear more than once) or the same property name.

Implements LibSgfcPlusPlus::ISgfcNode.

CreateGameInfo()

std::shared_ptr< ISgfcGameInfo > LibSgfcPlusPlus::SgfcNode::CreateGameInfo ( ) const

overridevirtual

Returns a newly constructed ISgfcGameInfo object with values taken from the properties in the root node that GetRoot() returns and the game info node that GetGameInfoNode() returns.

If GetGameInfoNode() returns nullptr then the ISgfcGameInfo object contains only values taken from the properties in the root node, but all values that would normally be taken from the properties in the game info node have default values.

If the content in the root node indicates that the game type is SgfcGameType::Go then the returned object is an ISgfcGoGameInfo object. The game type is SgfcGameType::Go in the following cases:

• If the root node contains a property of type SgfcPropertyType::GM that either has no value, or that has a single Number value, and that value is 0.
• Or if the root node does not contain a property of type SgfcPropertyType::GM.

See also

ISgfcGame::CreateGameInfo()

Implements LibSgfcPlusPlus::ISgfcNode.

GetChildren()

std::vector< std::shared_ptr< ISgfcNode > > LibSgfcPlusPlus::SgfcNode::GetChildren ( ) const

overridevirtual

Returns a collection of child nodes of the node. The collection is ordered, beginning with the first child node and ending with the last child node. The collection is empty if the node has no children.

Implements LibSgfcPlusPlus::ISgfcNode.

GetFirstChild()

std::shared_ptr< ISgfcNode > LibSgfcPlusPlus::SgfcNode::GetFirstChild ( ) const

overridevirtual

Returns the node's first child node. Returns nullptr if the node has no children.

Implements LibSgfcPlusPlus::ISgfcNode.

GetGameInfoNode()

std::shared_ptr< ISgfcNode > LibSgfcPlusPlus::SgfcNode::GetGameInfoNode ( ) const

overridevirtual

Returns the first node among the node itself and its ancestors that has the trait SgfcNodeTrait::GameInfo. Returns nullptr if there is no such node.

The search starts with the node itself, then progresses to the node's parent, the node's parent's parent, etc. up to the root node of the game tree. The search returns the first node whose GetTraits() method returns a value that includes SgfcNodeTrait::GameInfo.

See also

SgfcNodeTrait::GameInfo

GetMainVariationNodes()

Exceptions

std::bad_weak_ptr

Is thrown if the method would like to return the node itself, but the ISgfcNode object is not wrapped by an std::shared_ptr somewhere external. It is impossible for the library client to encounter this scenario, it can only occur during internal unit testing.

Implements LibSgfcPlusPlus::ISgfcNode.

GetInheritedProperties()

std::vector< std::shared_ptr< ISgfcProperty > > LibSgfcPlusPlus::SgfcNode::GetInheritedProperties ( ) const

overridevirtual

Returns a collection with the most recent occurrence of each property that has the trait SgfcPropertyTrait::Inheritable, when found on the node itself and its ancestors. The collection is empty if no properties were found. The collection has no particular order.

The detailed search logic is this:

• Determine a list of properties that have the trait SgfcPropertyTrait::Inheritable.
• Start examining the node itself, then the node's parent, etc. up to the game tree's root node.
• When a node contains one of the inheritable properties, include that property in the search result returned by the method, then stop looking for that particular property.
• Stop the search when all properties have been found.

The SGF standard's description of inheritable properties includes the concept of a "setting getting cleared". The implication is that if a "setting is cleared" then, from the node's perspective, things should look as if the property that defines the setting has never been there in the first place. Ideally then the search result returned by the method should not include a property if that property's most recent occurrence "cleared the setting". The problem is the interpretation of when a setting is "being cleared". The SGF standard says that this typically happens when the property is set with an empty value - but typically is not always. Because the SGF standard is not definitive about the meaning, the method does not make assumptions. It simply returns a property's most recent occurrence and leaves the interpretation of the property value to the library client.

Implements LibSgfcPlusPlus::ISgfcNode.

GetLastChild()

std::shared_ptr< ISgfcNode > LibSgfcPlusPlus::SgfcNode::GetLastChild ( ) const

overridevirtual

Returns the node's last child node. Returns nullptr if the node has no children.

Implements LibSgfcPlusPlus::ISgfcNode.

GetMainVariationNodes()

std::vector< std::shared_ptr< ISgfcNode > > LibSgfcPlusPlus::SgfcNode::GetMainVariationNodes ( ) const

overridevirtual

Returns an ordered collection of nodes that consists of the node's ancestors up to the root node, the node itself, and the main variation of game play found on the node's first child descendants.

The main variation is defined as the depth-first path that starts with the node itself and continues along the first child descendants down to the last node that has no more children. The collection that is returned therefore contains the following nodes in the listed order:

• Element 0: The root node
• Element 1: The root node's child that leads to the node itself (not necessarily the first child)
• Element 2: The root node child's child that leads to the node itself (not necessarily the first child)
• [...]
• Element n: The node itself
• Element n+1: The node's first child
• Element n+2: The node's first child's first child
• Etc.

If the node is the root node the returned collection's first element is the node itself. If the node has no children the returned collection's last element is the node itself. If the node is the root node and it has no children the returned collection contains only the node itself.

This is a convenience method that is most useful when invoked on a game info node, i.e. a node that has the trait SgfcNodeTrait::GameInfo. The returned collection fully spans the game tree from root node to leaf node along a distinct path that contains the game info node on which the method was invoked. The returned collection effectively represents a full game.

See also

SgfcNodeTrait::GameInfo

GetGameInfoNode()

Exceptions

std::bad_weak_ptr

Is thrown if the method would like to return the node itself, but the ISgfcNode object is not wrapped by an std::shared_ptr somewhere external. It is impossible for the library client to encounter this scenario, it can only occur during internal unit testing.

Implements LibSgfcPlusPlus::ISgfcNode.

GetNextSibling()

std::shared_ptr< ISgfcNode > LibSgfcPlusPlus::SgfcNode::GetNextSibling ( ) const

overridevirtual

Returns the node's next sibling node. Returns nullptr if the node has no next sibling node, i.e. if the node is the last child of its parent.

Implements LibSgfcPlusPlus::ISgfcNode.

GetParent()

std::shared_ptr< ISgfcNode > LibSgfcPlusPlus::SgfcNode::GetParent ( ) const

overridevirtual

Returns the node's parent node. Returns nullptr if the node has no parent node, i.e. if the node is the root node of a game tree.

Implements LibSgfcPlusPlus::ISgfcNode.

GetPreviousSibling()

std::shared_ptr< ISgfcNode > LibSgfcPlusPlus::SgfcNode::GetPreviousSibling ( ) const

overridevirtual

Returns the node's previous sibling node. Returns nullptr if the node has no previous sibling node, i.e. if the node is the first child of its parent.

Implements LibSgfcPlusPlus::ISgfcNode.

GetProperties() [1/2]

std::vector< std::shared_ptr< ISgfcProperty > > LibSgfcPlusPlus::SgfcNode::GetProperties ( ) const

overridevirtual

Returns a collection with the properties of the node. The collection is empty if the node has no properties. The collection has no particular order.

The SGF standard does not define an order in which properties have to appear within a node. In fact, it explicitly states that different applications may use different ordering, and that the order may change every time that the SGF data is saved.

The SGF standard defines that only one of each property is allowed per node.

Implements LibSgfcPlusPlus::ISgfcNode.

GetProperties() [2/2]

std::vector< std::shared_ptr< ISgfcProperty > > LibSgfcPlusPlus::SgfcNode::GetProperties ( SgfcPropertyCategory propertyCategory ) const

overridevirtual

Returns a collection with the properties of the node that are classified as propertyCategory. The collection is empty if the node has no properties with the requested category. The collection has no particular order.

Implements LibSgfcPlusPlus::ISgfcNode.

GetProperty() [1/2]

std::shared_ptr< ISgfcProperty > LibSgfcPlusPlus::SgfcNode::GetProperty ( const std::string & propertyName ) const

overridevirtual

Returns the property with the specified name propertyName if the node has such a property. Returns nullptr if the node has no such property.

The SGF standard defines that only one of each property is allowed per node.

Implements LibSgfcPlusPlus::ISgfcNode.

GetProperty() [2/2]

std::shared_ptr< ISgfcProperty > LibSgfcPlusPlus::SgfcNode::GetProperty ( SgfcPropertyType propertyType ) const

overridevirtual

Returns the property with the specified type propertyType if the node has such a property. Returns nullptr if the node has no such property.

If propertyType is SgfcPropertyType::Unknown and the node has several such properties, returns the property that appears first in the list that is returned by GetProperties().

The SGF standard defines that only one of each property is allowed per node.

Implements LibSgfcPlusPlus::ISgfcNode.

GetRoot()

std::shared_ptr< ISgfcNode > LibSgfcPlusPlus::SgfcNode::GetRoot ( ) const

overridevirtual

Returns the root node of the game tree that contains the node. Returns the node itself if the node has no parent, i.e. if it is itself the root node.

Exceptions

std::bad_weak_ptr

Is thrown if the method would like to return the node itself, but the ISgfcNode object is not wrapped by an std::shared_ptr somewhere external. It is impossible for the library client to encounter this scenario, it can only occur during internal unit testing.

Implements LibSgfcPlusPlus::ISgfcNode.

GetTraits()

SgfcNodeTraits LibSgfcPlusPlus::SgfcNode::GetTraits ( ) const

overridevirtual

Returns the node's traits.

Returns SgfcConstants::NodeTraitsNone if the node is not the root node of a game tree and if it has either no properties or only properties with SgfcPropertyCategory::Miscellaneous.

See also

SgfcNodeTraits

Implements LibSgfcPlusPlus::ISgfcNode.

HasChildren()

bool LibSgfcPlusPlus::SgfcNode::HasChildren ( ) const

overridevirtual

Returns true if the node has one or more children. Returns false if the node has no children.

Implements LibSgfcPlusPlus::ISgfcNode.

HasNextSibling()

bool LibSgfcPlusPlus::SgfcNode::HasNextSibling ( ) const

overridevirtual

Returns true if the node has a next sibling node. Returns false if the node has no next sibling node, i.e. if the node is the last child of its parent.

Implements LibSgfcPlusPlus::ISgfcNode.

HasParent()

bool LibSgfcPlusPlus::SgfcNode::HasParent ( ) const

overridevirtual

Returns true if the node has a parent node. Returns false if the node has no parent node, i.e. if the node is the root node of a game tree.

Implements LibSgfcPlusPlus::ISgfcNode.

HasPreviousSibling()

bool LibSgfcPlusPlus::SgfcNode::HasPreviousSibling ( ) const

overridevirtual

Returns true if the node has a previous sibling node. Returns false if the node has no previous sibling node, i.e. if the node is the first child of its parent.

Implements LibSgfcPlusPlus::ISgfcNode.

HasProperties()

bool LibSgfcPlusPlus::SgfcNode::HasProperties ( ) const

overridevirtual

Returns true if the node has one or more properties. Returns false if the node has no properties.

Implements LibSgfcPlusPlus::ISgfcNode.

HasTrait()

bool LibSgfcPlusPlus::SgfcNode::HasTrait ( SgfcNodeTrait trait ) const

overridevirtual

Returns true if the node has the trait trait. Returns false if the node does not have the trait trait.

See also

SgfcNodeTrait

Implements LibSgfcPlusPlus::ISgfcNode.

IsAncestorOf()

bool LibSgfcPlusPlus::SgfcNode::IsAncestorOf ( std::shared_ptr< ISgfcNode > node ) const

overridevirtual

Returns true if the node is an ancestor of node, i.e. if the node is a direct or indirect parent of node. Returns false if the node is not an ancestor of node.

Exceptions

std::invalid_argument

Is thrown if node is nullptr.

Implements LibSgfcPlusPlus::ISgfcNode.

IsDescendantOf()

bool LibSgfcPlusPlus::SgfcNode::IsDescendantOf ( std::shared_ptr< ISgfcNode > node ) const

overridevirtual

Returns true if the node is a descendant of node, i.e. if the node is anywhere below node in the game tree. Returns false if the node is not a descendant of node.

Exceptions

std::invalid_argument

Is thrown if node is nullptr.

Implements LibSgfcPlusPlus::ISgfcNode.

IsRoot()

bool LibSgfcPlusPlus::SgfcNode::IsRoot ( ) const

overridevirtual

Returns true if the node is the root node of a game tree. Returns false if the node is not the root node of a game tree.

Implements LibSgfcPlusPlus::ISgfcNode.

RemoveAllProperties()

void LibSgfcPlusPlus::SgfcNode::RemoveAllProperties ( )

overridevirtual

Removes all properties from the node's collection of properties.

Implements LibSgfcPlusPlus::ISgfcNode.

RemoveProperty()

void LibSgfcPlusPlus::SgfcNode::RemoveProperty ( std::shared_ptr< ISgfcProperty > property )

overridevirtual

Removes property from the node's collection of properties.

Exceptions

std::invalid_argument

Is thrown if property is not part of the node's collection of properties.

Implements LibSgfcPlusPlus::ISgfcNode.

SetFirstChild()

void LibSgfcPlusPlus::SgfcNode::SetFirstChild

(

std::shared_ptr< ISgfcNode >

node

)

Sets the node's first child node to node, overwriting the previously set first child node. This method performs no relinking of any kind.

This is a library-internal setter method. Library clients should never be able to invoke this directly. Instead library clients must use ISgfcTreeBuilder.

SetNextSibling()

void LibSgfcPlusPlus::SgfcNode::SetNextSibling

(

std::shared_ptr< ISgfcNode >

node

)

Sets the node's next sibling node to node, overwriting the previously set next sibling node. This method performs no relinking of any kind.

This is a library-internal setter method. Library clients should never be able to invoke this directly. Instead library clients must use ISgfcTreeBuilder.

SetParent()

void LibSgfcPlusPlus::SgfcNode::SetParent

(

std::shared_ptr< ISgfcNode >

node

)

Sets the node's parent node to node, overwriting the previously set parent node. This method performs no relinking of any kind.

This is a library-internal setter method. Library clients should never be able to invoke this directly. Instead library clients must use ISgfcTreeBuilder.

SetProperties()

void LibSgfcPlusPlus::SgfcNode::SetProperties ( const std::vector< std::shared_ptr< ISgfcProperty > > & properties )

overridevirtual

Sets the properties of the node to the collection properties. The collection may be empty. The order in which properties appear in the collection is irrelevant. No SgfcPropertyType except SgfcPropertyType::Unknown may appear more than once in the collection. No property name may appear more than once in the collection.

The SGF standard defines that only one of each property is allowed per node. This is the reason why this method prevents setting a collection that contains duplicate property types or names. Names are checked to prevent duplicates of custom properties, which have SgfcPropertyType::Unknown.

Exceptions

std::invalid_argument

Is thrown if properties contains nullptr elements, or if an SgfcPropertyType other than SgfcPropertyType::Unknown appears more than once, or if a property name appears more than once.

Implements LibSgfcPlusPlus::ISgfcNode.

SetProperty()

void LibSgfcPlusPlus::SgfcNode::SetProperty ( std::shared_ptr< ISgfcProperty > property )

overridevirtual

Adds property as the last property to the node's collection of properties. If the collection already contains a duplicate property that duplicate is removed first. property may not be nullptr.

Duplicate elimination works like this:

• If property has SgfcPropertyType::Unknown then the collection is searched for a duplicate by property name only.
• If property has a property type that is not SgfcPropertyType::Unknown then the collection is searched for a duplicate both by property type and by property name.

The method does nothing if the node's collection of properties already contains property.

Exceptions

std::invalid_argument

Is thrown if property is nullptr.

Implements LibSgfcPlusPlus::ISgfcNode.

WriteGameInfo()

void LibSgfcPlusPlus::SgfcNode::WriteGameInfo ( std::shared_ptr< ISgfcGameInfo > gameInfo ) const

overridevirtual

Writes all root property values in gameInfo to the corresponding properties in the root node that GetRoot() returns, and all game info property values in gameInfo to the game info node that GetGameInfoNode() returns.

If GetGameInfoNode() returns nullptr then the game info property values in gameInfo are written to the root node.

Game info property values are written only if they are not equal to their default values (already existing property values are overwritten). Game info property values that are equal to their default value cause the property to be removed, if it exists, from the game info node.

Root property values are always written, regardless of whether they are equal to their default values.

Exceptions

std::invalid_argument

Is thrown if gameInfo is nullptr.

Implements LibSgfcPlusPlus::ISgfcNode.

---

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

• /Users/patrick/dev/libsgfcplusplus/src/document/SgfcNode.h
• /Users/patrick/dev/libsgfcplusplus/src/document/SgfcNode.cpp