1/****h* PawnLibs/save
2 * Summary
3 *   A helper library for packing and unpacking application state data.
4 * Description
5 *   Pawn works with cells which has a size of 4 bytes. Native interfaces
6 *   handling generic data like application state have size limits for that
7 *   data.  If application does not need to work with a large numbers, several
8 *   values can be packed into a single cell. This library provides some
9 *   convenient functions to pack and unpack such values from array of cells
10 *   which can be saved or loaded on/from flash.
11 * Example
12 *   TBD
13 * History
14 *   * v6.0 - added
15 ******/
16#define CELL_BITS 32
17new save_pos = 0;
18 
19new saveArray[GAME_SAVE_SIZE];
20 
21/****f* PawnLibs/save/SaveReset
22 * Summary
23 *   Reset state before storing new data to pack.
24 * Synopsis
25 */
26SaveReset()
27/*
28 * Source
29 */
30{
31    save_pos = 0;
32    for (new i = 0; i < GAME_SAVE_SIZE; i++) {
33        saveArray[i] = 0;
34    }
35}
36/******/
37 
38/****f* PawnLibs/save/SaveWriteValue
39 * Summary
40 *   Store specified number of bits from some unsigned value.
41 * Synopsis
42 */
43SaveWriteValue(value, bits)
44/*
45 * Inputs
46 *   * value - a value to store data from
47 *   * bits - a number of bits to store
48 * Source
49 */
50{
51 
52    if (SaveCheckOverflow(bits)) return;
53 
54    if (value < 0) {
55        LOG_i("SaveMessage::WriteInt: negative value %d may be sent incorrectly, use WriteSignedInt instead ", value);
56    }
57    new freeBits = SaveGetFreeBits();
58 
59    if (freeBits >= bits) {
60        SaveWriteData(SaveTrim(value, bits, 0), bits);
61    } else {
62        SaveWriteData(SaveTrim(value, freeBits, 0), freeBits);
63        SaveWriteData(SaveTrim(value, bits - freeBits, freeBits), bits - freeBits);
64    }
65 
66}
67/******/
68 
69/****f* PawnLibs/save/SaveWriteSignedValue
70 * Summary
71 *   Store specified number of bits from some signed value.
72 * Synopsis
73 */
74SaveWriteSignedValue(value, bits)
75/*
76 * Inputs
77 *   * value - a value to store data from
78 *   * bits - a number of bits to store
79 * Source
80 */
81{
82    if (SaveCheckOverflow(bits + 1)) return;
83 
84    SaveWriteValue((value >> (CELL_BITS - 1)) & 0x1, 1);
85    SaveWriteValue(ABS(value), bits);
86 
87}
88/******/
89 
90/****f* PawnLibs/save/SaveReadValue
91 * Summary
92 *   Read specified number of bits of packed unsigned value.
93 * Synopsis
94 */
95SaveReadValue(bits)
96/*
97 * Inputs
98 *   * bits - a number of bits to get
99 * Return value
100 *   Unpacked unsigned value.
101 * Source
102 */
103{
104    if (SaveCheckOverflow(bits)) return 0;
105 
106    new value = 0;
107    new freeBits = SaveGetFreeBits();
108    new intermediate_result;
109 
110    if (SaveGetFreeBits() >= bits) {
111        value = saveArray[SaveGetCell()] << (SaveGetFreeBits() - bits);
112        value = value >>> (SaveGetFreeBits() - bits + SaveGetBits());
113        save_pos += bits;
114    } else {
115        value = saveArray[SaveGetCell()] >>> (SaveGetBits());
116        save_pos += freeBits;
117 
118        intermediate_result = (saveArray[SaveGetCell()] << (CELL_BITS - (bits - freeBits))) >>> (CELL_BITS - (bits - freeBits));
119        value |= intermediate_result << freeBits;
120        save_pos += bits - freeBits;
121    }
122 
123    return value;
124}
125/******/
126 
127/****f* PawnLibs/save/SaveReadSignedValue
128 * Summary
129 *   Read specified number of bits of packed signed value.
130 * Synopsis
131 */
132SaveReadSignedValue(bits)
133/*
134 * Inputs
135 *   * bits - a number of bits to get
136 * Return value
137 *   Unpacked signed value.
138 * Source
139 */
140{
141    if (SaveCheckOverflow(bits + 1)) return 0;
142 
143    new value = SaveReadValue(1) == 0 ? 1 :  - 1;
144    value *= SaveReadValue(bits);
145 
146    return value;
147}
148/******/
149 
150/****f* PawnLibs/save/SaveSetData
151 * Summary
152 *   Populate state with a new data to unpack.
153 * Synopsis
154 */
155SaveSetData(const pkt[], size)
156/*
157 * Inputs
158 *   * pkt - application state data to unpack
159 * Source
160 */
161{
162    for (new i = 0; i < size; i++)
163        saveArray[i] = pkt[i];
164}
165/*
166 * See also
167 *   * ON_Init()
168 *   * ON_Load()
169 ******/
170 
171/****f* PawnLibs/save/SaveGetData
172 * Summary
173 *   Get packed data to store on flash.
174 * Synopsis
175 */
176SaveGetData()
177/*
178 * Return value
179 *   Packed data to store.
180 * Source
181 */
182{
183    return saveArray;
184}
185/*
186 * See also
187 *   * saveState()
188 ******/
189 
190 
191SaveGetCell() {
192    return save_pos / CELL_BITS;
193}
194SaveGetBits() {
195    return save_pos % CELL_BITS;
196}
197SaveGetFreeBits() {
198    return CELL_BITS - save_pos % CELL_BITS;
199}
200SaveCheckOverflow(bits) {
201    if (save_pos + bits > GAME_SAVE_SIZE * 32) {
202        LOG_i("SaveMessage: maximum message size exceeded");
203        return true;
204    }
205 
206    return false;
207}
208SaveTrim(value, bits, right) {
209    return (value << (CELL_BITS - bits - right)) >>> (CELL_BITS - bits);
210}
211SaveWriteData(value, bits) {
212    saveArray[SaveGetCell()] |= value << SaveGetBits();
213    save_pos += bits;
214}
215 
216