SF.net SVN: geany:[4203] trunk

[ntrel at users.sourceforge.net]

Revision: 4203
          http://geany.svn.sourceforge.net/geany/?rev=4203&view=rev
Author:   ntrel
Date:     2009-09-17 16:47:45 +0000 (Thu, 17 Sep 2009)

Log Message:
-----------
Add foreach_dir() API macro.
Update API docs for utils_get_file_list().

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/src/utils.c
    trunk/src/utils.h

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog	2009-09-17 16:39:11 UTC (rev 4202)
+++ trunk/ChangeLog	2009-09-17 16:47:45 UTC (rev 4203)
@@ -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>

Modified: trunk/src/utils.c
===================================================================
--- trunk/src/utils.c	2009-09-17 16:39:11 UTC (rev 4202)
+++ trunk/src/utils.c	2009-09-17 16:47:45 UTC (rev 4203)
@@ -1342,23 +1342,30 @@
 
 
 /**
- *  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- at 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- at 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 @@
 	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++;
 	}

Modified: trunk/src/utils.h
===================================================================
--- trunk/src/utils.h	2009-09-17 16:39:11 UTC (rev 4202)
+++ trunk/src/utils.h	2009-09-17 16:47:45 UTC (rev 4203)
@@ -91,7 +91,15 @@
 #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);
 
 gint utils_get_line_endings(const gchar* buffer, glong size);


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.