[kdbus] sync with kdbus (kdbus.h - commit: 5ae1ecac44cb)

[platform/upstream/glib.git] / glib / gurifuncs.c

diff --git a/glib/gurifuncs.c b/glib/gurifuncs.c
index 731dc6d..44cf82a 100644 (file)
--- a/glib/gurifuncs.c
+++ b/glib/gurifuncs.c
@@ -13,29 +13,35 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  *
  * Author: Alexander Larsson <alexl@redhat.com>
  */
 
-#include <config.h>
+#include "config.h"
+
 #include "gurifuncs.h"
-#include "string.h"
 
-#include "galias.h"
+#include <glib/gstrfuncs.h>
+#include <glib/gmessages.h>
+#include <glib/gstring.h>
+#include <glib/gmem.h>
+
+#include <string.h>
+
+#include "config.h"
 
 /**
  * SECTION:gurifuncs
- * @short_description: URI Functions
- * 
- * Functions for manipulating Universal Resource Identifiers (URIs) as 
- * defined by RFC 3986. It is highly recommended that you have read and
- * understand RFC 3986 for understanding this API. A copy of RFC 3986 
- * can be found at <ulink url="http://www.ietf.org/rfc/rfc3986.txt"/>.
+ * @title: URI Functions
+ * @short_description: manipulating URIs
  *
- **/
+ * Functions for manipulating Universal Resource Identifiers (URIs) as
+ * defined by
+ * [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt).
+ * It is highly recommended that you have read and
+ * understand RFC 3986 for understanding this API.
+ */
 
 static int
 unescape_character (const char *scanner)
@@ -56,14 +62,22 @@ unescape_character (const char *scanner)
 
 /**
  * g_uri_unescape_segment:
- * @escaped_string: a string.
- * @escaped_string_end: a string.
- * @illegal_characters: a string of illegal characters not to be allowed.
+ * @escaped_string: (allow-none): A string, may be %NULL
+ * @escaped_string_end: (allow-none): Pointer to end of @escaped_string, may be %NULL
+ * @illegal_characters: (allow-none): An optional string of illegal characters not to be allowed, may be %NULL
  * 
  * Unescapes a segment of an escaped string.
- * 
+ *
+ * If any of the characters in @illegal_characters or the character zero appears
+ * as an escaped character in @escaped_string then that is an error and %NULL
+ * will be returned. This is useful it you want to avoid for instance having a
+ * slash being expanded in an escaped path element, which might confuse pathname
+ * handling.
+ *
  * Returns: an unescaped version of @escaped_string or %NULL on error.
- * The returned string should be freed when no longer needed.
+ * The returned string should be freed when no longer needed.  As a
+ * special case if %NULL is given for @escaped_string, this function
+ * will return %NULL.
  *
  * Since: 2.16
  **/
@@ -124,10 +138,17 @@ g_uri_unescape_segment (const char *escaped_string,
 /**
  * g_uri_unescape_string:
  * @escaped_string: an escaped string to be unescaped.
- * @illegal_characters: a string of illegal characters not to be allowed.
+ * @illegal_characters: (allow-none): a string of illegal characters not to be
+ *      allowed, or %NULL.
  * 
  * Unescapes a whole escaped string.
  * 
+ * If any of the characters in @illegal_characters or the character zero appears
+ * as an escaped character in @escaped_string then that is an error and %NULL
+ * will be returned. This is useful it you want to avoid for instance having a
+ * slash being expanded in an escaped path element, which might confuse pathname
+ * handling.
+ *
  * Returns: an unescaped version of @escaped_string. The returned string 
  * should be freed when no longer needed.
  *
@@ -141,11 +162,13 @@ g_uri_unescape_string (const char *escaped_string,
 }
 
 /**
- * g_uri_get_scheme:
+ * g_uri_parse_scheme:
  * @uri: a valid URI.
  * 
- * Gets the scheme portion of a URI. RFC 3986 decodes the scheme as:
+ * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
+ * |[
  * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] 
+ * ]|
  * Common schemes include "file", "http", "svn+ssh", etc.
  * 
  * Returns: The "Scheme" component of the URI, or %NULL on error. 
@@ -154,7 +177,7 @@ g_uri_unescape_string (const char *escaped_string,
  * Since: 2.16
  **/
 char *
-g_uri_get_scheme (const char  *uri)
+g_uri_parse_scheme (const char  *uri)
 {
   const char *p;
   char c;
@@ -194,10 +217,18 @@ g_uri_get_scheme (const char  *uri)
 /**
  * g_uri_escape_string:
  * @unescaped: the unescaped input string.
- * @reserved_chars_allowed: a string of reserve characters allowed to be used.
- * @allow_utf8: a #gboolean. Set to %TRUE if string can include UTF8 characters.
+ * @reserved_chars_allowed: (allow-none): a string of reserved characters that
+ *      are allowed to be used, or %NULL.
+ * @allow_utf8: %TRUE if the result can include UTF-8 characters.
  * 
  * Escapes a string for use in a URI.
+ *
+ * Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical
+ * characters plus dash, dot, underscore and tilde) are escaped.
+ * But if you specify characters in @reserved_chars_allowed they are not
+ * escaped. This is useful for the "reserved" characters in the URI
+ * specification, since those are allowed unescaped in some portions of
+ * a URI. 
  * 
  * Returns: an escaped version of @unescaped. The returned string should be 
  * freed when no longer needed.
@@ -219,6 +250,3 @@ g_uri_escape_string (const char *unescaped,
   
   return g_string_free (s, FALSE);
 }
-
-#define __G_URI_FUNCS_C__
-#include "galiasdef.c"