[glib: 1/5] gstrfuncs: Clarify that g_ascii_strtoull() accepts signed numbers

[Philip Withnall <pwithnall src gnome org>]

commit 8d0a163000b02c1bae6a0a8b279a11990ce8ad54
Author: Philip Withnall <withnall endlessm com>
Date:   Tue Dec 4 12:51:09 2018 +0000

    gstrfuncs: Clarify that g_ascii_strtoull() accepts signed numbers
    
    It’s perverse, but explicitly documented that strtoull() accepts numbers
    with a leading minus sign (`-`) and explicitly casts them to signed
    output.
    
    g_ascii_strtoull() is documented to do what strtoull() does (but locale
    independently), and its behaviour is correct. However, the documentation
    could be a lot clearer about this unexpected behaviour.
    
    Add a unit test for it too.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 glib/gstrfuncs.c      | 5 +++++
 glib/tests/strfuncs.c | 1 +
 2 files changed, 6 insertions(+)
---
diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index a9889dd50..4bde7dbd1 100644
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -1140,6 +1140,11 @@ g_parse_long_long (const gchar  *nptr,
  * changing the current locale, since that would not be
  * thread-safe.
  *
+ * Note that input with a leading minus sign (`-`) is accepted, and will return
+ * the negation of the parsed number, unless that would overflow a #guint64.
+ * Critically, this means you cannot assume that a short fixed length input will
+ * never result in a low return value, as the input could have a leading `-`.
+ *
  * This function is typically used when reading configuration
  * files or other non-user input that should be locale independent.
  * To handle input from the user you should normally use the
diff --git a/glib/tests/strfuncs.c b/glib/tests/strfuncs.c
index d974ad436..a2d059009 100644
--- a/glib/tests/strfuncs.c
+++ b/glib/tests/strfuncs.c
@@ -1098,6 +1098,7 @@ test_strtoll (void)
   check_uint64 ("18446744073709551616", "", 10, G_MAXUINT64, ERANGE);
   check_uint64 ("20xyz", "xyz", 10, 20, 0);
   check_uint64 ("-1", "", 10, G_MAXUINT64, 0);
+  check_uint64 ("-FF4", "", 16, -((guint64) 0xFF4), 0);
 
   check_int64 ("0", "", 10, 0, 0);
   check_int64 ("9223372036854775807", "", 10, G_MAXINT64, 0);