Merge branch 'release-2.140.101'
[feisty_meow.git] / nucleus / library / nodes / node.h
1 #ifndef NODE_CLASS
2 #define NODE_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : node                                                              *
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/definitions.h>
19
20 namespace nodes {
21
22 // forward:
23 class node_link_amorph;
24
25 //! An object representing the interstitial cell in most linked data structures.
26 /*!
27   The node is intended as an extensible base class that provides general
28   connectivity support.  Nodes can be connected to each other in
29   arbitrary ways, but often a derived data type provides more structured
30   organization.  When a node's link is zapped, only the connection is
31   cut; no destruction is performed.
32
33   Examples: A linked list can be represented as a node with one link that
34   connects to the succeeding item in the list.  A doubly linked list can
35   be represented by a node with two links; one to the previous node and
36   the other to the next node.  The most general structure might be an
37   arbitrary graph that can connect nodes to any number of other nodes.
38 */
39
40 class node : public virtual basis::root_object
41 {
42 public:
43   node(int number_of_links = 0);
44     //!< the constructor provides for "number_of_links" links initially.
45     /*!< the table below gives some common numbers for links for a variety of
46     data structures: @code
47     
48     Links   Data Structure             Purpose of Link(s)
49     ------  -------------------------  ----------------------------------
50       1     singly linked list         points to next node in list
51       2     doubly linked list         one to previous node, one to next
52       2     binary tree                point to the two children
53       n     n-ary tree                 point to the n children
54      n+1    n-ary doubly linked tree   point to n children and 1 parent
55       m     m-ary graph node           point to m relatives.
56     @endcode */
57
58   virtual ~node();
59     //!< the destructor simply invalidates the node.
60     /*!< this does not rearrange the links as would be appropriate for a
61     data structure in which only the node to be destroyed is being eliminated.
62     policies regarding the correct management of the links must be made in
63     objects derived from node. */
64
65   int links() const;
66     //!< Returns the number of links the node currently holds.
67
68   void set_link(int link_number, node *new_link);
69     //!< Connects the node "new_link" to this node.
70     /*!< the previous link is lost, but not modified in any way.  the address
71     of the new link is used directly--no copy of the node is made.  setting a
72     link to a null node pointer clears that link. */
73
74   node *get_link(int link_number) const;
75     //!< Returns the node that is connected to the specified "link_number".
76     /*!< if the link is not set, then NULL_POINTER is returned. */
77
78   void zap_link(int link_number);
79     //!< the specified link is removed from the node.
80
81   void insert_link(int where, node *to_add = NULL_POINTER);
82     //!< adds a new link prior to the position specified in "where".
83     /*!< thus a "where" value of less than or equal to zero will add a new
84     link as the first element.  a "where" value greater than or equal to
85     links() will add a new link after the last element.  the node "to_add"
86     will be stored in the new link. */
87
88   int which(node *to_find) const;
89     //!< locates the index where "to_find" lives in our list of links.
90     /*!< returns the link number for a particular node that is supposedly
91     connected to this node or common::NOT_FOUND if the node is not one
92     of the children. */
93
94 private:
95   node_link_amorph *_links;  //!< the list of connections to other nodes.
96
97   void set_empty(int link_number);
98     //!< clears the link number specified.
99
100   // disallowed:
101   node(const node &);
102   node &operator =(const node &);
103 };
104
105 //////////////
106
107 //! the basket class holds an object and supports connecting them as nodes.
108 /*!
109   the templated object is required to provide both a default constructor
110   and a copy constructor.
111 */
112
113 template <class contents>
114 class basket : public node
115 {
116 public:
117   basket(int links, const contents &to_store = contents())
118           : node(links), _storage(to_store) {}
119
120   basket(const basket &to_copy) { *this = to_copy; }
121
122   basket &operator = (const contents &to_copy)
123           { if (&to_copy != this) _storage = to_copy; return *this; }
124
125   const contents &stored() const { return _storage; }
126     //!< allows a peek at the stored object.
127   contents &stored() { return _storage; }
128     //!< provides access to the stored object.
129
130 private:
131   contents _storage;
132 };
133
134 } // end namespace.
135
136 #endif
137