NetSurf
string.h
Go to the documentation of this file.
1/*
2 * Copyright 2016 Vincent Sanders <vince@netsurf-browser.org>
3 *
4 * This file is part of NetSurf, http://www.netsurf-browser.org/
5 *
6 * NetSurf is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 2 of the License.
9 *
10 * NetSurf is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19/**
20 * \file
21 * \brief Interface to utility string handling.
22 */
23
24#ifndef _NETSURF_UTILS_STRING_H_
25#define _NETSURF_UTILS_STRING_H_
26
27#include <stdlib.h>
28#include <stdarg.h>
29
30#include "utils/errors.h"
31
32
33/**
34 * Replace consecutive whitespace with a single space.
35 *
36 * @todo determine if squash_whitespace utf-8 safe and that it needs to be
37 *
38 * \param s source string
39 * \return heap allocated result, or NULL on memory exhaustion
40 */
41char *squash_whitespace(const char * s);
42
43
44/**
45 * Converts NUL terminated UTF-8 encoded string s containing zero or more
46 * spaces (char 32) or TABs (char 9) to non-breaking spaces
47 * (0xC2 + 0xA0 in UTF-8 encoding).
48 *
49 * Caller needs to free() result. Returns NULL in case of error. No
50 * checking is done on validness of the UTF-8 input string.
51 */
52char *cnv_space2nbsp(const char *s);
53
54
55/**
56 * Create a human readable representation of a size in bytes.
57 *
58 * Does a simple conversion which assumes the user speaks English.
59 * The buffer returned is one of three static ones so may change each
60 * time this call is made. Don't store the buffer for later use.
61 * It's done this way for convenience and to fight possible memory
62 * leaks, it is not necessarily pretty.
63 *
64 * @param bytesize The size in bytes.
65 * @return A human readable string representing the size.
66 */
67char *human_friendly_bytesize(unsigned long long int bytesize);
68
69
70/**
71 * Generate a string from one or more component elements separated with
72 * a single value.
73 *
74 * This is similar in intent to the perl join function creating a
75 * single delimited string from an array of several.
76 *
77 * @note If a string is allocated it must be freed by the caller.
78 *
79 * @param[in,out] str pointer to string pointer if this is NULL enough
80 * storage will be allocated for the complete path.
81 * @param[in,out] size The size of the space available if \a str not
82 * NULL on input and if not NULL set to the total
83 * output length on output.
84 * @param[in] sep The character to separate the elements with.
85 * @param[in] nelm The number of elements up to a maximum of 16.
86 * @param[in] ap The elements of the path as string pointers.
87 * @return NSERROR_OK and the complete path is written to str or error
88 * code on failure.
89 */
90nserror vsnstrjoin(char **str, size_t *size, char sep, size_t nelm, va_list ap);
91
92
93/**
94 * Generate a string from one or more component elements separated with
95 * a single value.
96 *
97 * This is similar in intent to the Perl join function creating a
98 * single delimited string from an array of several.
99 *
100 * @note If a string is allocated it must be freed by the caller.
101 *
102 * @param[in,out] str pointer to string pointer if this is NULL enough
103 * storage will be allocated for the complete path.
104 * @param[in,out] size The size of the space available if \a str not
105 * NULL on input and if not NULL set to the total
106 * output length on output.
107 * @param[in] sep The character to separate the elements with.
108 * @param[in] nelm The number of elements up to a maximum of 16.
109 * @param[in] ... The elements of the path as string pointers.
110 * @return NSERROR_OK and the complete path is written to str or error
111 * code on failure.
112 */
113nserror snstrjoin(char **str, size_t *size, char sep, size_t nelm, ...);
114
115#endif
Error codes.
nserror
Enumeration of error codes.
Definition: errors.h:29
char * cnv_space2nbsp(const char *s)
Converts NUL terminated UTF-8 encoded string s containing zero or more spaces (char 32) or TABs (char...
Definition: utils.c:67
nserror vsnstrjoin(char **str, size_t *size, char sep, size_t nelm, va_list ap)
Generate a string from one or more component elements separated with a single value.
Definition: utils.c:107
char * squash_whitespace(const char *s)
Replace consecutive whitespace with a single space.
Definition: utils.c:38
char * human_friendly_bytesize(unsigned long long int bytesize)
Create a human readable representation of a size in bytes.
Definition: utils.c:209
nserror snstrjoin(char **str, size_t *size, char sep, size_t nelm,...)
Generate a string from one or more component elements separated with a single value.
Definition: utils.c:179