1 /*========================================================================= 2 * 3 * Copyright Insight Software Consortium 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0.txt 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 *=========================================================================*/ 18 #ifndef itkIndexedContainerInterface_h 19 #define itkIndexedContainerInterface_h 20 21 #include "itkObject.h" 22 23 namespace itk 24 { 25 /** \class IndexedContainerInterface 26 * \brief This should only be used for reference when writing containers 27 * conforming to this interface. 28 * This should only be used for reference when writing containers 29 * conforming to this interface. ITK uses generic programming to 30 * allow container type substitution, so polymorphism is not needed to 31 * use containers through this interface. This means that a container 32 * conforming to this interface need not be derived from it, and that 33 * their methods should not be virtual. However, the container must 34 * derive from Object in order to support the reference counting, 35 * modification time, and debug information required by this 36 * interface. 37 * 38 * Note that many comments refer to a "default element" or "default element 39 * value". This value is equal to the default constructor of the 40 * Element type. Also note that all non-const methods assume that the 41 * container was modified, and update the modification time. 42 * 43 * \tparam TElementIdentifier A type that shall be used to index the 44 * container. It must have a < operator defined for ordering. 45 * 46 * \tparam TElement The element type stored in the container. 47 * 48 * \ingroup DataRepresentation 49 * \ingroup ITKCommon 50 */ 51 52 template< typename TElementIdentifier, typename TElement > 53 class IndexedContainerInterface:public Object 54 { 55 public: 56 /** Standard class type aliases. */ 57 using Self = IndexedContainerInterface; 58 using Superclass = Object; 59 using Pointer = SmartPointer< Self >; 60 using ConstPointer = SmartPointer< const Self >; 61 62 /** Standard part of every itk Object. */ 63 itkTypeMacro(IndexedContainerInterface, Object); 64 65 /** Save the template parameters. */ 66 using ElementIdentifier = TElementIdentifier; 67 using Element = TElement; 68 69 /** Get a reference to an existing element. 70 * It is NOT guaranteed that the element will or will not be created if it 71 * doesn't exist. This behavior is implementation-specific. 72 * 73 * It is assumed that the value of the element is modified through the 74 * reference. */ 75 Element & ElementAt(ElementIdentifier); 76 77 /** Get a reference to an existing element. 78 * It is guaranteed that the element will be inserted with a default 79 * value if it does not exist. 80 * 81 * It is assumed that the value of the element is modified through the 82 * reference. */ 83 Element & CreateElementAt(ElementIdentifier); 84 85 /** Get a copy of an element without range checking. */ 86 Element GetElement(ElementIdentifier) const; 87 88 /** Set the value of an element. 89 * It is NOT guaranteed whether a spot for the element will be created 90 * automatically. This is implementation-defined. */ 91 void SetElement(ElementIdentifier, Element); 92 93 /** Set the value of an element. 94 * It is guaranteed that a spot for the element will be created if it 95 * doesn't exist. */ 96 void InsertElement(ElementIdentifier, Element); 97 98 /** Test if there is an entry in the container corresponding to the given 99 * index. */ 100 bool IndexExists(ElementIdentifier) const; 101 102 /** Combine the GetElement and IndexExists into one method. 103 * If false is returned, then no element with the given identifier was found. 104 * If true is returned, then the identifier was found. In this case, 105 * if the element pointer given as input is not null, the element is filled 106 * in with the value of the element found. */ 107 bool GetElementIfIndexExists(ElementIdentifier, Element *) const; 108 109 /** Create an entry in the container corresponding to the given index. 110 * The entry will be initialized with the default element. 111 * If an entry already exists, its value will be overwritten with the 112 * default element. */ 113 void CreateIndex(ElementIdentifier); 114 115 /** Delete the entry in the container corresponding to the given identifier. 116 * 117 * It is NOT guaranteed that IndexExists(id) will return false if called 118 * right after DeleteIndex(id). This behavior is implementation-defined. 119 * If the identifier's location is left behind, though, it will have the 120 * value of the default element. */ 121 void DeleteIndex(ElementIdentifier); 122 123 /** \class Iterator 124 * \brief Support iteration operations through a container. 125 * Dereferencing the iterator must provide an object with the following 126 * methods: 127 * ElementIdentifier Index() const; 128 * Element& Value(); 129 * \ingroup ITKCommon 130 */ 131 class Iterator {}; 132 133 /** \class ConstIterator 134 * \brief Support const iteration operations through a container. 135 * Dereferencing the iterator must provide an object with the following 136 * methods: 137 * ElementIdentifier Index() const; 138 * const Element& Value() const; 139 * \ingroup ITKCommon 140 */ 141 class ConstIterator {}; 142 143 /** Get a begin iterator for the container. */ 144 Iterator Begin(); 145 146 /** Get an end iterator for the container. */ 147 Iterator End(); 148 149 /** Get a begin const iterator for the container. */ 150 ConstIterator Begin() const; 151 152 /** Get an end const iterator for the container. */ 153 ConstIterator End() const; 154 155 /** Get the number of elements currently stored in the container. */ 156 ElementIdentifier Size() const; 157 158 /** Tell the container to allocate enough memory to allow at least 159 * as many elements as the size given to be stored. This is NOT 160 * guaranteed to actually allocate any memory, but is useful if the 161 * implementation of the container allocates contiguous storage. */ 162 void Reserve(ElementIdentifier); 163 164 /** Tell the container to try to minimize its memory usage for storage of 165 * the current number of elements. This is NOT guaranteed to decrease 166 * memory usage. */ 167 void Squeeze(); 168 169 /** Tell the container to release any memory it may have allocated and 170 * return itself to its initial state. */ 171 void Initialize(); 172 }; 173 } // end namespace itk 174 175 #endif 176