[glib] gutf8: Clarify return value docs for g_utf8_find_next_char()

[Philip Withnall <pwithnall src gnome org>]

commit 1366ce7ee004f97886807b9fede205c0af8b1a17
Author: Philip Withnall <withnall endlessm com>
Date:   Tue Jun 20 13:41:10 2017 +0100

    gutf8: Clarify return value docs for g_utf8_find_next_char()
    
    Make it clearer that it will only return NULL if @end is non-NULL. Add a
    test for this too.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    https://bugzilla.gnome.org/show_bug.cgi?id=773842

 glib/gutf8.c              |    8 +++++++-
 glib/tests/utf8-pointer.c |    9 +++++++++
 2 files changed, 16 insertions(+), 1 deletions(-)
---
diff --git a/glib/gutf8.c b/glib/gutf8.c
index e9191e2..e0d0850 100644
--- a/glib/gutf8.c
+++ b/glib/gutf8.c
@@ -162,7 +162,13 @@ g_utf8_find_prev_char (const char *str,
  * is made to see if the character found is actually valid other than
  * it starts with an appropriate byte.
  * 
- * Returns: a pointer to the found character or %NULL
+ * If @end is %NULL, the return value will never be %NULL: if the end of the
+ * string is reached, a pointer to the terminating nul byte is returned. If
+ * @end is non-%NULL, the return value will be %NULL if the end of the string
+ * is reached.
+ *
+ * Returns: (nullable): a pointer to the found character or %NULL if @end is
+ *    set and is reached
  */
 gchar *
 g_utf8_find_next_char (const gchar *p,
diff --git a/glib/tests/utf8-pointer.c b/glib/tests/utf8-pointer.c
index df1f442..c29ea3e 100644
--- a/glib/tests/utf8-pointer.c
+++ b/glib/tests/utf8-pointer.c
@@ -128,6 +128,15 @@ test_find (void)
 
   q = g_utf8_find_next_char (str + strlen (str), NULL);
   g_assert (q == str + strlen (str) + 1);
+
+  /* Check return values when reaching the end of the string,
+   * with @end set and unset. */
+  q = g_utf8_find_next_char (str + 10, NULL);
+  g_assert_nonnull (q);
+  g_assert (*q == '\0');
+
+  q = g_utf8_find_next_char (str + 10, str + 11);
+  g_assert_null (q);
 }
 
 int main (int argc, char *argv[])