aheinecke@404: /* Copyright (C) 2014 by Bundesamt für Sicherheit in der Informationstechnik
aheinecke@404:  * Software engineering by Intevation GmbH
aheinecke@404:  *
aheinecke@404:  * This file is Free Software under the GNU GPL (v>=2)
aheinecke@404:  * and comes with ABSOLUTELY NO WARRANTY!
aheinecke@404:  * See LICENSE.txt for details.
aheinecke@404:  */
aheinecke@60: #ifndef STRHELP_H
aheinecke@60: #define STRHELP_H
wilde@118: 
aheinecke@184: #ifdef __cplusplus
aheinecke@184: extern "C" {
aheinecke@184: #endif
aheinecke@184: 
wilde@131: #include <stdbool.h>
aheinecke@251: #include <stddef.h>
wilde@131: 
wilde@118: /**
wilde@118:  * @file  strhelp.h
wilde@118:  * @brief Helper functions for c strings and memory management
wilde@118:  * @details strhelp contains terminating memory allocation functions and
wilde@118:  * some conveniance functions to work with c strings or arrays of c
wilde@118:  * strings.
aheinecke@59:  */
wilde@118: 
aheinecke@59: void *xmalloc( size_t n );
aheinecke@59: void *xrealloc( void *a, size_t n );
aheinecke@59: void *xcalloc( size_t n, size_t m );
aheinecke@60: char *xstrndup( const char *string, const size_t len );
aheinecke@251: void xfree ( void *p );
aheinecke@59: 
aheinecke@59: /**
wilde@319:  * @brief Terminating variant of asprintf
wilde@319:  *
wilde@319:  * This function behaves exactly like asprintf(3) but will terminate
wilde@319:  * when an error occures (usally that means that memoy allocation
wilde@319:  * failed).
wilde@319:  */
wilde@319: int xasprintf (char **strp, const char *fmt, ...);
wilde@319: 
wilde@319: /**
wilde@118:  * @brief Returns the length of the given %NULL-terminated
wilde@118:  * string array str_array.
wilde@120:  * @param[in] str_array a %NULL-terminated array of strings
wilde@118:  * @returns length of str_array.
aheinecke@59:  */
aheinecke@59: unsigned int strv_length (char **str_array);
aheinecke@59: 
wilde@118: /**
wilde@118:  * @brief append a string to a NULL terminated array of strings.
aheinecke@59:  *
andre@1304:  * @param[in,out] pArray pointer to the NULL terminated list of string pointers.
aheinecke@59:  * @param[in] string pointer to the string to append to the list.
aheinecke@60:  * @param[in] len length of the string to append to the list
wilde@118:  */
wilde@116: void strv_append (char ***pArray, const char *string, const size_t len);
aheinecke@59: 
wilde@118: /**
wilde@118:  * @brief append a string to another string.
aheinecke@59:  *
andre@1304:  * @param[in,out] pDst pointer to the string to be extended.
andre@1304:  * @param[in,out] dst_len length of the dst string. Will be modified.
aheinecke@59:  * @param[in] appendage pointer to the string to append.
aheinecke@60:  * @param[in] len length of the string to append.
wilde@118:  */
wilde@116: void str_append_str (char **pDst, size_t *dst_len, const char *appendage,
aheinecke@91:                     const size_t len);
aheinecke@59: 
wilde@118: /**
wilde@118:  * @brief Frees the given %NULL-terminated string array.
andre@1304:  * @param[in,out] str_array a %NULL-terminated array of strings
wilde@118:  */
wilde@116: void strv_free (char **str_array);
wilde@131: 
wilde@131: /**
wilde@131:  * @brief Checks whether two strings exactly match
wilde@131:  * @param[in] s1 the first string
wilde@131:  * @param[in] s2 the second string
wilde@131:  * @returns true if s1 and s2 are equal
wilde@131:  */
wilde@131: bool str_equal (char *s1, char *s2);
wilde@131: 
wilde@131: /**
wilde@131:  * @brief Checks whether s2 exactly matches the beginning of s1.
wilde@131:  * @param[in] s1 the string who's beginning is searched
wilde@131:  * @param[in] s2 the string which is searched for
wilde@131:  * @returns true if s1 starts with s2, false otherwise
wilde@131:  */
wilde@131: bool str_starts_with (char *s1, char *s2);
wilde@131: 
wilde@133: /**
wilde@133:  * @brief Trims all white space from the start and end of string.
wilde@133:  * @details the start of the string is trimmed by setting *s to the
wilde@133:  * first non white space character.  The end is trimmed by setting the
wilde@133:  * first character after the last non white space character to \0.
andre@1304:  * @param[in,out] s ponter to the string to strip
wilde@133:  */
wilde@133: bool str_trim (char **s);
wilde@133: 
aheinecke@160: /** @brief decode base64 encoded data
aheinecke@160:  *
aheinecke@160:  * The memory allocated for dest needs to be free'd by the
aheinecke@160:  * caller.
aheinecke@160:  *
aheinecke@239:  * _Input warning:_
aheinecke@239:  * If the input contains invalid base64 characters an error
aheinecke@239:  * is returned.
aheinecke@239:  *
aheinecke@239:  * If the input is invalid base64 but consists of valid
aheinecke@239:  * base64 characters _no error_ is returned and dst contains
aheinecke@239:  * the valid input up to the error.
aheinecke@239:  *
aheinecke@160:  * @param [out] dst Pointer to the destination. Needs to be NULL
aheinecke@160:  * @param [out] dst_size Size allocated for the destination.
aheinecke@160:  * @param [in] src Pointer to the base64 encoded data.
aheinecke@160:  * @param [in] src_size Size of the encoded data.
aheinecke@160:  *
aheinecke@160:  * @returns 0 on success a polarssl error or -1 otherwise
aheinecke@160:  */
aheinecke@160: int str_base64_decode(char **dst, size_t *dst_size, char *src,
aheinecke@160:                       size_t src_size);
aheinecke@251: 
aheinecke@251: #ifdef WIN32
aheinecke@251: 
aheinecke@251: /** @brief convert a utf8 string to utf16 wchar
aheinecke@251:  *
aheinecke@251:  * @param[in] string utf8 string. Must be at least len characters long.
aheinecke@251:  * @param[in] len number of characters to be converted.
aheinecke@251:  *
aheinecke@251:  * @returns pointer to a newly allocated wchar array. NULL on error.
aheinecke@251:  *
aheinecke@251:  **/
aheinecke@251: wchar_t *utf8_to_wchar (const char *string, size_t len);
aheinecke@251: 
andre@1158: /** @brief convert a local 8 bit (acp) string to utf16 wchar
andre@1158:  *
andre@1158:  * @param[in] string acp string. Must be at least len characters long.
andre@1158:  * @param[in] len number of characters to be converted.
andre@1158:  *
andre@1158:  * @returns pointer to a newly allocated wchar array. NULL on error.
andre@1158:  *
andre@1158:  **/
andre@1158: wchar_t *acp_to_wchar (const char *string, size_t len);
andre@1158: 
aheinecke@251: /** @brief convert a utf16 string to utf8
aheinecke@251:  *
aheinecke@251:  * @param[in] string utf16 string. Must be at least len characters long.
aheinecke@251:  * @param[in] len number of characters to be converted.
aheinecke@251:  *
aheinecke@251:  * @returns pointer to a newly allocated char array. NULL on error.
aheinecke@251:  *
aheinecke@251:  **/
aheinecke@251: char *wchar_to_utf8 (const wchar_t *string, size_t len);
aheinecke@251: #endif
aheinecke@251: 
aheinecke@184: #ifdef __cplusplus
aheinecke@184: }
aheinecke@184: #endif
aheinecke@160: 
aheinecke@60: #endif