1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2  * Copyright by The HDF Group.                                               *
3  * Copyright by the Board of Trustees of the University of Illinois.         *
4  * All rights reserved.                                                      *
5  *                                                                           *
6  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
7  * terms governing use, modification, and redistribution, is contained in    *
8  * the COPYING file, which can be found at the root of the source code       *
9  * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases.  *
10  * If you do not have access to either file, you may request a copy from     *
11  * help@hdfgroup.org.                                                        *
12  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
13 
14 #include <string>
15 
16 #include "H5Include.h"
17 #include "H5Exception.h"
18 #include "H5IdComponent.h"
19 #include "H5PropList.h"
20 #include "H5OcreatProp.h"
21 #include "H5DcreatProp.h"
22 #include "H5LcreatProp.h"
23 #include "H5LaccProp.h"
24 #include "H5DaccProp.h"
25 #include "H5Location.h"
26 #include "H5Object.h"
27 #include "H5DataType.h"
28 #include "H5AtomType.h"
29 
30 namespace H5 {
31 
32 #ifndef DOXYGEN_SHOULD_SKIP_THIS
33 //--------------------------------------------------------------------------
34 // Function:    AtomType default constructor [protected]
35 // Purpose      Default constructor: creates a stub atomic datatype.
36 // Programmer   Binh-Minh Ribler - 2000
37 //--------------------------------------------------------------------------
AtomType()38 AtomType::AtomType() : DataType() {}
39 
40 //--------------------------------------------------------------------------
41 // Function:    AtomType overloaded constructor [protected]
42 // Purpose      Creates an AtomType object using an existing id.
43 // Parameter    existing_id - IN: Id of an existing datatype
44 // Exception    H5::DataTypeIException
45 // Programmer   Binh-Minh Ribler - 2000
46 //--------------------------------------------------------------------------
AtomType(const hid_t existing_id)47 AtomType::AtomType(const hid_t existing_id) : DataType(existing_id) {}
48 
49 //--------------------------------------------------------------------------
50 // Function:    AtomType copy constructor
51 ///\brief       Copy constructor: same HDF5 object as \a original
52 // Programmer   Binh-Minh Ribler - 2000
53 //--------------------------------------------------------------------------
AtomType(const AtomType & original)54 AtomType::AtomType(const AtomType& original) : DataType(original) {}
55 #endif // DOXYGEN_SHOULD_SKIP_THIS
56 
57 //--------------------------------------------------------------------------
58 // Function:    AtomType::setSize
59 ///\brief       Sets the total size for an atomic datatype.
60 ///\param       size - IN: Size to set
61 ///\exception   H5::DataTypeIException
62 // Programmer   Binh-Minh Ribler - 2000
63 //--------------------------------------------------------------------------
setSize(size_t size) const64 void AtomType::setSize(size_t size) const
65 {
66     // Call C routine H5Tset_size to set the total size
67     herr_t ret_value = H5Tset_size(id, size);
68     if (ret_value < 0)
69     {
70         throw DataTypeIException(inMemFunc("setSize"), "H5Tset_size failed");
71     }
72 }
73 
74 //--------------------------------------------------------------------------
75 // Function:    AtomType::getOrder
76 ///\brief       Returns the byte order of an atomic datatype.
77 ///\return      Byte order, which can be:
78 ///             \li \c H5T_ORDER_LE
79 ///             \li \c H5T_ORDER_BE
80 ///             \li \c H5T_ORDER_VAX
81 ///\exception   H5::DataTypeIException
82 // Programmer   Binh-Minh Ribler - Mar, 2005
83 //--------------------------------------------------------------------------
getOrder() const84 H5T_order_t AtomType::getOrder() const
85 {
86     // Call C routine to get the byte ordering
87     H5T_order_t type_order = H5Tget_order(id);
88 
89     // return a byte order constant if successful
90     if (type_order == H5T_ORDER_ERROR)
91     {
92         throw DataTypeIException(inMemFunc("getOrder"),
93              "H5Tget_order returns H5T_ORDER_ERROR");
94     }
95    return(type_order);
96 }
97 
98 //--------------------------------------------------------------------------
99 // Function:    AtomType::getOrder
100 ///\brief       This is an overloaded member function, provided for convenience.
101 ///             It takes a reference to a \c H5std_string for the buffer that
102 ///             provide the text description of the returned byte order.
103 ///             The text description can be either of the following:
104 ///             "Little endian byte ordering (0)";
105 ///             "Big endian byte ordering (1)";
106 ///             "VAX mixed byte ordering (2)";
107 ///\param       order_string - OUT: Text description of the returned byte order
108 ///\return      Byte order, which can be:
109 ///             \li \c H5T_ORDER_LE
110 ///             \li \c H5T_ORDER_BE
111 ///             \li \c H5T_ORDER_VAX
112 ///\exception   H5::DataTypeIException
113 // Programmer   Binh-Minh Ribler - 2000
114 //--------------------------------------------------------------------------
getOrder(H5std_string & order_string) const115 H5T_order_t AtomType::getOrder(H5std_string& order_string) const
116 {
117     // Call the overloaded to get the type order without text
118     H5T_order_t type_order = getOrder();
119 
120     // Then provide the text and return the type order
121     if (type_order == H5T_ORDER_LE)
122         order_string = "Little endian byte ordering (0)";
123     else if (type_order == H5T_ORDER_BE)
124         order_string = "Big endian byte ordering (1)";
125     else if (type_order == H5T_ORDER_VAX)
126         order_string = "VAX mixed byte ordering (2)";
127     return(type_order);
128 }
129 
130 //--------------------------------------------------------------------------
131 // Function:    AtomType::setOrder
132 ///\brief       Sets the byte ordering of an atomic datatype.
133 ///\param       order - IN: Byte ordering constant, which can be:
134 ///             \li \c H5T_ORDER_LE
135 ///             \li \c H5T_ORDER_BE
136 ///             \li \c H5T_ORDER_VAX
137 ///\exception   H5::DataTypeIException
138 // Programmer   Binh-Minh Ribler - 2000
139 //--------------------------------------------------------------------------
setOrder(H5T_order_t order) const140 void AtomType::setOrder(H5T_order_t order) const
141 {
142     // Call C routine to set the byte ordering
143     herr_t ret_value = H5Tset_order(id, order);
144     if (ret_value < 0)
145     {
146         throw DataTypeIException(inMemFunc("setOrder"), "H5Tset_order failed");
147     }
148 }
149 
150 //--------------------------------------------------------------------------
151 // Function:    AtomType::getPrecision
152 ///\brief       Returns the precision of an atomic datatype.
153 ///\return      Number of significant bits
154 ///\exception   H5::DataTypeIException
155 ///\par Description
156 ///             The precision is the number of significant bits which,
157 ///             unless padding is present, is 8 times larger than the
158 ///             value returned by \c DataType::getSize().
159 // Programmer   Binh-Minh Ribler - 2000
160 //--------------------------------------------------------------------------
getPrecision() const161 size_t AtomType::getPrecision() const
162 {
163     size_t num_signi_bits = H5Tget_precision(id);  // C routine
164 
165     // returns number of significant bits if successful
166     if (num_signi_bits == 0)
167     {
168         throw DataTypeIException(inMemFunc("getPrecision"),
169              "H5Tget_precision returns invalid number of significant bits");
170     }
171     return(num_signi_bits);
172 }
173 
174 //--------------------------------------------------------------------------
175 // Function:    AtomType::setPrecision
176 ///\brief       Sets the precision of an atomic datatype.
177 ///\param       precision - IN: Number of bits of precision
178 ///\exception   H5::DataTypeIException
179 ///\par Description
180 ///             For information, please refer to the H5Tset_precision API in
181 ///             the HDF5 C Reference Manual.
182 // Programmer   Binh-Minh Ribler - 2000
183 //--------------------------------------------------------------------------
setPrecision(size_t precision) const184 void AtomType::setPrecision(size_t precision) const
185 {
186     // Call C routine to set the datatype precision
187     herr_t ret_value = H5Tset_precision(id, precision);
188     if (ret_value < 0)
189     {
190         throw DataTypeIException(inMemFunc("setPrecision"), "H5Tset_precision failed");
191     }
192 }
193 
194 //--------------------------------------------------------------------------
195 // Function:    AtomType::getOffset
196 ///\brief       Retrieves the bit offset of the first significant bit.
197 ///\return      Offset value
198 ///\exception   H5::DataTypeIException
199 ///\par Description
200 ///             For information, please refer to the H5Tget_offset API in
201 ///             the HDF5 C Reference Manual.
202 // Programmer   Binh-Minh Ribler - 2000
203 // Modification
204 //              12/05/00: due to C API change
205 //                  - return type changed from size_t to int
206 //                  - offset = -1 when failure occurs vs. 0
207 //--------------------------------------------------------------------------
getOffset() const208 int AtomType::getOffset() const
209 {
210     int offset = H5Tget_offset(id);  // C routine
211 
212     // returns a non-negative offset value if successful
213     if (offset == -1)
214     {
215         throw DataTypeIException(inMemFunc("getOffset"),
216              "H5Tget_offset returns a negative offset value");
217     }
218     return(offset);
219 }
220 
221 //--------------------------------------------------------------------------
222 // Function:    AtomType::setOffset
223 ///\brief       Sets the bit offset of the first significant bit.
224 ///\param       offset - IN: Offset of first significant bit
225 ///\exception   H5::DataTypeIException
226 ///\par Description
227 ///             For information, please refer to the H5Tset_offset API in
228 ///             the HDF5 C Reference Manual.
229 // Programmer   Binh-Minh Ribler - 2000
230 //--------------------------------------------------------------------------
setOffset(size_t offset) const231 void AtomType::setOffset(size_t offset) const
232 {
233     // Call C routine to set the bit offset
234     herr_t ret_value = H5Tset_offset(id, offset);
235     if (ret_value < 0)
236     {
237         throw DataTypeIException(inMemFunc("setOffset"), "H5Tset_offset failed");
238     }
239 }
240 
241 //--------------------------------------------------------------------------
242 // Function:    AtomType::getPad
243 ///\brief       Retrieves the padding type of the least and most-significant
244 ///             bit padding.
245 ///\param       lsb - OUT: Least-significant bit padding type
246 ///\param       msb - OUT: Most-significant bit padding type
247 ///\exception   H5::DataTypeIException
248 ///\par Description
249 ///             Possible values for \a lsb and \a msb include:
250 ///             \li \c H5T_PAD_ZERO (0) - Set background to zeros.
251 ///             \li \c H5T_PAD_ONE (1) - Set background to ones.
252 ///             \li \c H5T_PAD_BACKGROUND (2) - Leave background alone.
253 // Programmer   Binh-Minh Ribler - 2000
254 //--------------------------------------------------------------------------
getPad(H5T_pad_t & lsb,H5T_pad_t & msb) const255 void AtomType::getPad(H5T_pad_t& lsb, H5T_pad_t& msb) const
256 {
257     // Call C routine to get the padding type
258     herr_t ret_value = H5Tget_pad(id, &lsb, &msb);
259     if (ret_value < 0)
260     {
261         throw DataTypeIException(inMemFunc("getPad"), "H5Tget_pad failed");
262     }
263 }
264 
265 //--------------------------------------------------------------------------
266 // Function:    AtomType::setPad
267 ///\brief       Sets the least and most-significant bits padding types.
268 ///\param       lsb - IN: Least-significant bit padding type
269 ///\param       msb - IN: Most-significant bit padding type
270 ///\exception   H5::DataTypeIException
271 ///\par Description
272 ///             Valid values for \a lsb and \a msb include:
273 ///             \li \c H5T_PAD_ZERO (0) - Set background to zeros.
274 ///             \li \c H5T_PAD_ONE (1) - Set background to ones.
275 ///             \li \c H5T_PAD_BACKGROUND (2) - Leave background alone.
276 // Programmer   Binh-Minh Ribler - 2000
277 //--------------------------------------------------------------------------
setPad(H5T_pad_t lsb,H5T_pad_t msb) const278 void AtomType::setPad(H5T_pad_t lsb, H5T_pad_t msb) const
279 {
280     // Call C routine to set the padding type
281     herr_t ret_value = H5Tset_pad(id, lsb, msb);
282     if (ret_value < 0)
283     {
284         throw DataTypeIException(inMemFunc("setPad"), "H5Tset_pad failed");
285     }
286 }
287 
288 #ifndef DOXYGEN_SHOULD_SKIP_THIS
289 //--------------------------------------------------------------------------
290 // Function:    AtomType destructor
291 ///\brief       Noop destructor.
292 // Programmer   Binh-Minh Ribler - 2000
293 //--------------------------------------------------------------------------
~AtomType()294 AtomType::~AtomType() {}
295 #endif // DOXYGEN_SHOULD_SKIP_THIS
296 
297 } // end namespace
298