Merge branch 'release-2.140.101'
[feisty_meow.git] / nucleus / library / structures / object_packers.h
1 #ifndef OBJECT_PACKERS_CLASS
2 #define OBJECT_PACKERS_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : object_packers                                                    *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 1995-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include <basis/byte_array.h>
19 #include <basis/definitions.h>
20
21 namespace structures {
22
23 // the sizes in bytes of common objects.  if the compiler doesn't match these, there will
24 // probably be severe tire damage.
25 const int PACKED_SIZE_BYTE = 1;
26 const int PACKED_SIZE_INT16 = 2;
27 const int PACKED_SIZE_INT32 = 4;
28
29 // these functions pack and unpack popular data types.
30
31 void attach(basis::byte_array &packed_form, bool to_attach);
32   //!< Packs a bool "to_attach" into "packed_form".
33 bool detach(basis::byte_array &packed_form, bool &to_detach);
34   //!< Unpacks a bool "to_detach" from "packed_form".
35
36 void attach(basis::byte_array &packed_form, basis::abyte to_attach);
37   //!< Packs a byte "to_attach" into "packed_form".
38 bool detach(basis::byte_array &packed_form, basis::abyte &to_detach);
39   //!< Unpacks a byte "to_detach" from "packed_form".
40
41 int packed_size(const basis::byte_array &packed_form);
42   //!< Reports the size required to pack a byte array into a byte array.
43 void attach(basis::byte_array &packed_form, const basis::byte_array &to_attach);
44   //!< Packs a byte_array "to_attach" into "packed_form".
45 bool detach(basis::byte_array &packed_form, basis::byte_array &to_detach);
46   //!< Unpacks a byte_array "to_detach" from "packed_form".
47
48 void attach(basis::byte_array &packed_form, char to_attach);
49   //!< Packs a char "to_attach" into "packed_form".
50 bool detach(basis::byte_array &packed_form, char &to_detach);
51   //!< Unpacks a char "to_detach" from "packed_form".
52
53 int packed_size(double to_pack);
54   //!< Reports how large the "to_pack" will be as a stream of bytes.
55 void attach(basis::byte_array &packed_form, double to_pack);
56   //!< Packs a double precision floating point "to_attach" into "packed_form".
57 bool detach(basis::byte_array &packed_form, double &to_unpack);
58   //!< Unpacks a double precision floating point "to_attach" from "packed_form".
59
60 void attach(basis::byte_array &packed_form, float to_pack);
61   //!< Packs a floating point "to_attach" into "packed_form".
62 bool detach(basis::byte_array &packed_form, float &to_unpack);
63   //!< Unpacks a floating point "to_attach" from "packed_form".
64
65 void attach(basis::byte_array &packed_form, int to_attach);
66   //!< Packs an integer "to_attach" into "packed_form".
67   /*!< This method and the other simple numerical storage methods use a little
68   endian ordering of the bytes.  They are platform independent with respect to
69   endianness and will reassemble the number properly on any platform. */
70 bool detach(basis::byte_array &packed_form, int &to_detach);
71   //!< Unpacks an integer "to_attach" from "packed_form".
72
73 void obscure_attach(basis::byte_array &packed_form, basis::un_int to_attach);
74   //!< like the normal attach but shifts in some recognizable sentinel data.
75   /*!< this is slightly more sure than a simple integer attachment.  it can
76   be used to make sure upcoming data is probably a valid int. */
77 bool obscure_detach(basis::byte_array &packed_form, basis::un_int &to_detach);
78   //!< shifts the number back and checks validity, false returned if corrupted.
79
80 /*
81 void attach(basis::byte_array &packed_form, long to_attach);
82   //!< Packs a long integer "to_attach" into "packed_form".
83 bool detach(basis::byte_array &packed_form, long &to_detach);
84   //!< Unpacks a long integer "to_attach" from "packed_form".
85 */
86
87 void attach(basis::byte_array &packed_form, short to_attach);
88   //!< Packs a short integer "to_attach" into "packed_form".
89 bool detach(basis::byte_array &packed_form, short &to_detach);
90   //!< Unpacks a short integer "to_attach" from "packed_form".
91
92 void attach(basis::byte_array &packed_form, basis::un_int to_attach);
93   //!< Packs an unsigned integer "to_attach" into "packed_form".
94 bool detach(basis::byte_array &packed_form, basis::un_int &to_detach);
95   //!< Unpacks an unsigned integer "to_attach" from "packed_form".
96
97 /*
98 void attach(basis::byte_array &packed_form, basis::un_long to_attach);
99   //!< Packs an unsigned long integer "to_attach" into "packed_form".
100 bool detach(basis::byte_array &packed_form, basis::un_long &to_detach);
101   //!< Unpacks an unsigned long integer "to_attach" from "packed_form".
102 */
103
104 void attach(basis::byte_array &packed_form, basis::un_short to_attach);
105   //!< Packs an unsigned short integer "to_attach" into "packed_form".
106 bool detach(basis::byte_array &packed_form, basis::un_short &to_detach);
107   //!< Unpacks an unsigned short integer "to_attach" from "packed_form".
108
109 //////////////
110
111 // helpful template functions for packing.
112
113 //! provides a way to pack any array that stores packable objects.
114 template <class contents>
115 void pack_array(basis::byte_array &packed_form, const basis::array<contents> &to_pack) {
116   obscure_attach(packed_form, to_pack.length());
117   for (int i = 0; i < to_pack.length(); i++) to_pack[i].pack(packed_form);
118 }
119
120 //! provides a way to unpack any array that stores packable objects.
121 template <class contents>
122 bool unpack_array(basis::byte_array &packed_form, basis::array<contents> &to_unpack) {
123   to_unpack.reset();
124   basis::un_int len;
125   if (!obscure_detach(packed_form, len)) return false;
126   basis::array<contents> swappy_array(len, NULL_POINTER, to_unpack.flags());
127     // we create an array of the specified length to see if it's tenable.
128   if (!swappy_array.observe()) return false;  // failed to allocate.
129   for (int i = 0; i < (int)len; i++) {
130     if (!swappy_array[i].unpack(packed_form))
131       return false;
132   }
133   // now that we've got exactly what we want, plunk it into the result array.
134   swappy_array.swap_contents(to_unpack);
135   return true;
136 }
137
138 //! provides space estimation for the objects to be packed.
139 template <class contents>
140 int packed_size_array(const basis::array<contents> &to_pack) {
141   int to_return = sizeof(int) * 2;  // obscure version uses double int size.
142   for (int i = 0; i < to_pack.length(); i++)
143     to_return += to_pack[i].packed_size();
144   return to_return;
145 }
146
147 //! Packs flat objects into an array of bytes.
148 /*! Similar to pack above, but operates on arrays with simple
149 objects that do not support functional pack and unpack. */
150 template <class contents>
151 void pack_simple(basis::byte_array &packed_form, const basis::array<contents> &to_pack) {
152   obscure_attach(packed_form, to_pack.length());
153   for (int i = 0; i < to_pack.length(); i++)
154     attach(packed_form, to_pack[i]);
155 }
156
157 //! Unpacks flat objects from an array of bytes.
158 /*! Similar to unpack above, but operates on arrays with simple
159 objects that do not support functional pack and unpack. */
160 template <class contents>
161 bool unpack_simple(basis::byte_array &packed_form, basis::array<contents> &to_unpack) {
162   to_unpack.reset();
163   basis::un_int len;
164   if (!obscure_detach(packed_form, len)) return false;
165   basis::array<contents> swappy_array(len, NULL_POINTER, to_unpack.flags());
166   if (!swappy_array.observe()) return false;  // failed to allocate.
167   for (int i = 0; i < len; i++) {
168     if (!detach(packed_form, swappy_array[i]))
169       return false;
170   }
171   swappy_array.swap_contents(to_unpack);
172   return true;
173 }
174
175 } // namespace
176
177 #endif
178