AMXX-BG.INFO › nvault_array.inc › Raw include

nvault_array.inc

Original include source with line numbers.

Back Download .inc
1
2 /*
3 nVault Array
4 v0.2
5 by bugsy
6 */
7
8 /* Change log
9 v0.1
10 - Initial release as a stand-alone include. These functions were initially included as part of
11 nvault utility but I decided to break them apart since these functions aren't quite utility
12 functions, they are an extension of nVault base functionality to save/load data.
13 - Added nvault_isarray() and nvault_arraysize().
14
15 v0.2
16 - Added checking while loading the array data in nvault_read_array() to make sure the data
17 is nvault_set_array() data. If the data is not array data, the plugin will fail. If the scripter
18 sees this error in logs, then he is attempting to read regular text data as an array which
19 should not be attempted. There is also the nvault_isarray() function that can be used to
20 check the data, but this shouldn't be necessary if the plugin was written properly.
21 */
22
23 #if defined _nvault_array_included
24 #endinput
25 #endif
26 #define _nvault_array_included
27
28 #if !defined _nvault_included
29 #include <nvault>
30 #endif
31
32 //********************************************************************************************
33 // Increase this value if your plugin throws the below error:
34 // "Array size too large, you must increase NVAULT_ARRAY_MAXARRAYSIZE in nvault_array.inc"
35
36 const _NVAULT_ARRAY_MAXARRAYSIZE = 500;
37 //********************************************************************************************
38
39 const _NVAULT_ARRAY_CELLSIZE = 5;
40 const _NVAULT_ARRAY_BUFFERSIZE = ( ( _NVAULT_ARRAY_MAXARRAYSIZE * _NVAULT_ARRAY_CELLSIZE ) + 1 );
41 const _NVAULT_ARRAY_BYTEMAP = 0b11110000;
42 const _NVAULT_ARRAY_NULLBYTE = 0b10101010;
43
44 /* Description: Set array data in a vault
45
46 Param(s):
47 vault - Vault file handle ID that was returned by nvault_open(). Do not pass an nvault utility file ID.
48 key[] - Key for data to store.
49 array[] - Array of data to store.
50 size - Size of array to store (use sizeof(array)).
51
52 Return value: 1 on success, 0 on failure.
53
54 Comments: None.
55 */
56 stock nvault_set_array( vault , const key[] , const any:array[] , size )
57 {
58 new iArrayPos , iOutputPos , iValue[ 1 ] , szString[ _NVAULT_ARRAY_BUFFERSIZE ];
59
60 if ( size > _NVAULT_ARRAY_MAXARRAYSIZE )
61 set_fail_state( "[nVault Array] Array size too large, you must increase NVAULT_ARRAY_MAXARRAYSIZE in nvault_array.inc." );
62
63 while ( ( iArrayPos < size ) && ( iOutputPos < charsmax( szString ) ) )
64 {
65 iValue[ 0 ] = array[ iArrayPos++ ];
66
67 if ( !( cellmin <= iValue[ 0 ] <= cellmax ) )
68 set_fail_state( "[nVault Array] Value exceeds valid long value range." );
69
70 szString[ iOutputPos++ ] = _nvault_array_byte_map( iValue );
71
72 for ( new i = 0 ; i < 4 ; i++ )
73 szString[ iOutputPos++ ] = !iValue{ i } ? _NVAULT_ARRAY_NULLBYTE : iValue{ i };
74 }
75
76 szString[ iOutputPos ] = EOS;
77
78 return nvault_set( vault , key , szString );
79 }
80
81 /* Description: Get array data in a vault
82
83 Param(s):
84 vault - Vault file handle ID that was returned by nvault_open(). Do not pass an nvault utility file ID.
85 key[] - Key for record to retrieve
86 array[] - Array to store retrieved data in.
87 size - Size of array that data is being retrieved in.
88 timestamp - Timestamp of record (passed by reference)
89
90 Return value: The number of array elements that were stored in the nvault array record.
91
92 Comments: Do not read an nvault record as an array when it was not stored with nvault_set_array()..
93 */
94 stock nvault_get_array( vault , const key[] , any:array[] , size , &timestamp=0 )
95 {
96 new iStringPos , iArrayPos , iValue[ 1 ] , bmByteMap , szString[ _NVAULT_ARRAY_BUFFERSIZE ];
97
98 if ( size > _NVAULT_ARRAY_MAXARRAYSIZE )
99 set_fail_state( "[nVault Array] Array size too large, you must increase _NVAULT_ARRAY_MAXARRAYSIZE in nvault_array.inc." );
100
101 //Read data from nvault. Switched from nvault_get() to nvault_lookup() to allow timestamp retrieval.
102 if ( nvault_lookup( vault , key , szString , charsmax( szString ) , timestamp ) )
103 {
104 //Each individual nvault array value consumes 5 characters. If the length of the string mod 5 is not 0 then
105 //the data is not array data.
106 if ( strlen( szString ) % 5 )
107 set_fail_state( "[nVault Array] Can only use nvault_get_array() on data that was saved using nvault_set_array()." );
108
109 //Loop through the string, making sure the index of the array and string is within boundaries.
110 while ( szString[ iStringPos ] && ( iStringPos < charsmax( szString ) ) && ( iArrayPos < size ) )
111 {
112 //Every 5th character of the string is a byte-map which holds a boolean in bits 1-4 for whether or not
113 //the following 4 characters are null. Bits 5-8 are set to constant 1 so these bits can be checked at each
114 //iteration to make sure they exist. If they do not, then the data is not nvault array data.
115 //[1111 0000] : 1's are always 1, 0's are booleans for whether or not adjacent bytes are null.
116 if ( ( ( bmByteMap = szString[ iStringPos++ ] ) & _NVAULT_ARRAY_BYTEMAP ) != _NVAULT_ARRAY_BYTEMAP )
117 set_fail_state( "[nVault Array] Can only use nvault_get_array() on data that was saved using nvault_set_array()." );
118
119 //Load byte value in cell. If the byte map says it is null, set it to null (0), otherwise set it so the
120 //value stored in the byte.
121 for ( new i = 0 ; i < 4 ; i++ )
122 {
123 iValue{ i } = bmByteMap & ( 1 << i ) ? szString[ iStringPos ] : 0;
124 iStringPos++;
125 }
126
127 //Assign value to array.
128 array[ iArrayPos++ ] = iValue[ 0 ];
129 }
130 }
131
132 return iArrayPos;
133 }
134
135 /* Description: Check if an nvault entry is an array
136
137 Param(s):
138 vault - Vault file handle ID that was returned by nvault_open(). Do not pass an nvault utility file ID.
139 key[] - Key for record to check
140
141 Return value: true / false
142 */
143 stock bool:nvault_isarray( vault , const key[] )
144 {
145 new szData[ _NVAULT_ARRAY_BUFFERSIZE ] , iTS , iDataLen , bool:bRetVal;
146
147 if ( nvault_lookup( vault , key , szData , charsmax( szData ) , iTS ) && ( iDataLen = strlen( szData ) ) )
148 {
149 bRetVal = true;
150
151 for ( new i = 0 ; i < iDataLen ; i += _NVAULT_ARRAY_CELLSIZE )
152 {
153 if ( ( szData[ i ] & _NVAULT_ARRAY_BYTEMAP ) != _NVAULT_ARRAY_BYTEMAP )
154 {
155 bRetVal = false;
156 break;
157 }
158 }
159 }
160
161 return bRetVal;
162 }
163
164 /* Description: Get the size of an nvault array
165
166 Param(s):
167 vault - Vault file handle ID that was returned by nvault_open(). Do not pass an nvault utility file ID.
168 key[] - Key for record to check
169
170 Return value: 0 = Record does not exist or is not an nvault array record
171 >0 = How large the array is (in cells)
172 */
173 stock nvault_arraysize( vault , const key[] )
174 {
175 new szData[ _NVAULT_ARRAY_BUFFERSIZE ] , iTS , iDataLen , bool:bIsArray , iRetVal;
176
177 if ( nvault_lookup( vault , key , szData , charsmax( szData ) , iTS ) && ( iDataLen = strlen( szData ) ) )
178 {
179 if ( ( iDataLen < charsmax( szData ) ) && !( iRetVal % _NVAULT_ARRAY_CELLSIZE ) )
180 {
181 bIsArray = true;
182
183 for ( new i = 0 ; i < iDataLen ; i += _NVAULT_ARRAY_CELLSIZE )
184 {
185 if ( ( szData[ i ] & _NVAULT_ARRAY_BYTEMAP ) != _NVAULT_ARRAY_BYTEMAP )
186 {
187 bIsArray = false;
188 break;
189 }
190 }
191
192 if ( bIsArray == true )
193 {
194 iRetVal = ( iDataLen / _NVAULT_ARRAY_CELLSIZE );
195 }
196 }
197 }
198
199 return iRetVal;
200 }
201
202 stock _nvault_array_byte_map( iValue[ 1 ] )
203 {
204 new iOut[ 1 ] = { _NVAULT_ARRAY_BYTEMAP };
205
206 for ( new i = 0 ; i < 4 ; i++)
207 iOut[ 0 ] |= !iValue{ i } ? 0 : ( 1 << i );
208
209 return iOut[ 0 ];
210 }
211 /* AMXX-Studio Notes - DO NOT MODIFY BELOW HERE
212 *{\\ rtf1\\ ansi\\ deff0{\\ fonttbl{\\ f0\\ fnil Tahoma;}}\n\\ viewkind4\\ uc1\\ pard\\ lang1033\\ f0\\ fs16 \n\\ par }
213 */
214