From 0e941418d139a77a0a505f28e42562bd20b452ba Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 28 Apr 2023 11:17:23 +0100 Subject: docs: Document high-level UTF-8 requirements for GLib MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I’ve finally found the right place in the docs to put this stuff. This doesn’t auto-link this section from every string in the GLib documentation, but I think that at this point (with gtk-doc in maintenance mode, and gi-docgen not fully applied to GLib) I don’t think we can do any better. The perfect is the enemy of the good, and having this stuff documented somewhere means that someone can link to it from multiple places in future *somehow*. Signed-off-by: Philip Withnall Fixes: #116 --- docs/reference/glib/programming.xml | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/reference/glib/programming.xml b/docs/reference/glib/programming.xml index 2c38fee5d..9efa19d33 100644 --- a/docs/reference/glib/programming.xml +++ b/docs/reference/glib/programming.xml @@ -30,6 +30,36 @@ to test all the allocation failure code paths. + +UTF-8 and String Encoding + + +All GLib, GObject and GIO functions accept and return strings in +UTF-8 encoding +unless otherwise specified. + + + +Input strings to function calls are not checked to see if +they are valid UTF-8: it is the application developer’s responsibility to +validate input strings at the time of input, either at the program or library +boundary, and to only use valid UTF-8 string constants in their application. +If GLib were to UTF-8 validate all string inputs to all functions, there would +be a significant drop in performance. + + +Similarly, output strings from functions are guaranteed to be in UTF-8, +and this does not need to be validated by the calling function. If a function +returns invalid UTF-8 (and is not documented as doing so), that’s a bug. + + + +See g_utf8_validate() +and g_utf8_make_valid() +for validating UTF-8 input. + + + Threads -- cgit v1.2.1