nucleus/library/nodes/path.h

   1 #ifndef PATH_CLASS
   2 #define PATH_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : path                                                              *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1992-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/contracts.h>
  19 #include <basis/enhance_cpp.h>
  20 #include <basis/outcome.h>
  21
  22 namespace nodes {
  23
  24 // forward:
  25 class node;
  26 class path_node_stack;
  27
  28 //! A method for tracing a route from a tree's root to a particular node.
  29 /*!
  30   A path has a starting point at a particular node and a list of links to
  31   take from that node to another node.  For the path to remain valid, none
  32   of the links contained within it may be destroyed.
  33 */
  34
  35 class path : public virtual basis::nameable
  36 {
  37 public:
  38   path(const node *root);
  39     //!< the path is relative to the "root" node.
  40     /*!< this will be the first object pushed onto the stack that we use
  41     to model the path. */
  42
  43   path(const path &to_copy);
  44
  45   ~path();
  46
  47   DEFINE_CLASS_NAME("path");
  48
  49   path &operator =(const path &to_copy);
  50
  51   int size() const;
  52     //!< returns the number of items in the path.
  53
  54   node *root() const;
  55     //!< returns the relative root node for this path.
  56
  57   node *current() const;
  58   node *follow() const;
  59     //!< Returns the node specified by this path.
  60     /*!< if the path is not valid, NULL_POINTER is returned. */
  61
  62   node *pop();
  63     //!< returns the top node on the path stack.
  64     /*!< this returns the node at the farthest distance from the relative
  65     root node and removes it from this path. */
  66
  67   basis::outcome push(node *to_add);
  68     //!< puts the node "to_add" on the top of the stack.
  69     /*!< adds a node to the path as long as "to_add" is one of the current
  70     node's descendants. */
  71
  72   basis::outcome push(int index);
  73     //!< indexed push uses the current top node's index'th link as new top.
  74     /*!< adds the node at "index" of the current top node to the path,
  75     providing that such a link number exists on the current node. */
  76
  77   bool generate_path(node *to_locate, path &to_follow) const;
  78     //!< finds the way to get from the root to the "to_locate" node.
  79     /*!< returns true if there is a path between the relative root of
  80     this path and the node "to_locate".  if there is such a path,
  81     "to_follow" is set to one of the possible paths. */
  82
  83   node *operator [] (int index) const;
  84     //!< returns the node stored at "index", or NULL_POINTER if "index" is invalid.
  85
  86 private:
  87   path_node_stack *_stack;  //!< implementation of our pathway.
  88 };
  89
  90 } // namespace.
  91
  92 #endif
  93