ByteArray.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
2 
3  This file is part of the TerraLib - a Framework for building GIS enabled applications.
4 
5  TerraLib is free software: you can redistribute it and/or modify
6  it under the terms of the GNU Lesser General Public License as published by
7  the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  TerraLib is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public License
16  along with TerraLib. See COPYING. If not, write to
17  TerraLib Team at <terralib-team@terralib.org>.
18  */
19 
20 /*!
21  \file terralib/datatype/ByteArray.h
22 
23  \brief A class for representing binary data.
24 */
25 
26 #ifndef __TERRALIB_DATATYPE_INTERNAL_BYTEARRAY_H
27 #define __TERRALIB_DATATYPE_INTERNAL_BYTEARRAY_H
28 
29 // TerraLib
30 #include "AbstractData.h"
31 #include "Enums.h"
32 
33 // Boost
34 #include <boost/cstdint.hpp>
35 
36 namespace te
37 {
38  namespace dt
39  {
40  /*!
41  \class ByteArray
42 
43  \brief A class for representing binary data.
44 
45  A byte array can be used as a container for binary data.
46 
47  \ingroup datatype
48 
49  \sa AbstractData, DataType, DateTime, SimpleData, CompositeData
50  */
51  class TEDATATYPEEXPORT ByteArray : public AbstractData
52  {
53  public:
54 
55  /*! \brief It creates a new empty byte array. */
56  ByteArray();
57 
58  /*!
59  \brief It creates a new byte array and allocates size bytes.
60 
61  \param capacity The number of bytes for the internal data buffer.
62  */
63  ByteArray(std::size_t capacity);
64 
65  /*!
66  \brief It creates a new byte array taking the ownership of the external data buffer.
67 
68  \param data The data array.
69  \param size The number of bytes in the data array. This value will be also the capacity of the byte array buffer.
70 
71  \note The byte array will take the ownership of the given data.
72  */
73  ByteArray(char* data, std::size_t size);
74 
75  /*!
76  \brief It creates a new byte array taking the ownership of the external data buffer.
77 
78  \param data The data array.
79  \param capacity The number of bytes available in the data buffer, it must be greater than or equal to usedBytes.
80  \param usedBytes The number of used bytes in the given data buffer.
81 
82  \note The byte array will take the ownership of the given data.
83  */
84  ByteArray(char* data, std::size_t capacity, std::size_t usedBytes);
85 
86  /*!
87  \brief Copy constructor.
88 
89  \param rhs The right-hand-side instance.
90  */
91  ByteArray(const ByteArray& rhs);
92 
93  /*!
94  \brief Assignment operator.
95 
96  \param rhs The right-hand-side instance.
97 
98  \return A reference to this byte array.
99  */
100  ByteArray& operator=(const ByteArray& rhs);
101 
102  /*! \brief Destructor. */
103  ~ByteArray();
104 
105  /*!
106  \brief It returns the data array.
107 
108  \return The data array.
109 
110  \note Don't free the returned pointer (it belongs to the byte array object).
111  */
112  char* getData() const;
113 
114  /*!
115  \brief It takes the ownership of the external data buffer.
116 
117  \param data The data array.
118  \param size The number of bytes in the array of data. This value will be also the capacity of the byte array buffer.
119 
120  \note The byte array will take the ownership of the given data.
121 
122  \note It will drop the internal buffer before taking the data argument.
123  */
124  void take(char* data, std::size_t size);
125 
126  /*!
127  \brief It takes the ownership of the external data buffer.
128 
129  \param data The data array.
130  \param capacity The number of bytes available in the data buffer, it must be greater than or equal to usedBytes.
131  \param usedBytes The number of used bytes in the given data buffer.
132 
133  \note The byte array will take the ownership of the given data.
134 
135  \note It will drop the internal buffer before taking the data argument.
136  */
137  void take(char* data, std::size_t capacity, std::size_t usedBytes);
138 
139  /*!
140  \brief It copies the data from the given pointer to the byte array.
141 
142  \param data The data array to be copied.
143  \param size The number of bytes to be copied from the input array.
144 
145  \note It will drop the internal buffer if its capacity is less than size bytes.
146  */
147  void copy(char* data, std::size_t size);
148 
149  /*!
150  \brief It copies the data from the given pointer to the byte array.
151 
152  \param data The data array to be copied.
153  \param size The number of bytes to be copied from the input array.
154  \param offset An offset in the internal data buffer.
155 
156  \note It will expand the internal buffer if its capacity is less than offset + size bytes.
157 
158  \note After this operation the number of bytes ocupied will be set to offset + size.
159  */
160  void copy(char* data, std::size_t size, std::size_t offset);
161 
162  /*!
163  \brief It returns the size of the internal buffer.
164 
165  \return The number of bytes in the internal buffer.
166  */
167  std::size_t capacity() const;
168 
169  /*!
170  \brief It returns the number of used bytes in the internal buffer.
171 
172  \return The number of used bytes in the internal buffer.
173  */
174  std::size_t bytesUsed() const;
175 
176  /*!
177  \brief It sets the number of used bytes in the internal buffer.
178 
179  \param size The number of used bytes in the internal buffer.
180  */
181  void setBytesUsed(std::size_t size);
182 
183  /*! \brief It clears the byte array. */
184  void clear();
185 
186  /*!
187  \brief It creates a new clone of the byte array
188 
189  \return A new clone of the byte array. The caller will take its ownership.
190  */
191  AbstractData* clone() const;
192 
193  /*!
194  \brief The type code for byte array data: BYTE_ARRAY_TYPE.
195 
196  \return The type code for byte array data: BYTE_ARRAY_TYPE.
197  */
198  int getTypeCode() const { return BYTE_ARRAY_TYPE; }
199 
200  /*!
201  \brief It returns the byte array in an string notation.
202 
203  \return An hex-string encoded version of the internal data buffer.
204 
205  \todo Remove the copy and allocation overhead in this method.
206  */
207  std::string toString() const;
208 
209  private:
210 
211  char* m_data; //!< The buffer data.
212  std::size_t m_capacity; //!< The number of bytes allocated by the internal buffer.
213  std::size_t m_bytesOccupied; //!< The number of bytes occupied in the buffer.
214  };
215 
216  } // end namespace dt
217 } // end namespace te
218 
219 /*!
220  \brief It writes the bytes from val to the byte array.
221 
222  \param barray A byte array container.
223  \param val A simple data type value like: an int, a double or a float.
224 
225  \return The byte array.
226 */
227 template<class T> inline te::dt::ByteArray& operator<<(te::dt::ByteArray& barray, T val)
228 {
229  barray.copy((char*)(&val), sizeof(T), barray.bytesUsed());
230 
231  return barray;
232 }
233 
234 
235 #endif // __TERRALIB_DATATYPE_INTERNAL_BYTEARRAY_H
236 
237 
238 
AbstractData.h
A base class for objects that can be retrieved from the data access module.
operator<<
te::dt::ByteArray & operator<<(te::dt::ByteArray &barray, T val)
It writes the bytes from val to the byte array.
Definition: ByteArray.h:227
te::dt::AbstractData
A base class for values that can be retrieved from the data access module.
Definition: AbstractData.h:56
te::dt::ByteArray
A class for representing binary data.
Definition: ByteArray.h:52
te::dt::ByteArray::ByteArray
ByteArray(std::size_t capacity)
It creates a new byte array and allocates size bytes.
te::dt::ByteArray::ByteArray
ByteArray(const ByteArray &rhs)
Copy constructor.
te::dt::ByteArray::m_capacity
std::size_t m_capacity
The number of bytes allocated by the internal buffer.
Definition: ByteArray.h:212
te::dt::ByteArray::capacity
std::size_t capacity() const
It returns the size of the internal buffer.
te::dt::ByteArray::copy
void copy(char *data, std::size_t size, std::size_t offset)
It copies the data from the given pointer to the byte array.
te::dt::ByteArray::getTypeCode
int getTypeCode() const
The type code for byte array data: BYTE_ARRAY_TYPE.
Definition: ByteArray.h:198
te::dt::ByteArray::take
void take(char *data, std::size_t size)
It takes the ownership of the external data buffer.
te::dt::ByteArray::m_bytesOccupied
std::size_t m_bytesOccupied
The number of bytes occupied in the buffer.
Definition: ByteArray.h:213
te::dt::ByteArray::bytesUsed
std::size_t bytesUsed() const
It returns the number of used bytes in the internal buffer.
te::dt::ByteArray::ByteArray
ByteArray()
It creates a new empty byte array.
te::dt::ByteArray::m_data
char * m_data
The buffer data.
Definition: ByteArray.h:211
te::dt::ByteArray::ByteArray
ByteArray(char *data, std::size_t size)
It creates a new byte array taking the ownership of the external data buffer.
te::dt::ByteArray::ByteArray
ByteArray(char *data, std::size_t capacity, std::size_t usedBytes)
It creates a new byte array taking the ownership of the external data buffer.
te::dt::ByteArray::clear
void clear()
It clears the byte array.
te::dt::ByteArray::operator=
ByteArray & operator=(const ByteArray &rhs)
Assignment operator.
te::dt::ByteArray::copy
void copy(char *data, std::size_t size)
It copies the data from the given pointer to the byte array.
te::dt::ByteArray::setBytesUsed
void setBytesUsed(std::size_t size)
It sets the number of used bytes in the internal buffer.
te::dt::ByteArray::take
void take(char *data, std::size_t capacity, std::size_t usedBytes)
It takes the ownership of the external data buffer.
te::dt::ByteArray::getData
char * getData() const
It returns the data array.
te::dt::ByteArray::~ByteArray
~ByteArray()
Destructor.
te::dt::ByteArray::toString
std::string toString() const
It returns the byte array in an string notation.
te::dt::ByteArray::clone
AbstractData * clone() const
It creates a new clone of the byte array.
te::dt::BYTE_ARRAY_TYPE
@ BYTE_ARRAY_TYPE
Definition: Enums.h:201
te
TerraLib.
Definition: AddressGeocodingOp.h:52
TEDATATYPEEXPORT
#define TEDATATYPEEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:61
Enums.h
Enumerations of XML module.