interface/wx/wxcrt.h

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