/**
 * CGI related string functions
 *
 * @file	platon/str/strcgi.h
 * @author	Ondrej Jombik <nepto@platon.sk>
 * @author	Rafael Steil <rafael@insanecorp.com>
 * @version	\$Platon: libcfg+/src/platon/str/strcgi.h,v 1.3 2003/04/22 14:22:53 nepto Exp $
 * @date	2001-2004
 *
 * This part is mostly based on the libcgi 0.7.2 library by Rafael Steil
 * and PHP: Hypertext Preprocessor source codes (http://www.php.net/).
 */

#ifndef _PLATON_STR_STRCGI_H
#define _PLATON_STR_STRCGI_H

#ifndef PLATON_FUNC
# define PLATON_FUNC(_name) _name
#endif
#ifndef PLATON_FUNC_STR
# define PLATON_FUNC_STR(_name) #_name
#endif

#ifdef __cplusplus
extern "C" {
#endif

	/**
	 * URL-encodes string
	 *
	 * @param		str		string to encode
	 * @return		allocated encoded string
	 *				or NULL on memory allocation error
	 *
	 * Function transform special characters into their appropriate hexadecimal
	 * form (like "\%E1"). It is encoded the same way that the posted data from
	 * a WWW form is encoded, that is the same way as in the media type called
	 * application/x-www-form-urlencoded. This differs from the RFC1738
	 * encoding (see rawurlencode() function) in that for historical reasons,
	 * spaces are encoded as plus (+) signs.
	 *
	 * Original code was from PHP: Hypertext preprocessor sources. See
	 * http://www.php.net/ for more information.
	 */
	char *PLATON_FUNC(urlencode)(const char *str);

	/**
	 * Decodes URL-encoded string
	 *
	 * @param		str		string to decode
	 * @return		allocated decoded string
	 *				or NULL on memory allocation error
	 *
	 * Function searches for special character sequences (like "\%E1") in str
	 * variable and converts them to the their apropriate ASCII character
	 * correspondent. For more information about how data are encoded, see
	 * urlencode() function.
	 */
	char *PLATON_FUNC(urldecode)(const char *str);

	/**
	 * URL-encodes string according to RFC1738
	 *
	 * @param		str		string to encode
	 * @return		allocated encoded string
	 *				or NULL on memory allocation error
	 *
	 * Function transform special characters into their appropriate hexadecimal
	 * form (like "\%E1"). This is the encoding described in RFC1738 for
	 * protecting literal characters from being interpreted as special URL
	 * delimiters, and for protecting URL's from being mangled by transmission
	 * media with character conversions (like some e-mail systems). This
	 * differs from the urlencode() function, where spaces are not encoded as
	 * plus (+) signs.
	 *
	 * Original code was from PHP: Hypertext preprocessor sources. See
	 * http://www.php.net/ for more information.
	 */
	char *PLATON_FUNC(rawurlencode)(const char *str);

	/**
	 * Decodes URL-encoded string according to RFC1738
	 *
	 * @param		str		string to decode
	 * @return		allocated decoded string
	 *				or NULL on memory allocation error
	 *
	 * This function searches for special character sequences (like "\%E1") in
	 * str variable and converts them to the their apropriate ASCII character
	 * correspondent. For more information about how data are encoded, see
	 * rawurlencode() function.
	 */
	char *PLATON_FUNC(rawurldecode)(const char *str);

	/**
	 * Adds slashes to a string when necessary
	 *
	 * @param		__s		string where to add slashes
	 * @return		allocated string with slashes added
	 *				or NULL on memory allocation error
	 */
#define addslashes(__s) (addnslashes(__s, strlen(__s)))

	/**
	 * Strips slashes from a string
	 *
	 * @param		__s		string where to strip slashes
	 * @return		allocated string with slashes striped
	 *				or NULL on memory allocation error
	 */
#define stripslashes(__s) (stripnslashes(__s, strlen(__s)))

	/**
	 * Adds slashes to a string when necessary
	 *
	 * @param		s		string where to add slashes
	 * @param		n		how many characters to consider
	 * @return		allocated string with slashes added
	 *				or NULL on memory allocation error
	 */
	char *PLATON_FUNC(addnslashes)(const char *s, int n);

	/**
	 * Strips slashes from a string
	 *
	 * @param		s		string where to strip slashes
	 * @param		n		how many characters to consider
	 * @return		allocated string with slashes striped
	 *				or NULL on memory allocation error
	 */
	char *PLATON_FUNC(stripnslashes)(const char *s, int n);

#ifdef __cplusplus
}
#endif

#endif /* #ifndef _PLATON_STR_STRPLUS_H */