unify include guard defines, __$FILENAME__
[blender-staging.git] / source / blender / blenlib / BLI_string.h
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License
6  * as published by the Free Software Foundation; either version 2
7  * of the License, or (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software Foundation,
16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17  *
18  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
19  * All rights reserved.
20  *
21  * The Original Code is: all of this file.
22  *
23  * Contributor(s): none yet.
24  *
25  * ***** END GPL LICENSE BLOCK *****
26  */
27
28 #ifndef __BLI_STRING_H__
29 #define __BLI_STRING_H__
30
31 /** \file BLI_string.h
32  *  \ingroup bli
33  */
34
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38
39         /**
40          * Duplicates the cstring @a str into a newly mallocN'd
41          * string and returns it.
42          * 
43          * @param str The string to be duplicated
44          * @retval Returns the duplicated string
45          */
46 char *BLI_strdup(const char *str);
47
48         /**
49          * Duplicates the first @a len bytes of cstring @a str 
50          * into a newly mallocN'd string and returns it. @a str
51          * is assumed to be at least len bytes long.
52          * 
53          * @param str The string to be duplicated
54          * @param len The number of bytes to duplicate
55          * @retval Returns the duplicated string
56          */
57 char *BLI_strdupn(const char *str, const size_t len);
58
59         /**
60          * Appends the two strings, and returns new mallocN'ed string
61          * @param str1 first string for copy
62          * @param str2 second string for append
63          * @retval Returns dst
64          */
65 char *BLI_strdupcat(const char *str1, const char *str2);
66
67         /** 
68          * Like strncpy but ensures dst is always
69          * '\0' terminated.
70          * 
71          * @param dst Destination for copy
72          * @param src Source string to copy
73          * @param maxncpy Maximum number of characters to copy (generally
74          *   the size of dst)
75          * @retval Returns dst
76          */
77 char *BLI_strncpy(char *dst, const char *src, const size_t maxncpy);
78
79         /* Makes a copy of the text within the "" that appear after some text 'blahblah'
80          * i.e. for string 'pose["apples"]' with prefix 'pose[', it should grab "apples"
81          * 
82          *      - str: is the entire string to chop
83          *      - prefix: is the part of the string to leave out 
84          *
85          * Assume that the strings returned must be freed afterwards, and that the inputs will contain 
86          * data we want...
87          */
88 char *BLI_getQuotedStr(const char *str, const char *prefix);
89
90         /**
91          * Returns a copy of the cstring @a str into a newly mallocN'd
92          * string with all instances of oldText replaced with newText,
93          * and returns it.
94          * 
95          * @param str The string to replace occurances of oldText in
96          * @param oldText The text in the string to find and replace
97          * @param newText The text in the string to find and replace
98          * @retval Returns the duplicated string
99          */
100 char *BLI_replacestr(char *str, const char *oldText, const char *newText);
101
102         /* 
103          * Replacement for snprintf
104          */
105 size_t BLI_snprintf(char *buffer, size_t len, const char *format, ...)
106 #ifdef __GNUC__
107 __attribute__ ((format (printf, 3, 4)))
108 #endif
109 ;
110
111         /* 
112          * Print formatted string into a newly mallocN'd string
113          * and return it.
114          */
115 char *BLI_sprintfN(const char *format, ...)
116 #ifdef __GNUC__
117 __attribute__ ((format (printf, 1, 2)))
118 #endif
119 ;
120
121 size_t BLI_strescape(char *dst, const char *src, const size_t maxlen);
122
123         /**
124          * Compare two strings without regard to case.
125          * 
126          * @retval True if the strings are equal, false otherwise.
127          */
128 int BLI_strcaseeq(const char *a, const char *b);
129
130 char *BLI_strcasestr(const char *s, const char *find);
131 int BLI_strcasecmp(const char *s1, const char *s2);
132 int BLI_strncasecmp(const char *s1, const char *s2, size_t len);
133 int BLI_natstrcmp(const char *s1, const char *s2);
134 size_t BLI_strnlen(const char *str, size_t maxlen);
135 void BLI_timestr(double _time, char *str); /* time var is global */
136
137 void BLI_ascii_strtolower(char *str, int len);
138 void BLI_ascii_strtoupper(char *str, int len);
139
140 #ifdef __cplusplus
141 }
142 #endif
143
144 #endif