]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/wxcrt.h
do not use preprocessor macros in interface headers; doxygen doesn't know about prepr...
[wxWidgets.git] / interface / wx / wxcrt.h
... / ...
CommitLineData
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*/
18bool 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*/
27size_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*/
42size_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*/
53int 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*/
64int 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*/
77bool 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*/
88bool 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*/
100wxArrayString 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 */
149size_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*/
164int 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*/
181int wxVsnprintf(char* buf, size_t len, const char* format, va_list argPtr);
182
183//@}
184