collection.h
Go to the documentation of this file.
00001 /*
00002  * Copyright 2006-2008 The FLWOR Foundation.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  * 
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef ZORBA_COLLECTION_API_H
00017 #define ZORBA_COLLECTION_API_H
00018 
00019 #include <zorba/config.h>
00020 #include <zorba/api_shared_types.h>
00021 #include <zorba/item.h>
00022 
00023 namespace zorba {
00024 
00025 /** \brief A Collection is a persistent sequence of node items.
00026  *
00027  * Instances of this class can be used to modify or retrieve the contents
00028  * of a collection.
00029  *
00030  * The variable aNodes passed to any of the insert functions is evaluated
00031  * as though it were an enclosed expression in an element constructor.
00032  * The result of this step is a sequence of nodes to be inserted into the collection.
00033  *
00034  * Note: This class is reference counted. When writing multi-threaded clients,
00035  * it is the responibility of the client code to synchronize assignments to the
00036  * SmartPtr holding this object.
00037  */
00038 class ZORBA_DLL_PUBLIC Collection : public SmartObject
00039 {
00040  public:
00041   /**
00042    * \brief Get the name of the collection.
00043    *
00044    * @return The name of the collection.
00045    */
00046   virtual const Item
00047   getName() const = 0;
00048 
00049   /**
00050    * This function inserts copies of the
00051    * given nodes at the beginning of the collection.
00052    *
00053    * @param aNodes The sequences of nodes whose copies
00054    *        should be added to the collection.
00055    *
00056    */
00057   virtual void
00058   insertNodesFirst(const ItemSequence_t& aNodes) = 0;
00059   
00060   /**
00061    * This function inserts copies of the
00062    * given nodes at the end of the collection.
00063    *
00064    * @param aNodes The sequences of nodes whose copies
00065    *        should be added to the collection.
00066    *
00067    */
00068   virtual void
00069   insertNodesLast(const ItemSequence_t& aNodes) = 0;
00070   
00071   /**
00072    * This function inserts copies of the given
00073    * nodes into a collection at the position directly preceding the
00074    * given target node.
00075    *
00076    * @param aTarget the node in the collection before which the
00077    *        sequence should be inserted.
00078    * @param aNodes The sequences of nodes whose copies should
00079    *        be added to the collection.
00080    *
00081    * @throw XDDY0011 if any nodes in the sequence is not a member of a collection
00082    *        or not all nodes of the sequence belong to the same collection.
00083    *
00084    */
00085   virtual void
00086   insertNodesBefore(
00087       const Item& aTarget,
00088       const ItemSequence_t& aNodes) = 0;
00089 
00090   /**
00091    * This function inserts copies of the given
00092    * nodes into a collection at the position directly following the
00093    * given target node.
00094    *
00095    * @param aTarget the node in the collection after which the
00096    *        sequence should be inserted.
00097    * @param aNodes The sequences of nodes whose copies should
00098    *        be added to the collection.
00099    *
00100    * @throw XDDY0011 if any nodes in the sequence is not a member of a collection
00101    *        or not all nodes of the sequence belong to the same collection.
00102    *
00103    */
00104   virtual void
00105   insertNodesAfter(
00106       const Item& aTarget,
00107       const ItemSequence_t& aNodes) = 0;
00108   
00109   /**
00110    * This function deletes zero of more nodes from a collection. 
00111    *
00112    * @param aNodes the nodes in the collection that should be deleted.
00113    *
00114    * @throw XDDY0011 if any nodes in the given sequence is not a member of a collection
00115    *        or not all nodes of the sequence belong to the same collection.
00116    *
00117    */
00118   virtual void
00119   deleteNodes(const ItemSequence_t& aNodes) = 0;
00120   
00121   /**
00122    * This function deletes the first node from a collection.
00123    *
00124    * @throw XDDY0011 if the collection doesn't contain any node.
00125    *
00126    */
00127   virtual void
00128   deleteNodeFirst() = 0;
00129   
00130   /**
00131    * This function deletes the n first nodes from a collection.
00132    *
00133    * @throw XDDY0011 if the collection doesn't contain any node.
00134    *
00135    */
00136   virtual void
00137   deleteNodesFirst(unsigned long aNumNodes) = 0;
00138   
00139   /**
00140    * This function deletes the last node from a collection.
00141    *
00142    * @throw XDDY0011 if the collection doesn't contain any node.
00143    *
00144    */
00145   virtual void
00146   deleteNodeLast() = 0;
00147   
00148   /**
00149    * This function deletes the n last nodes from a collection.
00150    *
00151    * @throw XDDY0011 if the collection doesn't contain any node.
00152    *
00153    */
00154   virtual void
00155   deleteNodesLast(unsigned long aNumNodes) = 0;
00156   
00157   /**
00158    * This function returns the index of the given node in the collection.
00159    *
00160    * @param aNode The node to retrieve the index from.
00161    *
00162    * @return Returns the position of the given node in the collection.
00163    *
00164    * @throw XDDY0011 if node is not contained in any collection.
00165    *
00166    */
00167   virtual long long
00168   indexOf(const Item& aNode) = 0;
00169   
00170   /**
00171    * This function returns the sequence of nodes of the collection.
00172    *
00173    * @return The sequence contained in the given collection.
00174    *
00175    */
00176   virtual ItemSequence_t
00177   contents() = 0;
00178 
00179   /**
00180    * \brief Destructor.
00181    */
00182   virtual ~Collection() {}
00183 
00184 };
00185   
00186 } /* namespace zorba */
00187 
00188 #endif
00189 /*
00190  * Local variables:
00191  * mode: c++
00192  * End:
00193  */
00194 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus