00001 // SpecimenBlock.h 00002 00003 #ifndef SPECIMENBLOCK_H 00004 #define SPECIMENBLOCK_H 00005 00006 #include "Block.h" 00007 #include "Specimen.h" 00008 00009 #include <vector> 00010 #include <list> 00011 #include <iostream> 00012 #include <sstream> 00013 00014 namespace Yosokumo 00015 { 00016 00017 /** 00018 * A block of <code>Specimen*</code>. Note that a <code>SpecimenBlock</code> 00019 * does not own the <code>Specimens</code> pointed to by the elements of the 00020 * <code>SpecimenBlock</code>. This class never constructs or destroys a 00021 * <code>Specimen</code>. 00022 */ 00023 class SpecimenBlock : public Block 00024 { 00025 // At present the specimenSequence list is implemented as a 00026 // vector<Specimen*> because this implementation has O(1) performance 00027 // for all three of "get", "add", and "next". The latter is used to 00028 // iterate over the list, and thus we do not want it to be expensive. 00029 // The "add" method appends to the end of the list. -- Essentially, we 00030 // want an array which can grow in size. 00031 00032 // The sequence is defined in Block.h 00033 00034 public: 00035 00036 // Constructors 00037 00038 /** 00039 * Initializes a newly created <code>SpecimenBlock</code> object with 00040 * default attributes. 00041 */ 00042 SpecimenBlock(); 00043 00044 /** 00045 * Initializes a newly created <code>SpecimenBlock</code> object with a 00046 * study identifier. 00047 * 00048 * @param id a study identifier for the block. 00049 */ 00050 SpecimenBlock(std::string id); 00051 00052 /** 00053 * Initializes a newly created <code>SpecimenBlock</code> object with the 00054 * Specimen vector specified by the input parameters. Note that the 00055 * Specimens *must* not be deleted while the SpecimenBlock exists. 00056 * 00057 * @param begin an iterator specifying the beginning of the Specimen 00058 * vector. 00059 * @param end an iterator specifying the end of the Specimen 00060 * vector. 00061 */ 00062 SpecimenBlock( 00063 std::vector<Specimen>::iterator begin, 00064 std::vector<Specimen>::iterator end); 00065 00066 /** 00067 * Initializes a newly created <code>SpecimenBlock</code> object with the 00068 * Specimen list specified by the input parameters. Note that the 00069 * Specimens *must* not be deleted while the SpecimenBlock exists. 00070 * 00071 * @param begin an iterator specifying the beginning of the Specimen 00072 * list. 00073 * @param end an iterator specifying the end of the Specimen 00074 * list. 00075 */ 00076 SpecimenBlock( 00077 std::list<Specimen>::iterator begin, 00078 std::list<Specimen>::iterator end); 00079 00080 /** 00081 * Initializes a newly created <code>SpecimenBlock</code> object with the 00082 * study identifier and the Specimen vector specified by the input 00083 * parameters. Note that the Specimens *must* not be deleted while the 00084 * SpecimenBlock exists. 00085 * 00086 * @param id a study identifier for the block. 00087 * @param begin an iterator specifying the beginning of the Specimen 00088 * vector. 00089 * @param end an iterator specifying the end of the Specimen 00090 * vector. 00091 */ 00092 SpecimenBlock( 00093 std::string id, 00094 std::vector<Specimen>::iterator begin, 00095 std::vector<Specimen>::iterator end); 00096 00097 /** 00098 * Initializes a newly created <code>SpecimenBlock</code> object with the 00099 * study identifier and the Specimen list specified by the input 00100 * parameters. Note that the Specimens *must* not be deleted while the 00101 * SpecimenBlock exists. 00102 * 00103 * @param id a study identifier for the block. 00104 * @param begin an iterator specifying the beginning of the Specimen 00105 * list. 00106 * @param end an iterator specifying the end of the Specimen 00107 * list. 00108 */ 00109 SpecimenBlock( 00110 std::string id, 00111 std::list<Specimen>::iterator begin, 00112 std::list<Specimen>::iterator end); 00113 00114 /** 00115 * Destructor. 00116 */ 00117 virtual ~SpecimenBlock(); 00118 00119 private: 00120 00121 /** 00122 * Copy constructor - NOT IMPLEMENTED. 00123 */ 00124 SpecimenBlock(const SpecimenBlock &rhs); 00125 00126 /** 00127 * Assignment operator - NOT IMPLEMENTED. 00128 */ 00129 SpecimenBlock& operator=(const SpecimenBlock& rhs); 00130 00131 public: 00132 00133 // Access to the specimen sequence 00134 00135 /** 00136 * Add a <code>Specimen*</code> to the block. The Specimen* parameter is 00137 * appended to the end of the Specimen* sequence. 00138 * 00139 * @param specimen the <code>Specimen*</code> to add to the block. 00140 */ 00141 void addSpecimen(Specimen* specimen); 00142 00143 00144 /** 00145 * Add a collection of <code>Specimen</code> to the block. The 00146 * <code>Specimen</code> in the vector specified by the parameters are 00147 * appended to the end of the Specimen* sequence. Note that the Specimens 00148 * *must* not be deleted while the SpecimenBlock exists. 00149 * 00150 * @param begin an iterator specifying the beginning of the Specimen 00151 * vector to add to the block. 00152 * @param end an iterator specifying the end of the Specimen 00153 * vector to add to the block. 00154 * 00155 * @return true if and only if the Specimen* sequence changes. 00156 */ 00157 bool addSpecimens( 00158 std::vector<Specimen>::iterator begin, 00159 std::vector<Specimen>::iterator end); 00160 00161 /** 00162 * Add a collection of <code>Specimen</code> to the block. The 00163 * <code>Specimen</code> in the list specified by the parameter are 00164 * appended to the end of the Specimen* sequence. Note that the Specimens 00165 * *must* not be deleted while the SpecimenBlock exists. 00166 * 00167 * @param begin an iterator specifying the beginning of the Specimen 00168 * list to add to the block. 00169 * @param end an iterator specifying the end of the Specimen 00170 * list to add to the block. 00171 * 00172 * @return true if and only if the Specimen* sequence changes. 00173 */ 00174 bool addSpecimens( 00175 std::list<Specimen>::iterator begin, 00176 std::list<Specimen>::iterator end); 00177 00178 /** 00179 * Remove Specimen* from the end of the block. The specified number of 00180 * specimens are removed from the end of the Specimen* sequence. 00181 * 00182 * @param numSpecimensToRemove is the number of specimens to remove 00183 * from the end of the block. If this value is zero, 00184 * no specimens are removed. If this value exceeds the number 00185 * of specimens in the block, then all specimens are removed. 00186 * 00187 * @return true if and only if the sequence is changed. 00188 */ 00189 bool removeSpecimens(uint64_t numSpecimensToRemove); 00190 00191 00192 /** 00193 * Return a Specimen* from the block. This makes it possible to iterate 00194 * over all specimens in the sequence like this: 00195 * <pre> 00196 * for (int i = 0; i < specimenBlock.size(); ++i) 00197 * { 00198 * Specimen *c = specimenBlock.getSpecimen(i) 00199 * process specimen *c 00200 * } 00201 * </pre> 00202 * 00203 * @param index specifying the Specimen* of the 0-based block. 00204 * 00205 * @return the <code>Specimen*</code> at the location specified by the index. 00206 */ 00207 Specimen *getSpecimen(uint64_t index) const; 00208 00209 00210 /** 00211 * Remove all Specimen* from the block. After a call of this method, 00212 * the sequence is empty, i.e., it contains no specimens. 00213 * 00214 */ 00215 void clearSpecimens(); 00216 00217 /** 00218 * Return the number of specimens in the block. 00219 * 00220 * @return the number of specimens in the block. 00221 */ 00222 uint64_t size() const; 00223 00224 /** 00225 * Return <code>true</code> if the block contains no specimens. 00226 * 00227 * @return <code>true</code> if the block contains no specimens. 00228 * <code>false</code> otherwise. 00229 */ 00230 bool isEmpty() const; 00231 00232 00233 // Utility 00234 00235 /** 00236 * Return a string representation of this <code>SpecimenBlock</code>. 00237 * 00238 * @return the string representation of this <code>SpecimenBlock</code>. 00239 */ 00240 virtual std::string toString(); 00241 00242 }; // end class SpecimenBlock 00243 00244 } // end namespace Yosokumo 00245 00246 00247 /** Output stream insertion operator. 00248 * 00249 * @param os the output stream. 00250 * @param sb the <code>SpecimenBlock</code> to insert in the stream. 00251 * 00252 * @return the output stream. 00253 */ 00254 std::ostream &operator<<(std::ostream &os, Yosokumo::SpecimenBlock &sb); 00255 00256 /** String stream insertion operator. 00257 * 00258 * @param s the string stream. 00259 * @param sb the <code>SpecimenBlock</code> to insert in the stream. 00260 * 00261 * @return the string stream. 00262 */ 00263 std::stringstream &operator<<(std::stringstream &s, Yosokumo::SpecimenBlock &sb); 00264 00265 #endif // SPECIMENBLOCK_H 00266 00267 // end SpecimenBlock.h