gum::detail Namespace Reference

Enumerations
enum class	FastGraphOp : std::uint8_t { None , Arc , RevArc , Edge }
	which operator (if any) precedes a node token in a fastGraph chain More...

Functions
std::size_t	fastGraphFindDash (std::string_view chain, std::size_t from)
	Finds the first '-' at bracket-depth 0, starting at from, skipping any '['...']' or '{'...'}' span.
std::vector< std::pair< std::string, FastGraphOp > >	fastGraphTokenize (std::string_view chain)
	Scans one ";"-delimited chain, splitting it into node tokens while remembering, for each token, whether it was preceded by "->" (Arc), "<-" (RevArc) or "-" (Edge).
bool	fastGraphIsNodeIdToken (const std::string &token)
	true if token must be read as a NodeId (non-negative integer)
template<typename GRAPH_TYPE>
NodeId	fastGraphBuildNode (GRAPH_TYPE &g, const std::string &token, bool useIds)
	gets or creates the node denoted by token, in NodeId or name mode
template<typename Resolve, typename AddArc, typename AddEdge>
void	fastGraphWalkTokens (const std::vector< std::pair< std::string, FastGraphOp > > &tokens, std::string_view desc, Resolve resolve, AddArc addArc, AddEdge addEdge)
	Walks one already-tokenized chain (see fastGraphTokenize()), resolving each token to a NodeId via resolve and wiring consecutive nodes via addArc / addEdge according to the operator preceding each token.

Enumeration Type Documentation

FastGraphOp

enum class gum::detail::FastGraphOp : std::uint8_t

strong

which operator (if any) precedes a node token in a fastGraph chain

Enumerator
None
Arc
RevArc
Edge

Definition at line 58 of file fastGraph_tpl.h.

: std::uint8_t { None, Arc, RevArc, Edge };

Function Documentation

fastGraphBuildNode()

template<typename GRAPH_TYPE>

NodeId gum::detail::fastGraphBuildNode	(	GRAPH_TYPE &	g,
		const std::string &	token,
		bool	useIds )

gets or creates the node denoted by token, in NodeId or name mode

Definition at line 138 of file fastGraph_tpl.h.

                                                                                  {
      if (useIds) {
        int value = 0;
        isIntegerWithResult(token, &value);
        const auto id = static_cast< NodeId >(value);
        if (!g.existsNode(id)) { g.addNodeWithId(id); }
        return id;
      }
 
      if (const auto id = g.idFromName(token)) { return *id; }
      const NodeId id = g.addNode();
      g.setName(id, token);
      return id;
    }

References gum::isIntegerWithResult().

Here is the call graph for this function:

fastGraphFindDash()

std::size_t gum::detail::fastGraphFindDash ( std::string_view chain, std::size_t from )

inline

Finds the first '-' at bracket-depth 0, starting at from, skipping any '['...']' or '{'...'}' span.

Node tokens built downstream by BayesNet/InfluenceDiagram's fastPrototype() may embed a fastVariable domain descriptor, e.g. "A[-3,3]" (negative range) or "B{-1.5:6.3:5}" (negative ticks): the '-' there is part of a number, not a topology operator, so it must not be mistaken for one.

Definition at line 69 of file fastGraph_tpl.h.

                                                                             {
      int depth = 0;
      for (std::size_t i = from; i < chain.size(); ++i) {
        const char c = chain[i];
        if (c == '[' || c == '{') {
          ++depth;
        } else if (c == ']' || c == '}') {
          if (depth > 0) --depth;
        } else if ((c == '-') && (depth == 0)) {
          return i;
        }
      }
      return std::string_view::npos;
    }

Referenced by fastGraphTokenize().

Here is the caller graph for this function:

fastGraphIsNodeIdToken()

bool gum::detail::fastGraphIsNodeIdToken ( const std::string & token )

inline

true if token must be read as a NodeId (non-negative integer)

Definition at line 131 of file fastGraph_tpl.h.

                                                               {
      int value = 0;
      return isIntegerWithResult(token, &value) && (value >= 0);
    }

References gum::isIntegerWithResult().

Here is the call graph for this function:

fastGraphTokenize()

