diff options
author | Vincent Sanders <vince@kyllikki.org> | 2014-05-11 21:31:14 +0100 |
---|---|---|
committer | Vincent Sanders <vince@kyllikki.org> | 2014-05-11 21:31:14 +0100 |
commit | 39b0393d31a86a8fcfa770ad040207ace95bde0d (patch) | |
tree | d59b25fbd066984d0feaf57a4763134d0e9a2884 /utils | |
parent | 06a3f84e5032b93052f1eb95946d5f51aa9368f2 (diff) | |
download | netsurf-39b0393d31a86a8fcfa770ad040207ace95bde0d.tar.gz netsurf-39b0393d31a86a8fcfa770ad040207ace95bde0d.tar.bz2 |
cleanup utils header, remove cruft and add documentation
Diffstat (limited to 'utils')
-rw-r--r-- | utils/nsurl.c | 11 | ||||
-rw-r--r-- | utils/utils.c | 104 | ||||
-rw-r--r-- | utils/utils.h | 114 | ||||
-rw-r--r-- | utils/utsname.h | 21 |
4 files changed, 121 insertions, 129 deletions
diff --git a/utils/nsurl.c b/utils/nsurl.c index c99b0d34a..5c0a48511 100644 --- a/utils/nsurl.c +++ b/utils/nsurl.c @@ -36,6 +36,17 @@ /* Define to enable NSURL debugging */ #undef NSURL_DEBUG +/** + * Return a hex digit for the given numerical value. + * + * \param digit the value to get the hex digit for. + * \return character in range 0-9A-F + */ +inline static char digit2uppercase_hex(unsigned char digit) { + assert(digit < 16); + return "0123456789ABCDEF"[digit]; +} + static bool nsurl__is_unreserved(unsigned char c) { /* From RFC3986 section 2.3 (unreserved characters) diff --git a/utils/utils.c b/utils/utils.c index bb30f921e..c036ff2f7 100644 --- a/utils/utils.c +++ b/utils/utils.c @@ -37,32 +37,7 @@ #include "utils/utf8.h" #include "utils/utils.h" -char * strip(char * const s) -{ - size_t i; - for (i = strlen(s); - i != 0 && (s[i - 1] == ' ' || s[i - 1] == '\n' || - s[i - 1] == '\r' || s[i - 1] == '\t'); - i--) - ; - s[i] = 0; - return s + strspn(s, " \t\r\n"); -} - -int whitespace(const char * str) -{ - unsigned int i; - for (i = 0; i < strlen(str); i++) - if (!isspace(str[i])) - return 0; - return 1; -} - -/** - * returns a string without its underscores - * \param replacespace true to insert a space where there was an underscore - */ - +/* exported interface documented in utils/utils.h */ char *remove_underscores(const char *s, bool replacespace) { size_t i, ii, len; @@ -81,15 +56,8 @@ char *remove_underscores(const char *s, bool replacespace) return ret; } -/** - * Replace consecutive whitespace with a single space. - * - * @todo determine if squash_whitespace utf-8 safe and that it needs to be - * - * \param s source string - * \return heap allocated result, or NULL on memory exhaustion - */ +/* exported interface documented in utils/utils.h */ char *squash_whitespace(const char *s) { char *c; @@ -116,14 +84,7 @@ char *squash_whitespace(const char *s) } -/** - * Converts NUL terminated UTF-8 encoded string s containing zero or more - * spaces (char 32) or TABs (char 9) to non-breaking spaces - * (0xC2 + 0xA0 in UTF-8 encoding). - * - * Caller needs to free() result. Returns NULL in case of error. No - * checking is done on validness of the UTF-8 input string. - */ +/* exported interface documented in utils/utils.h */ char *cnv_space2nbsp(const char *s) { const char *srcP; @@ -146,10 +107,8 @@ char *cnv_space2nbsp(const char *s) return d; } -/** - * Check if a directory exists. - */ +/* exported interface documented in utils/utils.h */ bool is_dir(const char *path) { struct stat s; @@ -160,6 +119,7 @@ bool is_dir(const char *path) return S_ISDIR(s.st_mode) ? true : false; } + /* exported interface documented in utils/utils.h */ nserror vsnstrjoin(char **str, size_t *size, char sep, size_t nelm, va_list ap) { @@ -240,12 +200,8 @@ nserror snstrjoin(char **str, size_t *size, char sep, size_t nelm, ...) return ret; } -/** - * Compile a regular expression, handling errors. - * - * Parameters as for regcomp(), see man regex. - */ +/* exported interface documented in utils/utils.h */ void regcomp_wrapper(regex_t *preg, const char *regex, int cflags) { int r; @@ -258,24 +214,20 @@ void regcomp_wrapper(regex_t *preg, const char *regex, int cflags) } } -/** We can have a fairly good estimate of how long the buffer needs to - * be. The unsigned long can store a value representing a maximum size - * of around 4 GB. Therefore the greatest space required is to - * represent 1023MB. Currently that would be represented as "1023MB" so 12 - * including a null terminator. - * Ideally we would be able to know this value for sure, in the mean - * time the following should suffice. - **/ - -#define BYTESIZE_BUFFER_SIZE 20 - /** - * Does a simple conversion which assumes the user speaks English. The buffer - * returned is one of three static ones so may change each time this call is - * made. Don't store the buffer for later use. It's done this way for - * convenience and to fight possible memory leaks, it is not necessarily pretty. - **/ + * The size of buffers within human_friendly_bytesize. + * + * We can have a fairly good estimate of how long the buffer needs to + * be. The unsigned long can store a value representing a maximum + * size of around 4 GB. Therefore the greatest space required is to + * represent 1023MB. Currently that would be represented as "1023MB" + * so 12 including a null terminator. Ideally we would be able to + * know this value for sure, in the mean time the following should + * suffice. + */ +#define BYTESIZE_BUFFER_SIZE 20 +/* exported interface documented in utils/utils.h */ char *human_friendly_bytesize(unsigned long bsize) { static char buffer1[BYTESIZE_BUFFER_SIZE]; static char buffer2[BYTESIZE_BUFFER_SIZE]; @@ -308,17 +260,13 @@ char *human_friendly_bytesize(unsigned long bsize) { unit = gigabytes; } - sprintf(curbuffer, "%3.2f%s", bytesize, messages_get(units[unit])); + snprintf(curbuffer, BYTESIZE_BUFFER_SIZE, "%3.2f%s", bytesize, messages_get(units[unit])); return curbuffer; } -/** - * Create an RFC 1123 compliant date string from a Unix timestamp - * - * \param t The timestamp to consider - * \return Pointer to buffer containing string - invalidated by next call. - */ + +/* exported interface documented in utils/utils.h */ const char *rfc1123_date(time_t t) { static char ret[30]; @@ -336,14 +284,8 @@ const char *rfc1123_date(time_t t) return ret; } -/** - * Returns a number of centiseconds, that increases in real time, for the - * purposes of measuring how long something takes in wall-clock terms. It uses - * gettimeofday() for this. Should the call to gettimeofday() fail, it returns - * zero. - * - * \return number of centiseconds that increases monotonically - */ + +/* exported interface documented in utils/utils.h */ unsigned int wallclock(void) { struct timeval tv; diff --git a/utils/utils.h b/utils/utils.h index 33cb0e99a..0922afb7e 100644 --- a/utils/utils.h +++ b/utils/utils.h @@ -17,6 +17,12 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * \file utils/utils.h + * \brief Interface to a number of general purpose functionality. + * \todo Many of these functions and macros should have their own headers. + */ + #ifndef _NETSURF_UTILS_UTILS_H_ #define _NETSURF_UTILS_UTILS_H_ @@ -89,27 +95,11 @@ struct dirent; /** * Calculate length of constant C string. * - * \param x a constant C string. - * \return the length of C string without its terminating NUL accounted. + * \param x a constant C string. + * \return The length of C string without its terminator. */ #define SLEN(x) (sizeof((x)) - 1) -enum query_response { - QUERY_CONTINUE, - QUERY_YES, - QUERY_NO, - QUERY_ESCAPE -}; - -typedef int query_id; - -#define QUERY_INVALID ((query_id)-1) - -typedef struct -{ - void (*confirm)(query_id id, enum query_response res, void *pw); - void (*cancel)(query_id, enum query_response res, void *pw); -} query_callback; #ifndef timeradd #define timeradd(a, aa, result) \ @@ -137,15 +127,78 @@ typedef struct -char * strip(char * const s); -int whitespace(const char * str); +/** + * Replace consecutive whitespace with a single space. + * + * @todo determine if squash_whitespace utf-8 safe and that it needs to be + * + * \param s source string + * \return heap allocated result, or NULL on memory exhaustion + */ char * squash_whitespace(const char * s); + +/** + * returns a string without its underscores + * \param replacespace true to insert a space where there was an underscore + */ char *remove_underscores(const char *s, bool replacespace); + +/** + * Converts NUL terminated UTF-8 encoded string s containing zero or more + * spaces (char 32) or TABs (char 9) to non-breaking spaces + * (0xC2 + 0xA0 in UTF-8 encoding). + * + * Caller needs to free() result. Returns NULL in case of error. No + * checking is done on validness of the UTF-8 input string. + */ char *cnv_space2nbsp(const char *s); + +/** + * Check if a directory exists. + */ bool is_dir(const char *path); + +/** + * Compile a regular expression, handling errors. + * + * Parameters as for regcomp(), see man regex. + */ void regcomp_wrapper(regex_t *preg, const char *regex, int cflags); + +/** + * Create a human redable representation of a size in bytes. + * + * Does a simple conversion which assumes the user speaks English. + * The buffer returned is one of three static ones so may change each + * time this call is made. Don't store the buffer for later use. + * It's done this way for convenience and to fight possible memory + * leaks, it is not necessarily pretty. + * + * @todo This implementation is strange doe sit need + * reconsidering? + * + * @param bsize The size in bytes. + * @return A human readable string representing the size. + */ char *human_friendly_bytesize(unsigned long bytesize); + +/** + * Create an RFC 1123 compliant date string from a Unix timestamp + * + * \param t The timestamp to consider + * \return Pointer to buffer containing string - invalidated by next call. + */ const char *rfc1123_date(time_t t); + +/** + * Returns a number of centiseconds, that increases in real time, for the + * purposes of measuring how long something takes in wall-clock terms. + * + * The implementation uses gettimeofday() for this. Should the call + * to gettimeofday() fail, it returns zero. + * + * \return number of centiseconds that increases monotonically + */ unsigned int wallclock(void); /** @@ -203,27 +256,6 @@ nserror snstrjoin(char **str, size_t *size, char sep, size_t nelm, ...); */ int dir_sort_alpha(const struct dirent **d1, const struct dirent **d2); -/** - * Return a hex digit for the given numerical value. - * - * \return character in range 0-9a-f - */ -inline static char digit2lowcase_hex(unsigned char digit) { - assert(digit < 16); - return "0123456789abcdef"[digit]; -} - -/** - * Return a hex digit for the given numerical value. - * - * \return character in range 0-9A-F - */ -inline static char digit2uppercase_hex(unsigned char digit) { - assert(digit < 16); - return "0123456789ABCDEF"[digit]; -} - - /* Platform specific functions */ void die(const char * const error); void warn_user(const char *warning, const char *detail); diff --git a/utils/utsname.h b/utils/utsname.h index cef183670..b4c0a79d9 100644 --- a/utils/utsname.h +++ b/utils/utsname.h @@ -27,16 +27,23 @@ #ifdef HAVE_UTSNAME #include <sys/utsname.h> #else -/* from posix spec */ +/** system information filled in by uname derived from posix spec. */ struct utsname { - char sysname[65]; /* Operating system name (e.g., "Linux") */ - char nodename[65]; /* Name within "some implementation-defined - network" */ - char release[65]; /* OS release (e.g., "2.6.28") */ - char version[65]; /* OS version */ - char machine[65]; /* Hardware identifier */ + char sysname[65]; /**< Operating system name (e.g., "Linux") */ + char nodename[65]; /**< Name within "some implementation-defined + * network" + */ + char release[65]; /**< OS release (e.g., "2.6.28") */ + char version[65]; /**< OS version */ + char machine[65]; /**< Hardware identifier */ }; +/** + * Get the system information. + * + * @param buf the buffer to fill with teh information. + * @return 0 on sucess or -1 and errno set on faliure. + */ int uname(struct utsname *buf); #endif |