summaryrefslogtreecommitdiff
path: root/doc/helper_headers.rst
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff-webhosting.net>2022-10-24 21:03:42 +0200
committerJörg Frings-Fürst <debian@jff-webhosting.net>2022-10-24 21:03:42 +0200
commit532d4a24e2013262dfa41fd85c06a9715c99abf7 (patch)
tree3b7f4fac1e983ead408c20a2f330b41aa2399ab1 /doc/helper_headers.rst
parenta1bdcfa3ca8af4ddb69ee57d716aa943cf3fe94a (diff)
New upstream version 4.7upstream/4.7
Diffstat (limited to 'doc/helper_headers.rst')
-rw-r--r--doc/helper_headers.rst128
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.