]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: wxcrt.h | |
3 | // Purpose: interface of global CRT wrapper functions | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** @addtogroup group_funcmacro_string */ | |
10 | //@{ | |
11 | ||
12 | /** | |
13 | Returns @true if the pointer @a p is either @NULL or points to an empty string, | |
14 | @false otherwise. | |
15 | ||
16 | @header{wx/wxcrt.h} | |
17 | */ | |
18 | bool wxIsEmpty(const char* p); | |
19 | ||
20 | /** | |
21 | This is a safe version of standard function @e strlen(): it does exactly | |
22 | the same thing (i.e. returns the length of the string) except that it | |
23 | returns 0 if @a p is the @NULL pointer. | |
24 | ||
25 | @header{wx/wxcrt.h} | |
26 | */ | |
27 | size_t wxStrlen(const char* p); | |
28 | ||
29 | /** | |
30 | This is a safe version of standard function @e strlen(): it returns the length | |
31 | of the string s in bytes if this length is smaller than @a maxlen bytes. | |
32 | Otherwise it returns @a maxlen. | |
33 | ||
34 | The @a maxlen parameter makes it easier to avoid array indexing errors | |
35 | since you are sure that wxStrnlen() won't read any memory exceeding the | |
36 | @c "*(p+maxlen)" location. | |
37 | ||
38 | @since 2.9.0 | |
39 | ||
40 | @header{wx/wxcrt.h} | |
41 | */ | |
42 | size_t wxStrnlen(const char* p, size_t maxlen); | |
43 | ||
44 | /** | |
45 | This function complements the standard C function @e stricmp() which | |
46 | performs case-insensitive comparison. | |
47 | ||
48 | @return A negative value, 0, or positive value if @a p1 is less than, | |
49 | equal to or greater than @a p2. The comparison is case-sensitive. | |
50 | ||
51 | @header{wx/wxcrt.h} | |
52 | */ | |
53 | int wxStrcmp(const char* p1, const char* p2); | |
54 | ||
55 | /** | |
56 | This function complements the standard C function @e strcmp() which performs | |
57 | case-sensitive comparison. | |
58 | ||
59 | @return A negative value, 0, or positive value if @a p1 is less than, | |
60 | equal to or greater than @e p2. The comparison is case-insensitive. | |
61 | ||
62 | @header{wx/wxcrt.h} | |
63 | */ | |
64 | int wxStricmp(const char* p1, const char* p2); | |
65 | ||
66 | /** | |
67 | @deprecated Use wxString::operator== instead. | |
68 | ||
69 | This macro is defined as: | |
70 | ||
71 | @code | |
72 | #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) | |
73 | @endcode | |
74 | ||
75 | @header{wx/wxcrt.h} | |
76 | */ | |
77 | bool wxStringEq(const wxString& s1, const wxString& s2); | |
78 | ||
79 | /** | |
80 | @deprecated Use wxString::Find() instead. | |
81 | ||
82 | Returns @true if the substring @a s1 is found within @a s2, ignoring case | |
83 | if @a exact is @false. If @a subString is @false, no substring matching is | |
84 | done. | |
85 | ||
86 | @header{wx/wxcrt.h} | |
87 | */ | |
88 | bool wxStringMatch(const wxString& s1, const wxString& s2, | |
89 | bool subString = true, bool exact = false); | |
90 | ||
91 | /** | |
92 | This is a convenience function wrapping wxStringTokenizer which simply | |
93 | returns all tokens found in the given @a string in an array. | |
94 | ||
95 | Please see wxStringTokenizer::wxStringTokenizer() for a description of the | |
96 | other parameters. | |
97 | ||
98 | @header{wx/wxcrt.h} | |
99 | */ | |
100 | wxArrayString wxStringTokenize(const wxString& string, | |
101 | const wxString& delims = wxDEFAULT_DELIMITERS, | |
102 | wxStringTokenizerMode mode = wxTOKEN_DEFAULT); | |
103 | ||
104 | /** | |
105 | Safe and more convenient replacement for strncpy(). | |
106 | ||
107 | This function copies the source string @a src to the destination buffer @a | |
108 | dst of size @a n without overflowing the buffer and ensuring that it is | |
109 | always @NUL-terminated. | |
110 | ||
111 | Example of use: | |
112 | @code | |
113 | char buf[256]; | |
114 | if ( wxStrlcpy(buf, GetSomeString(), WXSIZEOF(buf)) > WXSIZEOF(buf) ) | |
115 | ... handle truncation ... | |
116 | @endcode | |
117 | Notice that using wxStrncpy() in similar way is wrong, the above is broadly | |
118 | equivalent to | |
119 | @code | |
120 | char buf[256]; | |
121 | buf[WXSIZEOF(buf) - 1] = '\0'; | |
122 | wxStrncpy(buf, GetSomeString(), WXSIZEOF(buf) - 1); | |
123 | if ( buf[WXSIZEOF(buf) - 1] != '\0' ) | |
124 | { | |
125 | ... truncation occurred ... | |
126 | // need to NUL-terminate string manually | |
127 | buf[WXSIZEOF(buf) - 1] = '\0'; | |
128 | } | |
129 | @endcode | |
130 | which should explain the advantage of using wxStrlcpy(). | |
131 | ||
132 | Notice that this function is similar to the OpenBSD strlcpy() function. | |
133 | ||
134 | @param dst | |
135 | Destination buffer of size (greater or) equal to @a n. | |
136 | @param src | |
137 | @NUL-terminated source string. | |
138 | @param n | |
139 | The size of the destination buffer. | |
140 | @return | |
141 | The length of @a src, if the returned value is greater or equal to @a n | |
142 | then there was not enough space in the destination buffer and the | |
143 | string was truncated. | |
144 | ||
145 | @since 2.9.0 | |
146 | ||
147 | @header{wx/wxcrt.h} | |
148 | */ | |
149 | size_t wxStrlcpy(char *dst, const char *src, size_t n); | |
150 | ||
151 | /** | |
152 | This function replaces the dangerous standard function @e sprintf() and is | |
153 | like @e snprintf() available on some platforms. The only difference with | |
154 | @e sprintf() is that an additional argument - buffer size - is taken and | |
155 | the buffer is never overflowed. | |
156 | ||
157 | Returns the number of characters copied to the buffer or -1 if there is not | |
158 | enough space. | |
159 | ||
160 | @see wxVsnprintf(), wxString::Printf() | |
161 | ||
162 | @header{wx/wxcrt.h} | |
163 | */ | |
164 | int wxSnprintf(char* buf, size_t len, const char* format, ...); | |
165 | ||
166 | /** | |
167 | The same as wxSnprintf() but takes a @c va_list argument instead of an | |
168 | arbitrary number of parameters. | |
169 | ||
170 | @note If @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function | |
171 | supports positional arguments (see wxString::Printf() for more | |
172 | information). However other functions of the same family (wxPrintf(), | |
173 | wxSprintf(), wxFprintf(), wxVfprintf(), wxVfprintf(), wxVprintf(), | |
174 | wxVsprintf()) currently do not to support positional parameters even | |
175 | when @c wxUSE_PRINTF_POS_PARAMS is 1. | |
176 | ||
177 | @see wxSnprintf(), wxString::PrintfV() | |
178 | ||
179 | @header{wx/wxcrt.h} | |
180 | */ | |
181 | int wxVsnprintf(char* buf, size_t len, const char* format, va_list argPtr); | |
182 | ||
183 | //@} | |
184 |