argv-array: rename to strvec

The name "argv-array" isn't very good, because it describes what the
data type can be used for (program argument arrays), not what it
actually is (a dynamically-growing string array that maintains a
NULL-terminator invariant). This leads to people being hesitant to use
it for other cases where it would actually be a good fit. The existing
name is also clunky to use. It's overly long, and the name often leads
to saying things like "argv.argv" (i.e., the field names overlap with
variable names, since they're describing the use, not the type). Let's
give it a more neutral name.

I settled on "strvec" because "vector" is the name for a dynamic array
type in many programming languages. "strarray" would work, too, but it's
longer and a bit more awkward to say (and don't we all say these things
in our mind as we type them?).

A more extreme direction would be a generic data structure which stores
a NULL-terminated of _any_ type. That would be easy to do with void
pointers, but we'd lose some type safety for the existing cases. Plus it
raises questions about memory allocation and ownership. So I limited
myself here to changing names only, and not semantics. If we do find a
use for that more generic data type, we could perhaps implement it at a
lower level and then provide type-safe wrappers around it for strings.
But that can come later.

This patch does the minimum to convert the struct and function names in
the header and implementation, leaving a few things for follow-on
patches:

  - files retain their original names for now

  - struct field names are retained for now

  - there's a preprocessor compat layer that lets most users remain the
    same for now. The exception is headers which made a manual forward
    declaration of the struct. I've converted them (and their dependent
    function declarations) here.

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 32 insertions, 19 deletions

diff --git a/argv-array.h b/argv-array.h
index 4fc57b6..ca66a33 100644
--- a/argv-array.h
+++ b/argv-array.h
@@ -14,42 +14,42 @@
  * it contains an item structure with a `util` field that is not compatible
  * with the traditional argv interface.
  *
- * Each `argv_array` manages its own memory. Any strings pushed into the
- * array are duplicated, and all memory is freed by argv_array_clear().
+ * Each `strvec` manages its own memory. Any strings pushed into the
+ * array are duplicated, and all memory is freed by strvec_clear().
  */
 
-extern const char *empty_argv[];
+extern const char *empty_strvec[];
 
 /**
  * A single array. This should be initialized by assignment from
- * `ARGV_ARRAY_INIT`, or by calling `argv_array_init`. The `argv`
+ * `STRVEC_INIT`, or by calling `strvec_init`. The `argv`
  * member contains the actual array; the `argc` member contains the
  * number of elements in the array, not including the terminating
  * NULL.
  */
-struct argv_array {
+struct strvec {
 	const char **argv;
 	size_t argc;
 	size_t alloc;
 };
 
-#define ARGV_ARRAY_INIT { empty_argv, 0, 0 }
+#define STRVEC_INIT { empty_strvec, 0, 0 }
 
 /**
  * Initialize an array. This is no different than assigning from
- * `ARGV_ARRAY_INIT`.
+ * `STRVEC_INIT`.
  */
-void argv_array_init(struct argv_array *);
+void strvec_init(struct strvec *);
 
 /* Push a copy of a string onto the end of the array. */
-const char *argv_array_push(struct argv_array *, const char *);
+const char *strvec_push(struct strvec *, const char *);
 
 /**
  * Format a string and push it onto the end of the array. This is a
- * convenience wrapper combining `strbuf_addf` and `argv_array_push`.
+ * convenience wrapper combining `strbuf_addf` and `strvec_push`.
  */
 __attribute__((format (printf,2,3)))
-const char *argv_array_pushf(struct argv_array *, const char *fmt, ...);
+const char *strvec_pushf(struct strvec *, const char *fmt, ...);
 
 /**
  * Push a list of strings onto the end of the array. The arguments
@@ -57,33 +57,46 @@ const char *argv_array_pushf(struct argv_array *, const char *fmt, ...);
  * argument.
  */
 LAST_ARG_MUST_BE_NULL
-void argv_array_pushl(struct argv_array *, ...);
+void strvec_pushl(struct strvec *, ...);
 
 /* Push a null-terminated array of strings onto the end of the array. */
-void argv_array_pushv(struct argv_array *, const char **);
+void strvec_pushv(struct strvec *, const char **);
 
 /**
  * Remove the final element from the array. If there are no
  * elements in the array, do nothing.
  */
-void argv_array_pop(struct argv_array *);
+void strvec_pop(struct strvec *);
 
 /* Splits by whitespace; does not handle quoted arguments! */
-void argv_array_split(struct argv_array *, const char *);
+void strvec_split(struct strvec *, const char *);
 
 /**
  * Free all memory associated with the array and return it to the
  * initial, empty state.
  */
-void argv_array_clear(struct argv_array *);
+void strvec_clear(struct strvec *);
 
 /**
- * Disconnect the `argv` member from the `argv_array` struct and
+ * Disconnect the `argv` member from the `strvec` struct and
  * return it. The caller is responsible for freeing the memory used
  * by the array, and by the strings it references. After detaching,
- * the `argv_array` is in a reinitialized state and can be pushed
+ * the `strvec` is in a reinitialized state and can be pushed
  * into again.
  */
-const char **argv_array_detach(struct argv_array *);
+const char **strvec_detach(struct strvec *);
+
+/* compatibility for historic argv_array interface */
+#define argv_array strvec
+#define ARGV_ARRAY_INIT STRVEC_INIT
+#define argv_array_init strvec_init
+#define argv_array_push strvec_push
+#define argv_array_pushf strvec_pushf
+#define argv_array_pushl strvec_pushl
+#define argv_array_pushv strvec_pushv
+#define argv_array_pop strvec_pop
+#define argv_array_split strvec_split
+#define argv_array_clear strvec_clear
+#define argv_array_detach strvec_detach
 
 #endif /* ARGV_ARRAY_H */