std::vector< std::pair< std::string, FastGraphOp > > gum::detail::fastGraphTokenize ( std::string_view chain )

inline

Scans one ";"-delimited chain, splitting it into node tokens while remembering, for each token, whether it was preceded by "->" (Arc), "<-" (RevArc) or "-" (Edge).

A plain split() cannot preserve this, since it only handles one delimiter at a time.

"-" (not "--") is used for edges: MRF's own fast syntax already uses "--" to list the variables of a single factor (a clique), which is a different construct from a chain of pairwise edges. Reusing "--" here would silently give the same token two incompatible meanings.

Definition at line 96 of file fastGraph_tpl.h.

                                                {
      std::vector< std::pair< std::string, FastGraphOp > > tokens;
      std::size_t                                          pos       = 0;
      FastGraphOp                                          pendingOp = FastGraphOp::None;
 
      while (pos <= chain.size()) {
        const auto dashPos = fastGraphFindDash(chain, pos);
 
        std::size_t opStart = dashPos;
        std::size_t opLen   = 1;
        FastGraphOp op      = FastGraphOp::Edge;
 
        if (dashPos != std::string_view::npos) {
          if ((dashPos + 1 < chain.size()) && (chain[dashPos + 1] == '>')) {
            opLen = 2;
            op    = FastGraphOp::Arc;
          } else if ((dashPos > pos) && (chain[dashPos - 1] == '<')) {
            opStart = dashPos - 1;
            opLen   = 2;
            op      = FastGraphOp::RevArc;
          }
        }
 
        const auto tokEnd = (dashPos == std::string_view::npos) ? chain.size() : opStart;
 
        tokens.emplace_back(trim_copy(chain.substr(pos, tokEnd - pos)), pendingOp);
 
        if (dashPos == std::string_view::npos) { break; }
        pendingOp = op;
        pos       = opStart + opLen;
      }
      return tokens;
    }

References Arc, Edge, fastGraphFindDash(), None, RevArc, and gum::trim_copy().

Here is the call graph for this function:

fastGraphWalkTokens()

template<typename Resolve, typename AddArc, typename AddEdge>

void gum::detail::fastGraphWalkTokens	(	const std::vector< std::pair< std::string, FastGraphOp > > &	tokens,
		std::string_view	desc,
		Resolve	resolve,
		AddArc	addArc,
		AddEdge	addEdge )

Walks one already-tokenized chain (see fastGraphTokenize()), resolving each token to a NodeId via resolve and wiring consecutive nodes via addArc / addEdge according to the operator preceding each token.

This is the shared topology grammar behind fastGraph(), BayesNet::fastPrototype() and InfluenceDiagram::fastPrototype(): what a "node" is (a bare graph node, a chance/utility/ decision DiscreteVariable, ...) is entirely delegated to resolve, so callers with no notion of undirected edges (BayesNet, InfluenceDiagram) can simply pass an addEdge that throws.

Parameters

tokens	the chain, as produced by fastGraphTokenize().
desc	the full original description, only used to report errors.
resolve	NodeId resolve(const std::string& token): gets or creates the node denoted by a raw token.
addArc	void addArc(NodeId tail, NodeId head, const std::string& token): wires a directed arc; token is the node that carried the "->"/"<-" operator, for error messages.
addEdge	void addEdge(NodeId a, NodeId b, const std::string& token): wires an undirected edge; same token convention.

Exceptions

InvalidArc

if desc is malformed (an operator without a following node token).

Definition at line 176 of file fastGraph_tpl.h.

                                                                                                  {
      NodeId lastId = 0;
      bool   first  = true;
 
      for (const auto& [token, op]: tokens) {
        if (token.empty()) {
          GUM_ERROR(InvalidArc,
                    "fastGraph: malformed description '" << desc
                                                         << "' (operator without a node token)")
        }
        const NodeId id = resolve(token);
 
        if (!first) {
          if (op == FastGraphOp::Arc) {
            addArc(lastId, id, token);
          } else if (op == FastGraphOp::RevArc) {
            addArc(id, lastId, token);
          } else {
            addEdge(lastId, id, token);
          }
        }
 
        lastId = id;
        first  = false;
      }
    }

References Arc, GUM_ERROR, and RevArc.