gfile: add g_file_new_build_filename()

This is a convenience C API that combines g_build_filename() with
g_file_new_for_path().

https://bugzilla.gnome.org/show_bug.cgi?id=788488

docs/reference/gio/gio-sections.txt

@@ -85,6 +85,7 @@ g_file_new_for_commandline_arg
 g_file_new_for_commandline_arg_and_cwd
 g_file_new_tmp
 g_file_parse_name
+g_file_new_build_filename
 g_file_dup
 g_file_hash
 g_file_equal

gio/gfile.c

@@ -81,6 +81,7 @@
  * - g_file_new_for_commandline_arg() for a command line argument.
  * - g_file_new_tmp() to create a temporary file from a template.
  * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
+ * - g_file_new_build_filename() to create a file from path elements.
  *
  * One way to think of a #GFile is as an abstraction of a pathname. For
  * normal files the system pathname is what is stored internally, but as
@@ -6440,6 +6441,41 @@ g_file_parse_name (const char *parse_name)
   return g_vfs_parse_name (g_vfs_get_default (), parse_name);
 }
 
+/**
+ * g_file_new_build_filename:
+ * @first_element: (type filename): the first element in the path
+ * @...: remaining elements in path, terminated by %NULL
+ *
+ * Constructs a #GFile from a series of elements using the correct
+ * separator for filenames.
+ *
+ * Using this function is equivalent to calling g_build_filename(),
+ * followed by g_file_new_for_path() on the result.
+ *
+ * Returns: (transfer full): a new #GFile
+ *
+ * Since: 2.56
+ */
+GFile *
+g_file_new_build_filename (const gchar *first_element,
+                           ...)
+{
+  gchar *str;
+  GFile *file;
+  va_list args;
+
+  g_return_val_if_fail (first_element != NULL, NULL);
+
+  va_start (args, first_element);
+  str = g_build_filename_valist (first_element, &args);
+  va_end (args);
+
+  file = g_file_new_for_path (str);
+  g_free (str);
+
+  return file;
+}
+
 static gboolean
 is_valid_scheme_character (char c)
 {

gio/gfile.h

@@ -606,6 +606,9 @@ GFile *                 g_file_new_tmp                    (const char
                                                            GError                    **error);
 GLIB_AVAILABLE_IN_ALL
 GFile *                 g_file_parse_name                 (const char                 *parse_name);
+GLIB_AVAILABLE_IN_2_56
+GFile *                 g_file_new_build_filename         (const gchar                *first_element,
+                                                           ...) G_GNUC_NULL_TERMINATED;
 GLIB_AVAILABLE_IN_ALL
 GFile *                 g_file_dup                        (GFile                      *file);
 GLIB_AVAILABLE_IN_ALL

gio/tests/file.c

@@ -8,27 +8,47 @@
 #endif
 
 static void
-test_basic (void)
+test_basic_for_file (GFile       *file,
+                     const gchar *suffix)
 {
-  GFile *file;
   gchar *s;
 
-  file = g_file_new_for_path ("./some/directory/testfile");
-
   s = g_file_get_basename (file);
   g_assert_cmpstr (s, ==, "testfile");
   g_free (s);
 
   s = g_file_get_uri (file);
   g_assert (g_str_has_prefix (s, "file://"));
-  g_assert (g_str_has_suffix (s, "/some/directory/testfile"));
+  g_assert (g_str_has_suffix (s, suffix));
   g_free (s);
 
   g_assert (g_file_has_uri_scheme (file, "file"));
   s = g_file_get_uri_scheme (file);
   g_assert_cmpstr (s, ==, "file");
   g_free (s);
+}
 
+static void
+test_basic (void)
+{
+  GFile *file;
+
+  file = g_file_new_for_path ("./some/directory/testfile");
+  test_basic_for_file (file, "/some/directory/testfile");
+  g_object_unref (file);
+}
+
+static void
+test_build_filename (void)
+{
+  GFile *file;
+
+  file = g_file_new_build_filename (".", "some", "directory", "testfile", NULL);
+  test_basic_for_file (file, "/some/directory/testfile");
+  g_object_unref (file);
+
+  file = g_file_new_build_filename ("testfile", NULL);
+  test_basic_for_file (file, "/testfile");
   g_object_unref (file);
 }
 
@@ -1051,6 +1071,7 @@ main (int argc, char *argv[])
   g_test_bug_base ("http://bugzilla.gnome.org/");
 
   g_test_add_func ("/file/basic", test_basic);
+  g_test_add_func ("/file/build-filename", test_build_filename);
   g_test_add_func ("/file/parent", test_parent);
   g_test_add_func ("/file/child", test_child);
   g_test_add_func ("/file/type", test_type);