Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjlib / include / pj / string.h
1 /* $Id$ */
2 /* 
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19  */
20 #ifndef __PJ_STRING_H__
21 #define __PJ_STRING_H__
22
23 /**
24  * @file string.h
25  * @brief PJLIB String Operations.
26  */
27
28 #include <pj/types.h>
29 #include <pj/compat/string.h>
30
31
32 PJ_BEGIN_DECL
33
34 /**
35  * @defgroup PJ_PSTR String Operations
36  * @ingroup PJ_DS
37  * @{
38  * This module provides string manipulation API.
39  *
40  * \section pj_pstr_not_null_sec PJLIB String is NOT Null Terminated!
41  *
42  * That is the first information that developers need to know. Instead
43  * of using normal C string, strings in PJLIB are represented as
44  * pj_str_t structure below:
45  *
46  * <pre>
47  *   typedef struct pj_str_t
48  *   {
49  *       char      *ptr;
50  *       pj_size_t  slen;
51  *   } pj_str_t;
52  * </pre>
53  *
54  * There are some advantages of using this approach:
55  *  - the string can point to arbitrary location in memory even
56  *    if the string in that location is not null terminated. This is
57  *    most usefull for text parsing, where the parsed text can just
58  *    point to the original text in the input. If we use C string,
59  *    then we will have to copy the text portion from the input
60  *    to a string variable.
61  *  - because the length of the string is known, string copy operation
62  *    can be made more efficient.
63  *
64  * Most of APIs in PJLIB that expect or return string will represent
65  * the string as pj_str_t instead of normal C string.
66  *
67  * \section pj_pstr_examples_sec Examples
68  *
69  * For some examples, please see:
70  *  - @ref page_pjlib_string_test
71  */
72
73 /**
74  * Create string initializer from a normal C string.
75  *
76  * @param str   Null terminated string to be stored.
77  *
78  * @return      pj_str_t.
79  */
80 PJ_IDECL(pj_str_t) pj_str(char *str);
81
82 /**
83  * Create constant string from normal C string.
84  *
85  * @param str   The string to be initialized.
86  * @param s     Null terminated string.
87  *
88  * @return      pj_str_t.
89  */
90 PJ_INLINE(const pj_str_t*) pj_cstr(pj_str_t *str, const char *s)
91 {
92     str->ptr = (char*)s;
93     str->slen = s ? (pj_ssize_t)strlen(s) : 0;
94     return str;
95 }
96
97 /**
98  * Set the pointer and length to the specified value.
99  *
100  * @param str       the string.
101  * @param ptr       pointer to set.
102  * @param length    length to set.
103  *
104  * @return the string.
105  */
106 PJ_INLINE(pj_str_t*) pj_strset( pj_str_t *str, char *ptr, pj_size_t length)
107 {
108     str->ptr = ptr;
109     str->slen = (pj_ssize_t)length;
110     return str;
111 }
112
113 /**
114  * Set the pointer and length of the string to the source string, which
115  * must be NULL terminated.
116  *
117  * @param str       the string.
118  * @param src       pointer to set.
119  *
120  * @return the string.
121  */
122 PJ_INLINE(pj_str_t*) pj_strset2( pj_str_t *str, char *src)
123 {
124     str->ptr = src;
125     str->slen = src ? (pj_ssize_t)strlen(src) : 0;
126     return str;
127 }
128
129 /**
130  * Set the pointer and the length of the string.
131  *
132  * @param str       The target string.
133  * @param begin     The start of the string.
134  * @param end       The end of the string.
135  *
136  * @return the target string.
137  */
138 PJ_INLINE(pj_str_t*) pj_strset3( pj_str_t *str, char *begin, char *end )
139 {
140     str->ptr = begin;
141     str->slen = (pj_ssize_t)(end-begin);
142     return str;
143 }
144
145 /**
146  * Assign string.
147  *
148  * @param dst       The target string.
149  * @param src       The source string.
150  *
151  * @return the target string.
152  */
153 PJ_IDECL(pj_str_t*) pj_strassign( pj_str_t *dst, pj_str_t *src );
154
155 /**
156  * Copy string contents.
157  *
158  * @param dst       The target string.
159  * @param src       The source string.
160  *
161  * @return the target string.
162  */
163 PJ_IDECL(pj_str_t*) pj_strcpy(pj_str_t *dst, const pj_str_t *src);
164
165 /**
166  * Copy string contents.
167  *
168  * @param dst       The target string.
169  * @param src       The source string.
170  *
171  * @return the target string.
172  */
173 PJ_IDECL(pj_str_t*) pj_strcpy2(pj_str_t *dst, const char *src);
174
175 /**
176  * Copy source string to destination up to the specified max length.
177  *
178  * @param dst       The target string.
179  * @param src       The source string.
180  * @param max       Maximum characters to copy.
181  *
182  * @return the target string.
183  */
184 PJ_IDECL(pj_str_t*) pj_strncpy(pj_str_t *dst, const pj_str_t *src, 
185                                pj_ssize_t max);
186
187 /**
188  * Copy source string to destination up to the specified max length,
189  * and NULL terminate the destination. If source string length is
190  * greater than or equal to max, then max-1 will be copied.
191  *
192  * @param dst       The target string.
193  * @param src       The source string.
194  * @param max       Maximum characters to copy.
195  *
196  * @return the target string.
197  */
198 PJ_IDECL(pj_str_t*) pj_strncpy_with_null(pj_str_t *dst, const pj_str_t *src,
199                                          pj_ssize_t max);
200
201 /**
202  * Duplicate string.
203  *
204  * @param pool      The pool.
205  * @param dst       The string result.
206  * @param src       The string to duplicate.
207  *
208  * @return the string result.
209  */
210 PJ_IDECL(pj_str_t*) pj_strdup(pj_pool_t *pool,
211                               pj_str_t *dst,
212                               const pj_str_t *src);
213
214 /**
215  * Duplicate string and NULL terminate the destination string.
216  *
217  * @param pool      The pool.
218  * @param dst       The string result.
219  * @param src       The string to duplicate.
220  *
221  * @return          The string result.
222  */
223 PJ_IDECL(pj_str_t*) pj_strdup_with_null(pj_pool_t *pool,
224                                         pj_str_t *dst,
225                                         const pj_str_t *src);
226
227 /**
228  * Duplicate string.
229  *
230  * @param pool      The pool.
231  * @param dst       The string result.
232  * @param src       The string to duplicate.
233  *
234  * @return the string result.
235  */
236 PJ_IDECL(pj_str_t*) pj_strdup2(pj_pool_t *pool,
237                                pj_str_t *dst,
238                                const char *src);
239
240 /**
241  * Duplicate string and NULL terminate the destination string.
242  *
243  * @param pool      The pool.
244  * @param dst       The string result.
245  * @param src       The string to duplicate.
246  *
247  * @return          The string result.
248  */
249 PJ_IDECL(pj_str_t*) pj_strdup2_with_null(pj_pool_t *pool,
250                                          pj_str_t *dst,
251                                          const char *src);
252
253
254 /**
255  * Duplicate string.
256  *
257  * @param pool      The pool.
258  * @param src       The string to duplicate.
259  *
260  * @return the string result.
261  */
262 PJ_IDECL(pj_str_t) pj_strdup3(pj_pool_t *pool, const char *src);
263
264 /**
265  * Return the length of the string.
266  *
267  * @param str       The string.
268  *
269  * @return the length of the string.
270  */
271 PJ_INLINE(pj_size_t) pj_strlen( const pj_str_t *str )
272 {
273     return str->slen;
274 }
275
276 /**
277  * Return the pointer to the string data.
278  *
279  * @param str       The string.
280  *
281  * @return the pointer to the string buffer.
282  */
283 PJ_INLINE(const char*) pj_strbuf( const pj_str_t *str )
284 {
285     return str->ptr;
286 }
287
288 /**
289  * Compare strings. 
290  *
291  * @param str1      The string to compare.
292  * @param str2      The string to compare.
293  *
294  * @return 
295  *      - < 0 if str1 is less than str2
296  *      - 0   if str1 is identical to str2
297  *      - > 0 if str1 is greater than str2
298  */
299 PJ_IDECL(int) pj_strcmp( const pj_str_t *str1, const pj_str_t *str2);
300
301 /**
302  * Compare strings.
303  *
304  * @param str1      The string to compare.
305  * @param str2      The string to compare.
306  *
307  * @return 
308  *      - < 0 if str1 is less than str2
309  *      - 0   if str1 is identical to str2
310  *      - > 0 if str1 is greater than str2
311  */
312 PJ_IDECL(int) pj_strcmp2( const pj_str_t *str1, const char *str2 );
313
314 /**
315  * Compare strings. 
316  *
317  * @param str1      The string to compare.
318  * @param str2      The string to compare.
319  * @param len       The maximum number of characters to compare.
320  *
321  * @return 
322  *      - < 0 if str1 is less than str2
323  *      - 0   if str1 is identical to str2
324  *      - > 0 if str1 is greater than str2
325  */
326 PJ_IDECL(int) pj_strncmp( const pj_str_t *str1, const pj_str_t *str2, 
327                           pj_size_t len);
328
329 /**
330  * Compare strings. 
331  *
332  * @param str1      The string to compare.
333  * @param str2      The string to compare.
334  * @param len       The maximum number of characters to compare.
335  *
336  * @return 
337  *      - < 0 if str1 is less than str2
338  *      - 0   if str1 is identical to str2
339  *      - > 0 if str1 is greater than str2
340  */
341 PJ_IDECL(int) pj_strncmp2( const pj_str_t *str1, const char *str2, 
342                            pj_size_t len);
343
344 /**
345  * Perform case-insensitive comparison to the strings.
346  *
347  * @param str1      The string to compare.
348  * @param str2      The string to compare.
349  *
350  * @return 
351  *      - < 0 if str1 is less than str2
352  *      - 0   if str1 is equal to str2
353  *      - > 0 if str1 is greater than str2
354  */
355 PJ_IDECL(int) pj_stricmp(const pj_str_t *str1, const pj_str_t *str2);
356
357 /**
358  * Perform lowercase comparison to the strings which consists of only
359  * alnum characters. More over, it will only return non-zero if both
360  * strings are not equal, not the usual negative or positive value.
361  *
362  * If non-alnum inputs are given, then the function may mistakenly 
363  * treat two strings as equal.
364  *
365  * @param str1      The string to compare.
366  * @param str2      The string to compare.
367  * @param len       The length to compare.
368  *
369  * @return 
370  *      - 0         if str1 is equal to str2
371  *      - (-1)      if not equal.
372  */
373 #if defined(PJ_HAS_STRICMP_ALNUM) && PJ_HAS_STRICMP_ALNUM!=0
374 PJ_IDECL(int) strnicmp_alnum(const char *str1, const char *str2,
375                              int len);
376 #else
377 #define strnicmp_alnum  pj_ansi_strnicmp
378 #endif
379
380 /**
381  * Perform lowercase comparison to the strings which consists of only
382  * alnum characters. More over, it will only return non-zero if both
383  * strings are not equal, not the usual negative or positive value.
384  *
385  * If non-alnum inputs are given, then the function may mistakenly 
386  * treat two strings as equal.
387  *
388  * @param str1      The string to compare.
389  * @param str2      The string to compare.
390  *
391  * @return 
392  *      - 0         if str1 is equal to str2
393  *      - (-1)      if not equal.
394  */
395 #if defined(PJ_HAS_STRICMP_ALNUM) && PJ_HAS_STRICMP_ALNUM!=0
396 PJ_IDECL(int) pj_stricmp_alnum(const pj_str_t *str1, const pj_str_t *str2);
397 #else
398 #define pj_stricmp_alnum    pj_stricmp
399 #endif
400
401 /**
402  * Perform case-insensitive comparison to the strings.
403  *
404  * @param str1      The string to compare.
405  * @param str2      The string to compare.
406  *
407  * @return 
408  *      - < 0 if str1 is less than str2
409  *      - 0   if str1 is identical to str2
410  *      - > 0 if str1 is greater than str2
411  */
412 PJ_IDECL(int) pj_stricmp2( const pj_str_t *str1, const char *str2);
413
414 /**
415  * Perform case-insensitive comparison to the strings.
416  *
417  * @param str1      The string to compare.
418  * @param str2      The string to compare.
419  * @param len       The maximum number of characters to compare.
420  *
421  * @return 
422  *      - < 0 if str1 is less than str2
423  *      - 0   if str1 is identical to str2
424  *      - > 0 if str1 is greater than str2
425  */
426 PJ_IDECL(int) pj_strnicmp( const pj_str_t *str1, const pj_str_t *str2, 
427                            pj_size_t len);
428
429 /**
430  * Perform case-insensitive comparison to the strings.
431  *
432  * @param str1      The string to compare.
433  * @param str2      The string to compare.
434  * @param len       The maximum number of characters to compare.
435  *
436  * @return 
437  *      - < 0 if str1 is less than str2
438  *      - 0   if str1 is identical to str2
439  *      - > 0 if str1 is greater than str2
440  */
441 PJ_IDECL(int) pj_strnicmp2( const pj_str_t *str1, const char *str2, 
442                             pj_size_t len);
443
444 /**
445  * Concatenate strings.
446  *
447  * @param dst       The destination string.
448  * @param src       The source string.
449  */
450 PJ_IDECL(void) pj_strcat(pj_str_t *dst, const pj_str_t *src);
451
452
453 /**
454  * Concatenate strings.
455  *
456  * @param dst       The destination string.
457  * @param src       The source string.
458  */
459 PJ_IDECL(void) pj_strcat2(pj_str_t *dst, const char *src);
460
461
462 /**
463  * Finds a character in a string.
464  *
465  * @param str       The string.
466  * @param chr       The character to find.
467  *
468  * @return the pointer to first character found, or NULL.
469  */
470 PJ_INLINE(char*) pj_strchr( const pj_str_t *str, int chr)
471 {
472     return (char*) memchr((char*)str->ptr, chr, str->slen);
473 }
474
475 /**
476  * Find the occurence of a substring substr in string str.
477  *
478  * @param str       The string to search.
479  * @param substr    The string to search fo.
480  *
481  * @return the pointer to the position of substr in str, or NULL. Note
482  *         that if str is not NULL terminated, the returned pointer
483  *         is pointing to non-NULL terminated string.
484  */
485 PJ_DECL(char*) pj_strstr(const pj_str_t *str, const pj_str_t *substr);
486
487 /**
488  * Performs substring lookup like pj_strstr() but ignores the case of
489  * both strings.
490  *
491  * @param str       The string to search.
492  * @param substr    The string to search fo.
493  *
494  * @return the pointer to the position of substr in str, or NULL. Note
495  *         that if str is not NULL terminated, the returned pointer
496  *         is pointing to non-NULL terminated string.
497  */
498 PJ_DECL(char*) pj_stristr(const pj_str_t *str, const pj_str_t *substr);
499
500 /**
501  * Remove (trim) leading whitespaces from the string.
502  *
503  * @param str       The string.
504  *
505  * @return the string.
506  */
507 PJ_DECL(pj_str_t*) pj_strltrim( pj_str_t *str );
508
509 /**
510  * Remove (trim) the trailing whitespaces from the string.
511  *
512  * @param str       The string.
513  *
514  * @return the string.
515  */
516 PJ_DECL(pj_str_t*) pj_strrtrim( pj_str_t *str );
517
518 /**
519  * Remove (trim) leading and trailing whitespaces from the string.
520  *
521  * @param str       The string.
522  *
523  * @return the string.
524  */
525 PJ_IDECL(pj_str_t*) pj_strtrim( pj_str_t *str );
526
527 /**
528  * Initialize the buffer with some random string. Note that the 
529  * generated string is not NULL terminated.
530  *
531  * @param str       the string to store the result.
532  * @param length    the length of the random string to generate.
533  *
534  * @return the string.
535  */
536 PJ_DECL(char*) pj_create_random_string(char *str, pj_size_t length);
537
538 /**
539  * Convert string to unsigned integer. The conversion will stop as
540  * soon as non-digit character is found or all the characters have
541  * been processed.
542  *
543  * @param str   the string.
544  *
545  * @return the unsigned integer.
546  */
547 PJ_DECL(unsigned long) pj_strtoul(const pj_str_t *str);
548
549 /**
550  * Convert strings to an unsigned long-integer value.
551  * This function stops reading the string input either when the number
552  * of characters has exceeded the length of the input or it has read 
553  * the first character it cannot recognize as part of a number, that is
554  * a character greater than or equal to base. 
555  *
556  * @param str       The input string.
557  * @param endptr    Optional pointer to receive the remainder/unparsed
558  *                  portion of the input.
559  * @param base      Number base to use.
560  *
561  * @return the unsigned integer number.
562  */
563 PJ_DECL(unsigned long) pj_strtoul2(const pj_str_t *str, pj_str_t *endptr,
564                                    unsigned base);
565
566 /**
567  * Utility to convert unsigned integer to string. Note that the
568  * string will be NULL terminated.
569  *
570  * @param val       the unsigned integer value.
571  * @param buf       the buffer
572  *
573  * @return the number of characters written
574  */
575 PJ_DECL(int) pj_utoa(unsigned long val, char *buf);
576
577 /**
578  * Convert unsigned integer to string with minimum digits. Note that the
579  * string will be NULL terminated.
580  *
581  * @param val       The unsigned integer value.
582  * @param buf       The buffer.
583  * @param min_dig   Minimum digits to be printed, or zero to specify no
584  *                  minimum digit.
585  * @param pad       The padding character to be put in front of the string
586  *                  when the digits is less than minimum.
587  *
588  * @return the number of characters written.
589  */
590 PJ_DECL(int) pj_utoa_pad( unsigned long val, char *buf, int min_dig, int pad);
591
592
593 /**
594  * Fill the memory location with zero.
595  *
596  * @param dst       The destination buffer.
597  * @param size      The number of bytes.
598  */
599 PJ_INLINE(void) pj_bzero(void *dst, pj_size_t size)
600 {
601 #if defined(PJ_HAS_BZERO) && PJ_HAS_BZERO!=0
602     bzero(dst, size);
603 #else
604     memset(dst, 0, size);
605 #endif
606 }
607
608
609 /**
610  * Fill the memory location with value.
611  *
612  * @param dst       The destination buffer.
613  * @param c         Character to set.
614  * @param size      The number of characters.
615  *
616  * @return the value of dst.
617  */
618 PJ_INLINE(void*) pj_memset(void *dst, int c, pj_size_t size)
619 {
620     return memset(dst, c, size);
621 }
622
623 /**
624  * Copy buffer.
625  *
626  * @param dst       The destination buffer.
627  * @param src       The source buffer.
628  * @param size      The size to copy.
629  *
630  * @return the destination buffer.
631  */
632 PJ_INLINE(void*) pj_memcpy(void *dst, const void *src, pj_size_t size)
633 {
634     return memcpy(dst, src, size);
635 }
636
637 /**
638  * Move memory.
639  *
640  * @param dst       The destination buffer.
641  * @param src       The source buffer.
642  * @param size      The size to copy.
643  *
644  * @return the destination buffer.
645  */
646 PJ_INLINE(void*) pj_memmove(void *dst, const void *src, pj_size_t size)
647 {
648     return memmove(dst, src, size);
649 }
650
651 /**
652  * Compare buffers.
653  *
654  * @param buf1      The first buffer.
655  * @param buf2      The second buffer.
656  * @param size      The size to compare.
657  *
658  * @return negative, zero, or positive value.
659  */
660 PJ_INLINE(int) pj_memcmp(const void *buf1, const void *buf2, pj_size_t size)
661 {
662     return memcmp(buf1, buf2, size);
663 }
664
665 /**
666  * Find character in the buffer.
667  *
668  * @param buf       The buffer.
669  * @param c         The character to find.
670  * @param size      The size to check.
671  *
672  * @return the pointer to location where the character is found, or NULL if
673  *         not found.
674  */
675 PJ_INLINE(void*) pj_memchr(const void *buf, int c, pj_size_t size)
676 {
677     return (void*)memchr((void*)buf, c, size);
678 }
679
680
681 /**
682  * @}
683  */
684
685 #if PJ_FUNCTIONS_ARE_INLINED
686 #  include <pj/string_i.h>
687 #endif
688
689 PJ_END_DECL
690
691 #endif  /* __PJ_STRING_H__ */
692