The ISgfcNode interface provides access to the data of a single SGF node in a tree of SGF nodes. ISgfcNode also provides methods to navigate the game tree. ISgfcNode provides no methods to manipulate the game tree - use ISgfcTreeBuilder for that purpose. More...
#include <ISgfcNode.h>
Public Member Functions | |
| ISgfcNode () | |
| Initializes a newly constructed ISgfcNode object. | |
| virtual | ~ISgfcNode () |
| Destroys and cleans up the ISgfcNode object. | |
Game tree navigation | |
| virtual std::shared_ptr< ISgfcNode > | GetFirstChild () const =0 |
| Returns the node's first child node. Returns nullptr if the node has no children. | |
| virtual std::shared_ptr< ISgfcNode > | GetLastChild () const =0 |
| Returns the node's last child node. Returns nullptr if the node has no children. | |
| virtual std::vector< std::shared_ptr< ISgfcNode > > | GetChildren () const =0 |
| 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 =0 |
| 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 =0 |
| 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. | |
| virtual bool | HasNextSibling () const =0 |
| 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 =0 |
| 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 =0 |
| 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 =0 |
| 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. | |
| virtual bool | HasParent () const =0 |
| 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 =0 |
| 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 =0 |
| 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 =0 |
| 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. | |
Node traits | |
| virtual SgfcNodeTraits | GetTraits () const =0 |
| Returns the node's traits. | |
| virtual bool | HasTrait (SgfcNodeTrait trait) const =0 |
| Returns true if the node has the trait trait. Returns false if the node does not have the trait trait. | |
Game tree search | |
| virtual std::shared_ptr< ISgfcNode > | GetRoot () const =0 |
| 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 =0 |
| 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 =0 |
| 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. | |
Game info access | |
| virtual std::shared_ptr< ISgfcGameInfo > | CreateGameInfo () const =0 |
| 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 =0 |
| 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. | |
Property access | |
| virtual bool | HasProperties () const =0 |
| 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 =0 |
| 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)=0 |
| 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)=0 |
| 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)=0 |
| 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)=0 |
| Removes property from the node's collection of properties. | |
| virtual void | RemoveAllProperties ()=0 |
| Removes all properties from the node's collection of properties. | |
| virtual std::shared_ptr< ISgfcProperty > | GetProperty (SgfcPropertyType propertyType) const =0 |
| 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 =0 |
| 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 =0 |
| 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 =0 |
| 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. | |
Detailed Description
The ISgfcNode interface provides access to the data of a single SGF node in a tree of SGF nodes. ISgfcNode also provides methods to navigate the game tree. ISgfcNode provides no methods to manipulate the game tree - use ISgfcTreeBuilder for that purpose.
Member Function Documentation
◆ AppendProperty()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ CreateGameInfo()
|
pure virtual |
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()
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetChildren()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetFirstChild()
|
pure virtual |
Returns the node's first child node. Returns nullptr if the node has no children.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetGameInfoNode()
|
pure virtual |
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.
- 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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetInheritedProperties()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetLastChild()
|
pure virtual |
Returns the node's last child node. Returns nullptr if the node has no children.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetMainVariationNodes()
|
pure virtual |
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.
- 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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetNextSibling()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetParent()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetPreviousSibling()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetProperties() [1/2]
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetProperties() [2/2]
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetProperty() [1/2]
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetProperty() [2/2]
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetRoot()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ GetTraits()
|
pure virtual |
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
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ HasChildren()
|
pure virtual |
Returns true if the node has one or more children. Returns false if the node has no children.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ HasNextSibling()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ HasParent()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ HasPreviousSibling()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ HasProperties()
|
pure virtual |
Returns true if the node has one or more properties. Returns false if the node has no properties.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ HasTrait()
|
pure virtual |
Returns true if the node has the trait trait. Returns false if the node does not have the trait trait.
- See also
- SgfcNodeTrait
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ IsAncestorOf()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ IsDescendantOf()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ IsRoot()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ RemoveAllProperties()
|
pure virtual |
Removes all properties from the node's collection of properties.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ RemoveProperty()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ SetProperties()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ SetProperty()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
◆ WriteGameInfo()
|
pure virtual |
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.
Implemented in LibSgfcPlusPlus::SgfcNode.
The documentation for this class was generated from the following files:
- /Users/patrick/dev/libsgfcplusplus/include/ISgfcNode.h
- /Users/patrick/dev/libsgfcplusplus/src/interface/public/ISgfcNode.cpp
