HexUtils.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/common/HexUtils.h
22 
23  \brief This file contains several utilities functions for dealing with HEX strings.
24 
25  \ingroup common
26 */
27 
28 #ifndef __TERRALIB_COMMON_INTERNAL_HEXUTILS_H
29 #define __TERRALIB_COMMON_INTERNAL_HEXUTILS_H
30 
31 // STL
32 #include <cstring>
33 #include <map>
34 #include <vector>
35 
36 namespace te
37 {
38  namespace common
39  {
40  /*!
41  \brief It returns the decimal value in a char from a given hex value (for example: 'A' => 10, '8' => 8).
42 
43  \param hexValue The hex value we want to extract the decimal value.
44 
45  \return The decimal value in a char from a given hex value (for example: 'A' => 10, '8' => 8).
46 
47  \note This version is not case sensitive, i. e., 'A' and 'a' will return 10.
48  */
49  inline unsigned char GetDecimalFromHexNotCS(unsigned char hexValue)
50  {
51  switch(hexValue)
52  {
53  case '0':
54  return 0;
55 
56  case '1':
57  return 1;
58 
59  case '2':
60  return 2;
61 
62  case '3':
63  return 3;
64 
65  case '4':
66  return 4;
67 
68  case '5':
69  return 5;
70 
71  case '6':
72  return 6;
73 
74  case '7':
75  return 7;
76 
77  case '8':
78  return 8;
79 
80  case '9':
81  return 9;
82 
83  case 'A':
84  case 'a':
85  return 10;
86 
87  case 'B':
88  case 'b':
89  return 11;
90 
91  case 'C':
92  case 'c':
93  return 12;
94 
95  case 'D':
96  case 'd':
97  return 13;
98 
99  case 'E':
100  case 'e':
101  return 14;
102 
103  //case 'F':
104  //case 'f':
105  default:
106  return 15;
107  }
108  }
109 
110  /*!
111  \brief It returns the decimal value in a char from a given hex value (for example: 'A' => 10, '8' => 8).
112 
113  \param hexValue The hex value we want to extract the decimal value.
114 
115  \return The decimal value in a char from a given hex value (for example: 'A' => 10, '8' => 8).
116 
117  \note This version is upper case sensitive, i. e., 'A' will return 10 and 'a' will return a wrong value.
118  */
119  inline unsigned char GetDecimalFromHexUCase(char hexValue)
120  {
121  switch(hexValue)
122  {
123  case '0':
124  return 0;
125 
126  case '1':
127  return 1;
128 
129  case '2':
130  return 2;
131 
132  case '3':
133  return 3;
134 
135  case '4':
136  return 4;
137 
138  case '5':
139  return 5;
140 
141  case '6':
142  return 6;
143 
144  case '7':
145  return 7;
146 
147  case '8':
148  return 8;
149 
150  case '9':
151  return 9;
152 
153  case 'A':
154  return 10;
155 
156  case 'B':
157  return 11;
158 
159  case 'C':
160  return 12;
161 
162  case 'D':
163  return 13;
164 
165  case 'E':
166  return 14;
167 
168  //case 'F':
169  default:
170  return 15;
171  }
172  }
173 
174  /*!
175  \fn unsigned char GetDecimalFromHexLCase(char hexValue)
176 
177  \brief It returns the decimal value in a char from a given hex value (for example: 'a' => 10, '8' => 8).
178 
179  \param hexValue The hex value we want to extract the decimal value.
180 
181  \return The decimal value in a char from a given hex value (for example: 'a' => 10, '8' => 8).
182 
183  \note This version is lower case sensitive, i. e., 'a' will return 10 and 'A' will return a wrong value.
184  */
185  inline unsigned char GetDecimalFromHexLCase(char hexValue)
186  {
187  switch(hexValue)
188  {
189  case '0':
190  return 0;
191 
192  case '1':
193  return 1;
194 
195  case '2':
196  return 2;
197 
198  case '3':
199  return 3;
200 
201  case '4':
202  return 4;
203 
204  case '5':
205  return 5;
206 
207  case '6':
208  return 6;
209 
210  case '7':
211  return 7;
212 
213  case '8':
214  return 8;
215 
216  case '9':
217  return 9;
218 
219  case 'a':
220  return 10;
221 
222  case 'b':
223  return 11;
224 
225  case 'c':
226  return 12;
227 
228  case 'd':
229  return 13;
230 
231  case 'e':
232  return 14;
233 
234  //case 'f':
235  default:
236  return 15;
237  }
238  }
239 
240  /*!
241  \brief It converts the character to a hex representation.
242 
243  \param c The byte to be transformed to hex representation.
244  \param r The resulting hex encoding will be write in the r pointer.
245 
246  \note It is used by Binary2Hex function.
247  */
248  inline void Char2Hex(unsigned char c, char* r)
249  {
250  static char ct[]={"0123456789ABCDEF" };
251  int h; // high byte
252  int l; // low byte
253 
254  h = (c >> 4);
255  l = (c & 0x0F);
256 
257  r[0] = ct[h];
258  r[1] = ct[l];
259  }
260 
261  /*!
262  \brief It converts the character from a hex representation to a byte.
263 
264  \param h At least a pair of bytes to be transformed from a hex representation.
265 
266  \note It is used by Hex2Binary function.
267 
268  \result A byte representation from a two bytes hex representation.
269  */
270  inline char Hex2Char(const char* hex)
271  {
272  char c = hex[0];
273  char h, l;
274 
275  if(c >= '0' && c <= '9')
276  h = c - 48;
277  else
278  h = c + 10 - 65;
279 
280  c = hex[1];
281 
282  if((c >= '0') && (c <= '9'))
283  l = c - 48;
284  else
285  l = c + 10 - 65;
286 
287  return (h << 4) + l;
288  }
289 
290  /*!
291  \brief It converts the character from a hex representation to a byte.
292 
293  \param h At least a pair of bytes to be transformed from a hex representation.
294 
295  \note It is used by Hex2Binary function.
296 
297  \result A byte representation from a two bytes hex representation.
298 
299  \warning In our tests, this version was slower than the other.
300  */
301  inline unsigned char Hex2Char2(const char* hex)
302  {
303  unsigned char h = 0; // high byte
304  unsigned char l = 0; // low byte
305 
306  switch(hex[0])
307  {
308  case '0' :
309  h = 0;
310  break;
311 
312  case '1' :
313  h = 1;
314  break;
315 
316  case '2' :
317  h = 2;
318  break;
319 
320  case '3' :
321  h = 3;
322  break;
323 
324  case '4' :
325  h = 4;
326  break;
327 
328  case '5' :
329  h = 5;
330  break;
331 
332  case '6' :
333  h = 6;
334  break;
335 
336  case '7' :
337  h = 7;
338  break;
339 
340  case '8' :
341  h = 8;
342  break;
343 
344  case '9' :
345  h = 9;
346  break;
347 
348  case 'A' :
349  case 'a' :
350  h = 10;
351  break;
352 
353  case 'B' :
354  case 'b' :
355  h = 11;
356  break;
357 
358  case 'C' :
359  case 'c' :
360  h = 12;
361  break;
362 
363  case 'D' :
364  case 'd' :
365  h = 13;
366  break;
367 
368  case 'E' :
369  case 'e' :
370  h = 14;
371  break;
372 
373  case 'F' :
374  case 'f' :
375  h = 15;
376  break;
377  }
378 
379  switch(hex[1])
380  {
381  case '0' :
382  l = 0;
383  break;
384 
385  case '1' :
386  l = 1;
387  break;
388 
389  case '2' :
390  l = 2;
391  break;
392 
393  case '3' :
394  l = 3;
395  break;
396 
397  case '4' :
398  l = 4;
399  break;
400 
401  case '5' :
402  l = 5;
403  break;
404 
405  case '6' :
406  l = 6;
407  break;
408 
409  case '7' :
410  l = 7;
411  break;
412 
413  case '8' :
414  l = 8;
415  break;
416 
417  case '9' :
418  l = 9;
419  break;
420 
421  case 'A' :
422  case 'a' :
423  l = 10;
424  break;
425 
426  case 'B' :
427  case 'b' :
428  l = 11;
429  break;
430 
431  case 'C' :
432  case 'c' :
433  l = 12;
434  break;
435 
436  case 'D' :
437  case 'd' :
438  l = 13;
439  break;
440 
441  case 'E' :
442  case 'e' :
443  l = 14;
444  break;
445 
446  case 'F' :
447  case 'f' :
448  l = 15;
449  break;
450  }
451 
452  return ((h << 4) + l);
453  }
454 
455  /*!
456  \brief It converts each pair of hex characters from a NULL-terminated string of hex characters into a binary format.
457 
458  This function can be used, for example, to decode the returned geometry from PostGIS.
459 
460  \param hex A NULL-terminated string of hexadecimal characters.
461 
462  \return An array of binary characters in binary format.
463 
464  \note The size of the returned array is the half of the input array.
465 
466  \note The caller of this function will take the ownership of the returned
467  pointer, so it must delete it. Use delete [] returned_pointer.
468  */
469  inline char* Hex2Binary(const char* hex)
470  {
471  std::size_t hSize = strlen(hex);
472 
473  std::size_t size = hSize / 2;
474 
475  char* buf = new char[size];
476 
477  char h, l;
478 
479  for(std::size_t i = 0; i < size; ++i)
480  {
481  char c = hex[i * 2];
482 
483  if(c >= '0' && c <= '9')
484  h = c - 48;
485  else
486  h = c + 10 - 65;
487 
488  c = hex[i * 2 + 1];
489 
490  if((c >= '0') && (c <= '9'))
491  l = c - 48;
492  else
493  l = c + 10 - 65;
494 
495  buf[i] = (h << 4) + l;
496  }
497 
498  return buf;
499  }
500 
501  /*!
502  \brief It converts each pair of hex characters from an input string of hex characters into a binary format.
503 
504  This version can be used for those who wants to pre-allocate the memory where the parsed
505  version will be output.
506 
507  \param hex A string of hexadecimal characters.
508  \param hSize The number of bytes in the input string. Remember that it must be a multiple of 2.
509  \param outBuff A pointer to a pre-allocated buffer where to output the binary version. It must have at least hSize/2 bytes.
510 
511  \note The size of the input buffer (outBuff) must be at least the half of the input array.
512 
513  \note The outBuff can be the same as the input buffer; in this case the input will be overwritten.
514  */
515  inline void Hex2Binary(const char* hex, std::size_t hSize, char* outBuff)
516  {
517  std::size_t size = hSize / 2;
518 
519  char h, l;
520 
521  for(std::size_t i = 0; i < size; ++i)
522  {
523  char c = hex[i * 2];
524 
525  if(c >= '0' && c <= '9')
526  h = c - 48;
527  else
528  h = c + 10 - 65;
529 
530  c = hex[i * 2 + 1];
531 
532  if((c >= '0') && (c <= '9'))
533  l = c - 48;
534  else
535  l = c + 10 - 65;
536 
537  outBuff[i] = (h << 4) + l;
538  }
539  }
540 
541  /*!
542  \brief It converts each pair of hex characters from a NULL-terminated string of hex characters into a binary format.
543 
544  This function can be used, for example, to decode the returned geometry from PostGIS.
545 
546  \param hex A NULL-terminated string of hexadecimal characters.
547 
548  \return An array of binary characters in binary format.
549 
550  \note The size of the returned array is the half of the input array.
551 
552  \note The caller of this function will take the ownership of the returned
553  pointer, so it must delete it. Use delete [] returned_pointer.
554 
555  \warning In our tests, this version was slower than the other equivalent.
556  */
557  inline char* Hex2Binary2(const char* hex)
558  {
559  std::size_t hSize = strlen(hex);
560 
561  std::size_t size = hSize / 2;
562 
563  char* buf = new char[size];
564 
565  for(std::size_t i = 0; i < size; ++i)
566  buf[i] = Hex2Char2(hex + (2 * i));
567 
568  return buf;
569  }
570 
571  /*!
572  \brief It converts each pair of hex characters from an input string of hex characters into a binary format.
573 
574  This version can be used for those who wants to pre-allocate the memory where the parsed
575  version will be output.
576 
577  \param hex A string of hexadecimal characters.
578  \param hSize The number of bytes in the input string. Remember that it must be a multiple of 2.
579  \param outBuff A pointer to a pre-allocated buffer where to output the binary version. It must have at least hSize/2 bytes.
580 
581  \note The size of the input buffer (outBuff) must be at least the half of the input array.
582  */
583  inline void Hex2Binary2(const char* hex, std::size_t hSize, char* outBuff)
584  {
585  std::size_t size = hSize / 2;
586 
587  for(std::size_t i = 0; i < size; ++i)
588  outBuff[i] = Hex2Char2(hex + (2 * i));
589  }
590 
591  /*!
592  \brief Each char from the array of characters in binary format is converted into a pair of hex characters. The final string is NULL terminated.
593 
594  \param s An array of characters in binary format.
595  \param size The size of the string of characters (not including the trailing '\0').
596 
597  \note The caller of this function will take the ownership of the returned
598  pointer, so it must delete it. Use delete [] returned_pointer.
599 
600  \note The returned buffer size is: 2 * size + 1.
601  */
602  inline char* Binary2Hex(const char* s, std::size_t size)
603  {
604  char* buff = new char[2 * size + 1];
605 
606  std::size_t i = 0;
607 
608  for(; i < size; ++i)
609  Char2Hex(s[i], buff + (i * 2));
610 
611  buff[i * 2] = '\0';
612 
613  return buff;
614  }
615 
616  /*!
617  \brief Each char from the array of characters in binary format is converted into a pair of hex characters. The final string is NULL terminated.
618 
619  \param s An array of characters in binary format.
620  \param size The size of the string of characters (not including the trailing '\0').
621  \param outBuff A pointer to a pre-allocated buffer where to output the binary version. It must have at least 2*size+1 bytes.
622  */
623  inline void Binary2Hex(const char* s, std::size_t size, char* outBuff)
624  {
625  std::size_t i = 0;
626 
627  for(; i < size; ++i)
628  Char2Hex(s[i], outBuff + (i * 2));
629 
630  outBuff[i * 2] = '\0';
631  }
632 
633  } // end namespace common
634 } // end namespace te
635 
636 #endif // __TERRALIB_COMMON_INTERNAL_HEXUTILS_H
637 
char * Hex2Binary2(const char *hex)
It converts each pair of hex characters from a NULL-terminated string of hex characters into a binary...
Definition: HexUtils.h:557
unsigned char GetDecimalFromHexUCase(char hexValue)
It returns the decimal value in a char from a given hex value (for example: 'A' => 10...
Definition: HexUtils.h:119
void Char2Hex(unsigned char c, char *r)
It converts the character to a hex representation.
Definition: HexUtils.h:248
unsigned char GetDecimalFromHexNotCS(unsigned char hexValue)
It returns the decimal value in a char from a given hex value (for example: 'A' => 10...
Definition: HexUtils.h:49
char * Binary2Hex(const char *s, std::size_t size)
Each char from the array of characters in binary format is converted into a pair of hex characters...
Definition: HexUtils.h:602
char Hex2Char(const char *hex)
It converts the character from a hex representation to a byte.
Definition: HexUtils.h:270
URI C++ Library.
unsigned char Hex2Char2(const char *hex)
It converts the character from a hex representation to a byte.
Definition: HexUtils.h:301
unsigned char GetDecimalFromHexLCase(char hexValue)
It returns the decimal value in a char from a given hex value (for example: 'a' => 10...
Definition: HexUtils.h:185
char * Hex2Binary(const char *hex)
It converts each pair of hex characters from a NULL-terminated string of hex characters into a binary...
Definition: HexUtils.h:469