diff options
Diffstat (limited to 'doc/helper_headers.rst')
| -rw-r--r-- | doc/helper_headers.rst | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/doc/helper_headers.rst b/doc/helper_headers.rst new file mode 100644 index 0000000..7b4c083 --- /dev/null +++ b/doc/helper_headers.rst @@ -0,0 +1,128 @@ +============== +Helper headers +============== + +ctype helpers +============= + +Functions from the ``<ctype.h>`` header, including, but not limited to, +``isalpha``, ``tolower``, and so forth, are defined to take an ``int`` as first +argument. C strings consist of ``char``s, which may either be ``signed`` or +``unsigned``. It does not matter for *characters_* but since ``char``s are +implicitly convertible to *numbers*, one needs to explicitly cast chars to +unsigned before feeding them to ``isalpha``. + +.. code-block:: c + + /* “hyvää yötä”, UTF-8 encoded */ + + const char h[] = {'h', 'y', 'v', 0xc3, 0xa4, 0xc3, 0xa4, ' ', + 'y', 0xc3, 0xb6, 't', 0xc3, 0xa4}; + +libHX's ctype_helper.h therefore provides wrappers with a different function +signature that does the intended test. It does so by always taking ``unsigned +char``. The implication is that EOF cannot be passed to ``HX_isalpha`` — not +that there is a good reason to do so in the first place. + +.. code-block:: c + + #include <libHX/ctype_helper.h> + + bool HX_isalnum(unsigned char c); + bool HX_isalpha(unsigned char c); + bool HX_isdigit(unsigned char c); + bool HX_islower(unsigned char c); + bool HX_isprint(unsigned char c); + bool HX_isspace(unsigned char c); + bool HX_isupper(unsigned char c); + bool HX_isxdigit(unsigned char c); + unsigned char HX_tolower(unsigned char c); + unsigned char HX_toupper(unsigned char c); + +The ``HX_is*`` functions also differ from ctype's in that they return ``bool`` +instead of ``int``. Not all functions from ``ctype.h`` are present either; +``isascii``, ``isblank``, ``iscntrl``, ``isgraph``, ``ispunct`` and +``isxdigit`` have been omitted as the author has never needed them to this +date. + + +libxml2 helpers +=============== + +libxml2 defines a type called ``xmlChar`` for use within its strings. +``xmlChar`` is typedef'ed to ``unsigned char`` by libxml2, causing compiler warnings related to +differing signedness whenever interacting with strings from the +outside world, which are usually just a pointer to char. Because +casting is a real chore, ``libxml_helper.h`` will do it by +providing some wrappers with better argument types. + +.. code-block:: c + + #include <libHX/libxml_helper.h> + + int xml_strcmp(const xmlChar *a, const char *b); + int xml_strcasecmp(const xmlChar *a, const char *b); + + char *xml_getprop(xmlNode *node, const char *attr); + char *xml_getnsprop(xmlNode *node, const char *nsprefix, const char *attr); + xmlAttr *xml_newprop(xmlNode *node, const char *attr); + xmlNode *xml_newnode(xmlNode *parent, const char *name, const char *value); + xmlAttr *xml_setprop(xmlNode *node, const char *name, const char *value); + +The functions map to ``strcmp``, ``strcasecmp``, ``xmlGetProp``, +``xmlNewPropxmlNewProp``, ``xmlNewTextNodexmlNewTextNode`` and +``xmlSetPropxmlSetProp``, respectively. + +``xml_getnsprop`` works similar to ``xmlGetNsProp``, but instead of taking a +namespace URI, it does a lookup by namespace prefix. The argument order is also +different compared to ``xmlGetNsProp``. + + +wxWidgets +========= + +.. code-block:: c++ + + #include <libHX/wx_helper.hpp> + +Shortcut macros +--------------- + +``wxACV`` + Expands to ``wxALIGN_CENTER_VERTICAL``. + +``wxCDF`` + Expands to a set of common dialog flags for wxDialogs, which includes + ``wxDEFAULT_FRAME_STYLE`` and a flag such that the dialog does not + create a new window in the task bar (``wxFRAME_NO_TASKBAR``). + +``wxDPOS`` + Expands to ``wxDefaultPosition``. + +``wxDSIZE`` + Expands to ``wxDefaultSize``. + +``wxDSPAN`` + Expands to ``wxDefaultSpan``. + +String conversion +----------------- + +.. code-block:: c++ + + wxString wxfu8(const char *); + wxString wxfv8(const char *); + const char *wxtu8(const wxString &); + +``wxfu8`` + Converts a UTF-8 string to a ``wxString`` object. + +``wxfv8`` + Converts a UTF-8 string to an entity usable by ``wxPrintf``. + +``wxtu8`` + Converts a wxString to a pointer to char usable by ``printf``. Note + that the validity of the pointer is very limited and usually does not + extend beyond the statement in which it is used. Hence, storing the + pointer in a variable (``const char *p = wxtu8(s);``) will make ``p`` + dangling as soon as the assignment has been completed. |