new home directory
[feisty_meow.git] / 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