interface/wxcrt.h

   1 /////////////////////////////////////////////////////////////////////////////
   2     // Name:        wxcrt.h
   3     // Purpose:     documentation for global functions
   4     // Author:      wxWidgets team
   5     // RCS-ID:      $Id$
   6     // Licence:     wxWindows license
   7     /////////////////////////////////////////////////////////////////////////////
   8
   9     /**
  10     Returns a negative value, 0, or positive value if @e p1 is less than, equal
  11     to or greater than @e p2. The comparison is case-sensitive.
  12
  13     This function complements the standard C function @e stricmp() which performs
  14     case-insensitive comparison.
  15 */
  16 int wxStrcmp(const char * p1, const char * p2);
  17
  18
  19     /**
  20     @b NB: This function is obsolete, use wxString instead.
  21
  22     A macro defined as:
  23     @code
  24     #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
  25     @endcode
  26 */
  27 bool wxStringEq(const wxString& s1, const wxString& s2);
  28
  29 /**
  30     @b NB: This function is obsolete, use wxString::Find instead.
  31
  32     Returns @true if the substring @e s1 is found within @e s2,
  33     ignoring case if @e exact is @false. If @e subString is @false,
  34     no substring matching is done.
  35 */
  36 bool wxStringMatch(const wxString& s1, const wxString& s2,
  37                    bool subString = @true,
  38                    bool exact = @false);
  39
  40 /**
  41     This function replaces the dangerous standard function @c sprintf() and is
  42     like @c snprintf() available on some platforms. The only difference with
  43     sprintf() is that an additional argument - buffer size - is taken and the
  44     buffer is never overflowed.
  45
  46     Returns the number of characters copied to the buffer or -1 if there is not
  47     enough space.
  48
  49     @sa wxVsnprintf, wxString::Printf
  50 */
  51 int wxSnprintf(wxChar * buf, size_t len, const wxChar * format,
  52                 ...);
  53
  54 /**
  55     This is a convenience function wrapping
  56     wxStringTokenizer which simply returns all tokens
  57     found in the given @e str in an array.
  58
  59     Please see
  60     wxStringTokenizer::wxStringTokenizer
  61     for the description of the other parameters.
  62 */
  63 wxArrayString wxStringTokenize(const wxString& str,
  64                                const wxString& delims = wxDEFAULT_DELIMITERS,
  65                                wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
  66
  67 /**
  68     This is a safe version of standard function @e strlen(): it does exactly the
  69     same thing (i.e. returns the length of the string) except that it returns 0 if
  70     @e p is the @NULL pointer.
  71 */
  72 size_t wxStrlen(const char * p);
  73
  74 /**
  75     The same as wxSnprintf but takes a @c va_list
  76     argument instead of arbitrary number of parameters.
  77
  78     Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
  79     positional arguments (see wxString::Printf for more information).
  80     However other functions of the same family (wxPrintf, wxSprintf, wxFprintf,
  81     wxVfprintf,
  82     wxVfprintf, wxVprintf, wxVsprintf) currently do not to support positional
  83     parameters
  84     even when @c wxUSE_PRINTF_POS_PARAMS is 1.
  85
  86     @sa wxSnprintf, wxString::PrintfV
  87 */
  88 int wxVsnprintf(wxChar * buf, size_t len, const wxChar * format,
  89                 va_list argPtr);
  90
  91 /**
  92     Returns @true if the pointer is either @NULL or points to an empty
  93     string, @false otherwise.
  94 */
  95 bool wxIsEmpty(const char * p);
  96
  97 /**
  98     Returns a negative value, 0, or positive value if @e p1 is less than, equal
  99     to or greater than @e p2. The comparison is case-insensitive.
 100
 101     This function complements the standard C function @e strcmp() which performs
 102     case-sensitive comparison.
 103 */
 104 int wxStricmp(const char * p1, const char * p2);
 105