[Pmplib-commits] SF.net SVN: pmplib: [186] trunk/pmplib/lib/filepath

[<suc...@us...>]

Revision: 186
Author:   sucknblow
Date:     2006-08-12 19:51:10 -0700 (Sat, 12 Aug 2006)
ViewCVS:  http://svn.sourceforge.net/pmplib/?rev=186&view=rev

Log Message:
-----------
Start of APIdox for filepath.

Modified Paths:
--------------
    trunk/pmplib/lib/filepath/filepath_posix.c

Added Paths:
-----------
    trunk/pmplib/lib/filepath/Mainpage.dox
Added: trunk/pmplib/lib/filepath/Mainpage.dox
===================================================================
--- trunk/pmplib/lib/filepath/Mainpage.dox	                        (rev 0)
+++ trunk/pmplib/lib/filepath/Mainpage.dox	2006-08-13 02:51:10 UTC (rev 186)
@@ -0,0 +1,5 @@
+/** 
+ * @defgroup filepath File and path name library.
+ * Functions for working with file and path names with different path
+ * separators.
+ */

Modified: trunk/pmplib/lib/filepath/filepath_posix.c
===================================================================
--- trunk/pmplib/lib/filepath/filepath_posix.c	2006-08-13 01:26:12 UTC (rev 185)
+++ trunk/pmplib/lib/filepath/filepath_posix.c	2006-08-13 02:51:10 UTC (rev 186)
@@ -22,6 +22,16 @@
 
 /* $Id$ */
 
+/** 
+ * @file
+ * 
+ * Functions for working with file and path names with different path
+ * separators (POSIX implementation).
+ *
+ * @addtogroup filepath
+ * @{
+ */
+
 #ifdef	HAVE_CONFIG_H
 #include <config.h>
 #endif/*HAVE_CONFIG_H*/
@@ -103,6 +113,22 @@
 	return 0;
 }
 
+/** 
+ * Finds the file name extension in a native path name.
+ * 
+ * Checks if the file name in the given @p path has a file name
+ * extension: that is, whether the part of the path after the last
+ * path separator contains a period ('.').  If the @p path has an
+ * extension a pointer to the first character after the last period
+ * is returned (or a pointer to the null terminator if there are no
+ * subsequent characters).  If the file name has no extension, then
+ * null itself is returned.
+ * 
+ * @param path the path name to be searched for an extension.
+ * 
+ * @return a pointer to the file name extension, or NULL if none was
+ *         found.
+ */
 static ucs2char_t* search_extension(ucs2char_t* path)
 {
 	ucs2char_t* p = ucs2rchr(path, PATHCHAR);
@@ -115,6 +141,18 @@
 	return NULL;
 }
 
+/** 
+ * Adds the native path separator to a UCS-2 encoded path name.
+ *
+ * If the given @p path does not have a native path separator at the
+ * end, then one is added.  The @p path is modified in place, and is
+ * assumed to have enough space allocated to it to add the extra
+ * character.
+ *  
+ * @param path the path name to be modified.
+ * 
+ * @return a pointer to the last character in the new path.
+ */
 ucs2char_t* filepath_addslash(ucs2char_t* path)
 {
 	size_t length = ucs2len(path);
@@ -128,6 +166,17 @@
 	return (path + length);
 }
 
+/** 
+ * Removes the native path separator from a UCS-2 encoded path name.
+ * 
+ * If the given @p path has a native path separator at then end, then
+ * it is removed (or more accurately, it is replaced with the null
+ * terminator).
+ * 
+ * @param path the path name to be modified.
+ * 
+ * @return a pointer to the last character in the new path.
+ */
 ucs2char_t* filepath_removeslash(ucs2char_t* path)
 {
 	size_t length = ucs2len(path)-1;
@@ -335,6 +384,17 @@
 	return ret;
 }
 
+/** 
+ * Replaces all path separators with a backslash ('\') separator.
+ * 
+ * Replaces all path separators in the given path with Windows-style
+ * path separators (back-slashes).  On POSIX systems, this means
+ * converting forward slash ('/') path separators into backslashes. On
+ * Windows, this is a no-op.  The @p path is modified in place.
+ *
+ * @param path the path to be converted.
+ * @return
+ */
 int filepath_encode(ucs2char_t* path)
 {
 	while (*path) {
@@ -346,6 +406,17 @@
 	return 0;
 }
 
+/** 
+ * Replaces '\'-slashes in a path name with the native path separator.
+ * 
+ * Replaces all Windows-style path separators (back-slashes) in the
+ * given path with the native path separator.  On POSIX systems, the
+ * replacement character is a forward slash ('/').  On Windows, this
+ * is a no-op.  The @p path is modified in place.
+ *
+ * @param path the path to be converted.
+ * @return
+ */
 int filepath_decode(ucs2char_t* path)
 {
 	while (*path) {
@@ -356,3 +427,4 @@
 	}
 	return 0;
 }
+/**@}*/


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