From 8c1743cb3ebd33bacebdff8978c2047716ca26dc Mon Sep 17 00:00:00 2001
From: Nick Treleaven <nick.treleaven@btinternet.com>
Date: Thu, 17 Sep 2009 16:47:45 +0000
Subject: [PATCH] Add foreach_dir() API macro. Update API docs for
 utils_get_file_list().

git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@4203 ea778897-0a13-0410-b9d1-a72fbfd435f5
---
 ChangeLog   |  3 +++
 src/utils.c | 31 +++++++++++++++++--------------
 src/utils.h |  8 ++++++++
 3 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index eead0592c..b12fc49f7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -3,6 +3,9 @@
  * plugins/filebrowser.c:
    Free file list memory whilst iterating the list.
    Minor formatting fixes.
+ * src/utils.c, src/utils.h:
+   Add foreach_dir() API macro.
+   Update API docs for utils_get_file_list().
 
 
 2009-09-16  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
diff --git a/src/utils.c b/src/utils.c
index 342c69618..22998078f 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -1342,23 +1342,30 @@ gint utils_mkdir(const gchar *path, gboolean create_parent_dirs)
 
 
 /**
- *  Gets a sorted list of files from the specified directory.
- *  Locale encoding is expected for path and used for the file list. The list and the data
- *  in the list should be freed after use.
+ * Gets a sorted list of files from the specified directory.
+ * Locale encoding is expected for @a path and used for the file list. The list and the data
+ * in the list should be freed after use, e.g.:
+ * @code
+ * g_slist_foreach(list, (GFunc) g_free, NULL);
+ * g_slist_free(list); @endcode
  *
- *  @param path The path of the directory to scan, in locale encoding.
- *  @param length The location to store the number of non-@c NULL data items in the list,
- *                unless @c NULL.
- *  @param error The is the location for storing a possible error, or @c NULL.
+ * @note If you don't want sorted filenames you should use the foreach_dir() macro instead -
+ * it's more efficient and perhaps easier to use than freeing the list and its contents.
  *
- *  @return A newly allocated list or @c NULL if no files found. The list and its data should be
- *          freed when no longer needed.
+ * @param path The path of the directory to scan, in locale encoding.
+ * @param length The location to store the number of non-@c NULL data items in the list,
+ *               unless @c NULL.
+ * @param error The location for storing a possible error, or @c NULL.
+ *
+ * @return A newly allocated list or @c NULL if no files found. The list and its data should be
+ *         freed when no longer needed.
  **/
 GSList *utils_get_file_list(const gchar *path, guint *length, GError **error)
 {
 	GSList *list = NULL;
 	guint len = 0;
 	GDir *dir;
+	const gchar *filename;
 
 	if (error)
 		*error = NULL;
@@ -1370,12 +1377,8 @@ GSList *utils_get_file_list(const gchar *path, guint *length, GError **error)
 	if (dir == NULL)
 		return NULL;
 
-	while (1)
+	foreach_dir(filename, dir)
 	{
-		const gchar *filename = g_dir_read_name(dir);
-		if (filename == NULL)
-			break;
-
 		list = g_slist_insert_sorted(list, g_strdup(filename), (GCompareFunc) utils_str_casecmp);
 		len++;
 	}
diff --git a/src/utils.h b/src/utils.h
index 1b03aff7a..ee7958d3e 100644
--- a/src/utils.h
+++ b/src/utils.h
@@ -91,6 +91,14 @@
 #define foreach_slist(node, list) \
 	foreach_list(node, list)
 
+/** Iterates through each unsorted filename in a @c GDir.
+ * @param filename (@c const @c gchar*) locale-encoded filename, without path. Do not modify or free.
+ * @param dir @c GDir created with @c g_dir_open(). Call @c g_dir_close() afterwards.
+ * @see utils_get_file_list() if you want a sorted list.
+ * @since Geany 0.19. */
+#define foreach_dir(filename, dir)\
+	for ((filename) = g_dir_read_name(dir); (filename) != NULL; (filename) = g_dir_read_name(dir))
+
 
 void utils_open_browser(const gchar *uri);