1 /* @include ajtagval **********************************************************
2 **
3 ** Handling of tag-value pairs of strings
4 **
5 ** @author Copyright (C) 2011 Peter Rice
6 ** @version $Revision: 1.1 $
7 ** @modified $Date: 2011/11/08 15:01:23 $ by $Author: rice $
8 ** @@
9 **
10 ** This library is free software; you can redistribute it and/or
11 ** modify it under the terms of the GNU Lesser General Public
12 ** License as published by the Free Software Foundation; either
13 ** version 2.1 of the License, or (at your option) any later version.
14 **
15 ** This library is distributed in the hope that it will be useful,
16 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 ** Lesser General Public License for more details.
19 **
20 ** You should have received a copy of the GNU Lesser General Public
21 ** License along with this library; if not, write to the Free Software
22 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
23 ** MA 02110-1301, USA.
24 ******************************************************************************/
25
26 #include "ajlib.h"
27 #include "ajtagval.h"
28
29
30
31
32 /* @filesection ajtagval ******************************************************
33 **
34 ** @nam1rule aj Function belongs to the AJAX library.
35 **
36 ******************************************************************************/
37
38
39
40
41 /* @datasection [AjPTagval] Tag value data ************************************
42 **
43 ** Function is for manipulating tag value pairs
44 **
45 ** @nam2rule Tagval Tag value pairs
46 **
47 ******************************************************************************/
48
49
50
51
52 /* @section constructors ******************************************************
53 **
54 ** Constructors
55 **
56 ** @fdata [AjPTagval]
57 **
58 ** @nam3rule New Constructor
59 ** @suffix C Character values
60 ** @suffix S String values
61 **
62 ** @argrule C tagtxt [const char*] Tag name
63 ** @argrule C valtxt [const char*] Tag value
64 ** @argrule S tag [const AjPStr] Tag name
65 ** @argrule S val [const AjPStr] Tag value
66 **
67 ** @valrule * [AjPTagval] Tag value pair object
68 **
69 ** @fcategory new
70 **
71 ******************************************************************************/
72
73
74
75
76 /* @func ajTagvalNewC *********************************************************
77 **
78 ** Tag value pair constructor
79 **
80 ** @param [r] tagtxt [const char*] Tag name
81 ** @param [r] valtxt [const char*] Tag value
82 ** @return [AjPTagval] New object
83 **
84 ** @release 6.5.0
85 ** @@
86 ******************************************************************************/
87
ajTagvalNewC(const char * tagtxt,const char * valtxt)88 AjPTagval ajTagvalNewC(const char* tagtxt, const char* valtxt)
89 {
90 AjPTagval ret;
91
92 AJNEW0(ret);
93
94 ret->Tag = ajStrNewC(tagtxt);
95 ret->Value = ajStrNewC(valtxt);
96
97 return ret;
98 }
99
100
101
102
103 /* @func ajTagvalNewS *********************************************************
104 **
105 ** Tag value pair constructor
106 **
107 ** @param [r] tag [const AjPStr] Tag name
108 ** @param [r] val [const AjPStr] Tag value
109 ** @return [AjPTagval] New object
110 **
111 ** @release 6.5.0
112 ** @@
113 ******************************************************************************/
114
ajTagvalNewS(const AjPStr tag,const AjPStr val)115 AjPTagval ajTagvalNewS(const AjPStr tag, const AjPStr val)
116 {
117 AjPTagval ret;
118
119 AJNEW0(ret);
120
121 ret->Tag = ajStrNewS(tag);
122 ret->Value = ajStrNewS(val);
123
124 return ret;
125 }
126
127
128
129
130 /* @section Tag value pair destructors ****************************************
131 **
132 ** Destruction destroys all internal data structures and frees the
133 ** memory allocated for the tag value pair object.
134 **
135 ** @fdata [AjPTagval]
136 **
137 ** @nam3rule Del Destructor
138 **
139 ** @argrule Del Ptagval [AjPTagval*] Tag value pair object
140 **
141 ** @valrule * [void]
142 **
143 ** @fcategory delete
144 **
145 ******************************************************************************/
146
147
148
149
150 /* @func ajTagvalDel **********************************************************
151 **
152 ** Tag value pair destructor
153 **
154 ** @param [d] Ptagval [AjPTagval*] Tag value pair object to delete
155 ** @return [void]
156 **
157 ** @release 6.5.0
158 ** @@
159 ******************************************************************************/
160
ajTagvalDel(AjPTagval * Ptagval)161 void ajTagvalDel(AjPTagval *Ptagval)
162 {
163 AjPTagval tagval;
164
165 if(!Ptagval) return;
166 if(!(*Ptagval)) return;
167
168 tagval = *Ptagval;
169
170 ajStrDel(&tagval->Tag);
171 ajStrDel(&tagval->Value);
172
173 AJFREE(*Ptagval);
174 *Ptagval = NULL;
175
176 return;
177 }
178
179
180
181
182 /* @section element retrieval *************************************************
183 **
184 ** Functions for returning elements of a tag value pair object.
185 **
186 ** @fdata [AjPTagval]
187 **
188 ** @nam3rule Get Retrieve an unmodified element of a string object.
189 ** @nam4rule GetTag Retrieve tag name
190 ** @nam4rule GetValue Retrieve tag value
191 **
192 ** @argrule * tagval [const AjPTagval] Tag value pair
193 **
194 ** @valrule GetTag [const AjPStr] Tag name
195 ** @valrule GetValue [const AjPStr] Tag value
196 **
197 ** @fcategory use
198 ******************************************************************************/
199
200
201
202
203 /* @func ajTagvalGetTag *******************************************************
204 **
205 ** Returns the tag name
206 **
207 ** @param [r] tagval [const AjPTagval] Source tag value pair
208 ** @return [const AjPStr] Current tag name, or a null string if undefined.
209 **
210 ** @release 6.5.0
211 ** @@
212 ******************************************************************************/
213
ajTagvalGetTag(const AjPTagval tagval)214 const AjPStr ajTagvalGetTag(const AjPTagval tagval)
215 {
216 if(!tagval)
217 return NULL;
218
219
220 return tagval->Tag;
221 }
222
223
224
225
226 /* @macro MAJTAGVALGETTAG *****************************************************
227 **
228 ** Returns the tag name
229 **
230 ** A macro version of {ajTagvalGetTag} available in case it is needed for speed.
231 **
232 ** @param [r] tagval [const AjPTagval] Source tag value pair
233 ** @return [const AjPStr] Current tag name, or a null string if undefined.
234 **
235 ** @release 6.5.0
236 ** @@
237 ******************************************************************************/
238
239
240
241
242 /* @func ajTagvalGetValue *****************************************************
243 **
244 ** Returns the tag value
245 **
246 ** @param [r] tagval [const AjPTagval] Source tag value pair
247 ** @return [const AjPStr] Current tag value, or a null string if undefined.
248 **
249 ** @release 6.5.0
250 ** @@
251 ******************************************************************************/
252
ajTagvalGetValue(const AjPTagval tagval)253 const AjPStr ajTagvalGetValue(const AjPTagval tagval)
254 {
255 if(!tagval)
256 return NULL;
257
258
259 return tagval->Value;
260 }
261
262
263
264
265 /* @macro MAJTAGVALGETVALUE ***************************************************
266 **
267 ** Returns the tag value
268 **
269 ** A macro version of {ajTagvalGetTagValue} available in case it is
270 ** needed for speed.
271 **
272 ** @param [r] str [const AjPStr] Source string
273 ** @return [const AjPStr] Current tag value, or a null string if undefined.
274 ** @@
275 ******************************************************************************/
276
277
278
279
280 /* @section modifiers *********************************************************
281 **
282 ** @fdata [AjPTagval]
283 **
284 ** @nam3rule Append Add text to the tag value
285 ** @nam3rule Fmt Change the format of a tag name
286 ** @nam3rule Replace Replace the tag value
287 **
288 ** @nam4rule FmtLower Convert to lower case.
289 ** @nam4rule FmtUpper Convert to upper case.
290 **
291 ** @suffix C Character data
292 ** @suffix S String data
293 **
294 ** @argrule * tagval [AjPTagval] Tag value pair
295 ** @argrule C txt [const char*] Text
296 ** @argrule S str [const AjPStr] Text
297 **
298 ** @valrule * [void]
299 **
300 ** @fcategory modify
301 ******************************************************************************/
302
303
304
305
306 /* @func ajTagvalAppendC ******************************************************
307 **
308 ** Adds text to the tag value
309 **
310 ** @param [u] tagval [AjPTagval] Tag value pair
311 ** @param [r] txt [const char*] Text
312 ** @return [void]
313 **
314 ** @release 6.5.0
315 ** @@
316 ******************************************************************************/
317
ajTagvalAppendC(AjPTagval tagval,const char * txt)318 void ajTagvalAppendC(AjPTagval tagval, const char* txt)
319 {
320 ajStrAppendC(&tagval->Value, txt);
321 return;
322 }
323
324
325
326
327 /* @func ajTagvalAppendS ******************************************************
328 **
329 ** Adds text to the tag value
330 **
331 ** @param [u] tagval [AjPTagval] Tag value pair
332 ** @param [r] str [const AjPStr] Text
333 ** @return [void]
334 **
335 ** @release 6.5.0
336 ** @@
337 ******************************************************************************/
338
ajTagvalAppendS(AjPTagval tagval,const AjPStr str)339 void ajTagvalAppendS(AjPTagval tagval, const AjPStr str)
340 {
341 ajStrAppendS(&tagval->Value, str);
342 return;
343 }
344
345
346
347
348 /* @func ajTagvalFmtLower *****************************************************
349 **
350 ** Converts a tag value pair name to lower case
351 **
352 ** @param [u] tagval [AjPTagval] Tag value pair
353 ** @return [void]
354 **
355 ** @release 6.5.0
356 ** @@
357 ******************************************************************************/
358
ajTagvalFmtLower(AjPTagval tagval)359 void ajTagvalFmtLower(AjPTagval tagval)
360 {
361 ajStrFmtLower(&tagval->Tag);
362 return;
363 }
364
365
366
367
368 /* @func ajTagvalFmtUpper *****************************************************
369 **
370 ** Converts a tag value pair name to upper case
371 **
372 ** @param [u] tagval [AjPTagval] Tag value pair
373 ** @return [void]
374 **
375 ** @release 6.5.0
376 ** @@
377 ******************************************************************************/
378
ajTagvalFmtUpper(AjPTagval tagval)379 void ajTagvalFmtUpper(AjPTagval tagval)
380 {
381 ajStrFmtUpper(&tagval->Tag);
382 return;
383 }
384
385
386
387
388 /* @func ajTagvalReplaceC ******************************************************
389 **
390 ** Replace the tag value
391 **
392 ** @param [u] tagval [AjPTagval] Tag value pair
393 ** @param [r] txt [const char*] Text
394 ** @return [void]
395 **
396 ** @release 6.5.0
397 ** @@
398 ******************************************************************************/
399
ajTagvalReplaceC(AjPTagval tagval,const char * txt)400 void ajTagvalReplaceC(AjPTagval tagval, const char* txt)
401 {
402 ajStrAssignC(&tagval->Value, txt);
403 return;
404 }
405
406
407
408
409 /* @func ajTagvalReplaceS ******************************************************
410 **
411 ** Replace the tag value
412 **
413 ** @param [u] tagval [AjPTagval] Tag value pair
414 ** @param [r] str [const AjPStr] Text
415 ** @return [void]
416 **
417 ** @release 6.5.0
418 ** @@
419 ******************************************************************************/
420
ajTagvalReplaceS(AjPTagval tagval,const AjPStr str)421 void ajTagvalReplaceS(AjPTagval tagval, const AjPStr str)
422 {
423 ajStrAssignS(&tagval->Value, str);
424 return;
425 }
426