From 2566377e2a9d2085119757660d6f47273733b703 Mon Sep 17 00:00:00 2001
From: Celine Mercier <celine.mercier@metabarcoding.org>
Date: Mon, 25 Apr 2016 18:02:58 +0200
Subject: [PATCH] Updated the documentation for utils functions

---
 src/utils.c | 42 +++++++++++++++++++++++++++++++++++-------
 src/utils.h | 30 +++++++++++++++++++++++++++---
 2 files changed, 62 insertions(+), 10 deletions(-)

diff --git a/src/utils.c b/src/utils.c
index c569141..ccdca0b 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -17,11 +17,11 @@
 #include <stdlib.h>
 #include <dirent.h>
 #include <unistd.h>
+#include <time.h>
 
 #include "utils.h"
 #include "obidebug.h"
 #include "obierrno.h"
-#include "obidms.h"
 
 
 #define DEBUG_LEVEL 0	// TODO has to be defined somewhere else (cython compil flag?)
@@ -35,17 +35,17 @@
  **********************************************************************/
 
 
-int count_dir(char *dir)
+int count_dir(char* dir_path)
 {
-	struct dirent *dp;
-	DIR *fd;
-	int count;
+	struct dirent* dp;
+	DIR*           fd;
+	int            count;
 
 	count = 0;
-	if ((fd = opendir(dir)) == NULL)
+	if ((fd = opendir(dir_path)) == NULL)
 	{
 		obi_set_errno(OBI_UTILS_ERROR);
-		obidebug(1, "Error opening a directory: %s\n", dir);
+		obidebug(1, "Error opening a directory: %s\n", dir_path);
 		return -1;
 	}
 	while ((dp = readdir(fd)) != NULL)
@@ -54,5 +54,33 @@ int count_dir(char *dir)
 			continue;
 		count++;
 	}
+
 	return count;
 }
+
+
+char* obi_format_date(time_t date)
+{
+	char*       formatted_time;
+	struct tm*  tmp;
+
+	formatted_time = (char*) malloc(FORMATTED_TIME_LENGTH*sizeof(char));
+
+	tmp = localtime(&date);
+	if (tmp == NULL)
+	{
+		obi_set_errno(OBICOL_UNKNOWN_ERROR);
+		obidebug(1, "\nError formatting a date");
+		return NULL;
+	}
+
+	if (strftime(formatted_time, FORMATTED_TIME_LENGTH, "%c", tmp) == 0)
+	{
+		obi_set_errno(OBICOL_UNKNOWN_ERROR);
+		obidebug(1, "\nError formatting a date");
+		return NULL;
+	}
+
+	return formatted_time;
+}
+
diff --git a/src/utils.h b/src/utils.h
index 2b4f43a..fff78c0 100644
--- a/src/utils.h
+++ b/src/utils.h
@@ -19,14 +19,38 @@
 #include "obidms.h"
 
 
+#define FORMATTED_TIME_LENGTH (1024)    /**< The length allocated for the character string containing a formatted date.
+ 	 	 	 	 	 	 	 	 	     */
 #define ONE_IF_ZERO(x) (((x)==0)?1:(x))	/**< If x is equal to 0, x takes the value 1.
                                 	   	 */
 
 
-/*
- * TODO
+/**
+ * @brief Counts the number of files and directories in a directory.
+ *
+ * @param dir_path The absolute path of the directory.
+ *
+ * @returns The number of files and directories in the directory.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
  */
-int count_dir(char *dir);
+int count_dir(char* dir_path);
+
+
+/**
+ * @brief Formats a date in a way that is easy to read.
+ *
+ * @warning The pointer returned must be freed by the caller.
+ *
+ * @param date A date.
+ *
+ * @returns The date formatted in a way that is easy to read.
+ *
+ * @since October 2015
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
+char* obi_format_date(time_t date);
 
 
 #endif /* UTILS_H_ */