grab_fd and grab_file: add a size arg, use everywhere.
[ccan] / ccan / string / string.h
1 #ifndef CCAN_STRING_H
2 #define CCAN_STRING_H
3 #include <string.h>
4 #include <stdbool.h>
5
6 /**
7  * streq - Are two strings equal?
8  * @a: first string
9  * @b: first string
10  *
11  * This macro is arguably more readable than "!strcmp(a, b)".
12  *
13  * Example:
14  *      if (streq(str, ""))
15  *              printf("String is empty!\n");
16  */
17 #define streq(a,b) (strcmp((a),(b)) == 0)
18
19 /**
20  * strstarts - Does this string start with this prefix?
21  * @str: string to test
22  * @prefix: prefix to look for at start of str
23  *
24  * Example:
25  *      if (strstarts(str, "foo"))
26  *              printf("String %s begins with 'foo'!\n", str);
27  */
28 #define strstarts(str,prefix) (strncmp((str),(prefix),strlen(prefix)) == 0)
29
30 /**
31  * strends - Does this string end with this postfix?
32  * @str: string to test
33  * @postfix: postfix to look for at end of str
34  *
35  * Example:
36  *      if (strends(str, "foo"))
37  *              printf("String %s end with 'foo'!\n", str);
38  */
39 static inline bool strends(const char *str, const char *postfix)
40 {
41         if (strlen(str) < strlen(postfix))
42                 return false;
43
44         return streq(str + strlen(str) - strlen(postfix), postfix);
45 }
46
47 /**
48  * strsplit - Split string into an array of substrings
49  * @ctx: the context to tallocate from (often NULL)
50  * @string: the string to split
51  * @delims: delimiters where lines should be split.
52  * @nump: optional pointer to place resulting number of lines
53  *
54  * This function splits a single string into multiple strings.  The
55  * original string is untouched: an array is allocated (using talloc)
56  * pointing to copies of each substring.  Multiple delimiters result
57  * in empty substrings.  By definition, no delimiters will appear in
58  * the substrings.
59  *
60  * The final char * in the array will be NULL, so you can use this or
61  * @nump to find the array length.
62  *
63  * Example:
64  *      unsigned int count_long_lines(const char *text)
65  *      {
66  *              char **lines;
67  *              unsigned int i, long_lines = 0;
68  *
69  *              // Can only fail on out-of-memory.
70  *              lines = strsplit(NULL, string, "\n", NULL);
71  *              for (i = 0; lines[i] != NULL; i++)
72  *                      if (strlen(lines[i]) > 80)
73  *                              long_lines++;
74  *              talloc_free(lines);
75  *              return long_lines;
76  *      }
77  */
78 char **strsplit(const void *ctx, const char *string, const char *delims,
79                  unsigned int *nump);
80
81 /**
82  * strjoin - Join an array of substrings into one long string
83  * @ctx: the context to tallocate from (often NULL)
84  * @strings: the NULL-terminated array of strings to join
85  * @delim: the delimiter to insert between the strings
86  *
87  * This function joins an array of strings into a single string.  The
88  * return value is allocated using talloc.  Each string in @strings is
89  * followed by a copy of @delim.
90  *
91  * Example:
92  *      // Append the string "--EOL" to each line.
93  *      char *append_to_all_lines(const char *string)
94  *      {
95  *              char **lines, *ret;
96  *              unsigned int i, num, newnum;
97  *
98  *              lines = strsplit(NULL, string, "\n", NULL);
99  *              ret = strjoin(NULL, lines, "-- EOL\n");
100  *              talloc_free(lines);
101  *              return ret;
102  *      }
103  */
104 char *strjoin(const void *ctx, char *strings[], const char *delim);
105
106 /**
107  * grab_fd - read all of a file descriptor into memory
108  * @ctx: the context to tallocate from (often NULL)
109  * @fd: the file descriptor to read from
110  * @size: the (optional) size of the file
111  *
112  * This function reads from the given file descriptor until no more
113  * input is available.  The content is talloced off @ctx, and the size
114  * of the file places in @size if it's non-NULL.  For convenience, the
115  * byte after the end of the content will always be NUL.
116  *
117  * Example:
118  *      // Return all of standard input, as lines.
119  *      char **read_as_lines(void)
120  *      {
121  *              char **lines, *all;
122  *
123  *              all = grab_fd(NULL, 0, NULL);
124  *              if (!all)
125  *                      return NULL;
126  *              lines = strsplit(NULL, all, "\n", NULL);
127  *              talloc_free(all);
128  *              return lines;
129  *      }
130  */
131 void *grab_fd(const void *ctx, int fd, size_t *size);
132
133 /**
134  * grab_file - read all of a file (or stdin) into memory
135  * @ctx: the context to tallocate from (often NULL)
136  * @filename: the file to read (NULL for stdin)
137  * @size: the (optional) size of the file
138  *
139  * This function reads from the given file until no more input is
140  * available.  The content is talloced off @ctx, and the size of the
141  * file places in @size if it's non-NULL.  For convenience, the byte
142  * after the end of the content will always be NUL.
143  *
144  * Example:
145  *      // Return all of a given file, as lines.
146  *      char **read_as_lines(const char *filename)
147  *      {
148  *              char **lines, *all;
149  *
150  *              all = grab_file(NULL, filename, NULL);
151  *              if (!all)
152  *                      return NULL;
153  *              lines = strsplit(NULL, all, "\n", NULL);
154  *              talloc_free(all);
155  *              return lines;
156  *      }
157  */
158 void *grab_file(const void *ctx, const char *filename, size_t *size);
159 #endif /* CCAN_STRING_H */