argv-array: move doc to argv-array.h
Move the documentation from Documentation/technical/api-argv-array.txt to argv-array.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file. Also documentation/technical/api-argv-array.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and synchronized with the documentation in the header file. Signed-off-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heba Waly committed
Nov 17, 2019 at 21:04 UTC
971b1f24a2190ebe288fc6544378941a0624bb95
2 files changed
+62
-65
Documentation/technical/api-argv-array.txt
deleted
-65
@@ -1,65 +0,0 @@
1
-argv-array API
2
-==============
3
-
4
-The argv-array API allows one to dynamically build and store
5
-NULL-terminated lists. An argv-array maintains the invariant that the
6
-`argv` member always points to a non-NULL array, and that the array is
7
-always NULL-terminated at the element pointed to by `argv[argc]`. This
8
-makes the result suitable for passing to functions expecting to receive
9
-argv from main(), or the link:api-run-command.html[run-command API].
10
-
11
-The string-list API (documented in string-list.h) is similar, but cannot be
12
-used for these purposes; instead of storing a straight string pointer,
13
-it contains an item structure with a `util` field that is not compatible
14
-with the traditional argv interface.
15
-
16
-Each `argv_array` manages its own memory. Any strings pushed into the
17
-array are duplicated, and all memory is freed by argv_array_clear().
18
-
19
-Data Structures
20
----------------
21
-
22
-`struct argv_array`::
23
-
24
- A single array. This should be initialized by assignment from
25
- `ARGV_ARRAY_INIT`, or by calling `argv_array_init`. The `argv`
26
- member contains the actual array; the `argc` member contains the
27
- number of elements in the array, not including the terminating
28
- NULL.
29
-
30
-Functions
31
----------
32
-
33
-`argv_array_init`::
34
- Initialize an array. This is no different than assigning from
35
- `ARGV_ARRAY_INIT`.
36
-
37
-`argv_array_push`::
38
- Push a copy of a string onto the end of the array.
39
-
40
-`argv_array_pushl`::
41
- Push a list of strings onto the end of the array. The arguments
42
- should be a list of `const char *` strings, terminated by a NULL
43
- argument.
44
-
45
-`argv_array_pushf`::
46
- Format a string and push it onto the end of the array. This is a
47
- convenience wrapper combining `strbuf_addf` and `argv_array_push`.
48
-
49
-`argv_array_pushv`::
50
- Push a null-terminated array of strings onto the end of the array.
51
-
52
-`argv_array_pop`::
53
- Remove the final element from the array. If there are no
54
- elements in the array, do nothing.
55
-
56
-`argv_array_clear`::
57
- Free all memory associated with the array and return it to the
58
- initial, empty state.
59
-
60
-`argv_array_detach`::
61
- Disconnect the `argv` member from the `argv_array` struct and
62
- return it. The caller is responsible for freeing the memory used
63
- by the array, and by the strings it references. After detaching,
64
- the `argv_array` is in a reinitialized state and can be pushed
65
- into again.
argv-array.h
+62
@@ -1,8 +1,32 @@
1
#ifndef ARGV_ARRAY_H
2
#define ARGV_ARRAY_H
3
4
+/**
5
+ * The argv-array API allows one to dynamically build and store
6
+ * NULL-terminated lists. An argv-array maintains the invariant that the
7
+ * `argv` member always points to a non-NULL array, and that the array is
8
+ * always NULL-terminated at the element pointed to by `argv[argc]`. This
9
+ * 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
+ *
17
+ * Each `argv_array` manages its own memory. Any strings pushed into the
18
+ * array are duplicated, and all memory is freed by argv_array_clear().
19
+ */
20
+
21
extern const char *empty_argv[];
22
23
+/**
24
+ * A single array. This should be initialized by assignment from
25
+ * `ARGV_ARRAY_INIT`, or by calling `argv_array_init`. The `argv`
26
+ * member contains the actual array; the `argc` member contains the
27
+ * number of elements in the array, not including the terminating
28
+ * NULL.
29
+ */
30
struct argv_array {
31
const char **argv;
32
int argc;
@@ -11,17 +35,55 @@ struct argv_array {
35
36
#define ARGV_ARRAY_INIT { empty_argv, 0, 0 }
37
38
+/**
39
+ * Initialize an array. This is no different than assigning from
40
+ * `ARGV_ARRAY_INIT`.
41
+ */
42
void argv_array_init(struct argv_array *);
43
+
44
+/* Push a copy of a string onto the end of the array. */
45
const char *argv_array_push(struct argv_array *, const char *);
46
+
47
+/**
48
+ * Format a string and push it onto the end of the array. This is a
49
+ * convenience wrapper combining `strbuf_addf` and `argv_array_push`.
50
+ */
51
__attribute__((format (printf,2,3)))
52
const char *argv_array_pushf(struct argv_array *, const char *fmt, ...);
53
+
54
+/**
55
+ * Push a list of strings onto the end of the array. The arguments
56
+ * should be a list of `const char *` strings, terminated by a NULL
57
+ * argument.
58
+ */
59
LAST_ARG_MUST_BE_NULL
60
void argv_array_pushl(struct argv_array *, ...);
61
+
62
+/* Push a null-terminated array of strings onto the end of the array. */
63
void argv_array_pushv(struct argv_array *, const char **);
64
+
65
+/**
66
+ * Remove the final element from the array. If there are no
67
+ * elements in the array, do nothing.
68
+ */
69
void argv_array_pop(struct argv_array *);
70
+
71
/* Splits by whitespace; does not handle quoted arguments! */
72
void argv_array_split(struct argv_array *, const char *);
73
+
74
+/**
75
+ * Free all memory associated with the array and return it to the
76
+ * initial, empty state.
77
+ */
78
void argv_array_clear(struct argv_array *);
79
+
80
+/**
81
+ * Disconnect the `argv` member from the `argv_array` struct and
82
+ * return it. The caller is responsible for freeing the memory used
83
+ * by the array, and by the strings it references. After detaching,
84
+ * the `argv_array` is in a reinitialized state and can be pushed
85
+ * into again.
86
+ */
87
const char **argv_array_detach(struct argv_array *);
88
89
#endif /* ARGV_ARRAY_H */