docs: Add a cute trick for achieving a stable sort

This trick is inspired by
http://www.gnu.org/s/hello/manual/libc/Array-Sort-Function.html
http://jeffreystedfast.blogspot.com/2011/04/optimizing-merge-sort.html

diff --git a/glib/garray.c b/glib/garray.c
index e3d872b..231db52 100644 (file)
--- a/glib/garray.c
+++ b/glib/garray.c
@@ -1560,7 +1560,10 @@ g_byte_array_remove_range (GByteArray *array,
  * first arg is greater than second arg).
  *
  * If two array elements compare equal, their order in the sorted array
- * is undefined.
+ * is undefined. If you want equal elements to keep their order - ie
+ * you want a stable sort - you can write a comparison function that,
+ * if two elements would otherwise compare equal, it compares them by
+ * their addresses.
  **/
 void
 g_byte_array_sort (GByteArray   *array,