blob: 4715d3e51f873e7b6618a80ebc79f2d2b4ebaab7 [file] [log] [blame]
Jeff Kingdbbcd442020-07-28 16:23:39 -04001#ifndef STRVEC_H
2#define STRVEC_H
Jeff Kingc1189ca2011-09-13 17:57:57 -04003
Heba Waly971b1f22019-11-17 21:04:52 +00004/**
Jeff Kingd70a9eb2020-07-28 20:37:20 -04005 * The strvec API allows one to dynamically build and store
6 * NULL-terminated arrays of strings. A strvec maintains the invariant that the
Linus Arverf10b0982024-01-12 07:06:35 +00007 * `v` member always points to a non-NULL array, and that the array is
8 * always NULL-terminated at the element pointed to by `v[nr]`. This
Heba Waly971b1f22019-11-17 21:04:52 +00009 * makes the result suitable for passing to functions expecting to receive
10 * argv from main().
11 *
12 * The string-list API (documented in string-list.h) is similar, but cannot be
13 * used for these purposes; instead of storing a straight string pointer,
14 * it contains an item structure with a `util` field that is not compatible
15 * with the traditional argv interface.
16 *
Jeff King873cd282020-07-28 16:23:25 -040017 * Each `strvec` manages its own memory. Any strings pushed into the
18 * array are duplicated, and all memory is freed by strvec_clear().
Heba Waly971b1f22019-11-17 21:04:52 +000019 */
20
Jeff King873cd282020-07-28 16:23:25 -040021extern const char *empty_strvec[];
Jeff Kingc1189ca2011-09-13 17:57:57 -040022
Heba Waly971b1f22019-11-17 21:04:52 +000023/**
24 * A single array. This should be initialized by assignment from
Linus Arverf10b0982024-01-12 07:06:35 +000025 * `STRVEC_INIT`, or by calling `strvec_init`. The `v`
Jeff Kingd70a9eb2020-07-28 20:37:20 -040026 * member contains the actual array; the `nr` member contains the
Heba Waly971b1f22019-11-17 21:04:52 +000027 * number of elements in the array, not including the terminating
28 * NULL.
29 */
Jeff King873cd282020-07-28 16:23:25 -040030struct strvec {
Jeff Kingd70a9eb2020-07-28 20:37:20 -040031 const char **v;
Jeff King8d133a42021-09-11 11:01:16 -040032 size_t nr;
33 size_t alloc;
Jeff Kingc1189ca2011-09-13 17:57:57 -040034};
35
Ævar Arnfjörð Bjarmasonf69a6e42021-09-27 14:54:27 +020036#define STRVEC_INIT { \
37 .v = empty_strvec, \
38}
Jeff Kingc1189ca2011-09-13 17:57:57 -040039
Heba Waly971b1f22019-11-17 21:04:52 +000040/**
41 * Initialize an array. This is no different than assigning from
Jeff King873cd282020-07-28 16:23:25 -040042 * `STRVEC_INIT`.
Heba Waly971b1f22019-11-17 21:04:52 +000043 */
Jeff King873cd282020-07-28 16:23:25 -040044void strvec_init(struct strvec *);
Heba Waly971b1f22019-11-17 21:04:52 +000045
46/* Push a copy of a string onto the end of the array. */
Jeff King873cd282020-07-28 16:23:25 -040047const char *strvec_push(struct strvec *, const char *);
Heba Waly971b1f22019-11-17 21:04:52 +000048
49/**
50 * Format a string and push it onto the end of the array. This is a
Jeff King873cd282020-07-28 16:23:25 -040051 * convenience wrapper combining `strbuf_addf` and `strvec_push`.
Heba Waly971b1f22019-11-17 21:04:52 +000052 */
Jeff Kingc1189ca2011-09-13 17:57:57 -040053__attribute__((format (printf,2,3)))
Jeff King873cd282020-07-28 16:23:25 -040054const char *strvec_pushf(struct strvec *, const char *fmt, ...);
Heba Waly971b1f22019-11-17 21:04:52 +000055
56/**
57 * Push a list of strings onto the end of the array. The arguments
58 * should be a list of `const char *` strings, terminated by a NULL
59 * argument.
60 */
Ramsay Jones9fe3edc2013-07-18 21:02:12 +010061LAST_ARG_MUST_BE_NULL
Jeff King873cd282020-07-28 16:23:25 -040062void strvec_pushl(struct strvec *, ...);
Heba Waly971b1f22019-11-17 21:04:52 +000063
64/* Push a null-terminated array of strings onto the end of the array. */
Jeff King873cd282020-07-28 16:23:25 -040065void strvec_pushv(struct strvec *, const char **);
Heba Waly971b1f22019-11-17 21:04:52 +000066
67/**
68 * Remove the final element from the array. If there are no
69 * elements in the array, do nothing.
70 */
Jeff King873cd282020-07-28 16:23:25 -040071void strvec_pop(struct strvec *);
Heba Waly971b1f22019-11-17 21:04:52 +000072
Johannes Schindelinc5aa6db2018-04-25 11:53:57 +020073/* Splits by whitespace; does not handle quoted arguments! */
Jeff King873cd282020-07-28 16:23:25 -040074void strvec_split(struct strvec *, const char *);
Heba Waly971b1f22019-11-17 21:04:52 +000075
76/**
77 * Free all memory associated with the array and return it to the
78 * initial, empty state.
79 */
Jeff King873cd282020-07-28 16:23:25 -040080void strvec_clear(struct strvec *);
Heba Waly971b1f22019-11-17 21:04:52 +000081
82/**
Linus Arverf10b0982024-01-12 07:06:35 +000083 * Disconnect the `v` member from the `strvec` struct and
Heba Waly971b1f22019-11-17 21:04:52 +000084 * return it. The caller is responsible for freeing the memory used
85 * by the array, and by the strings it references. After detaching,
Jeff King873cd282020-07-28 16:23:25 -040086 * the `strvec` is in a reinitialized state and can be pushed
Heba Waly971b1f22019-11-17 21:04:52 +000087 * into again.
88 */
Jeff King873cd282020-07-28 16:23:25 -040089const char **strvec_detach(struct strvec *);
90
Jeff Kingdbbcd442020-07-28 16:23:39 -040091#endif /* STRVEC_H */