Rename value string (and similar) functions to use a consistent pattern. This

was done using textual search+replace, not anything syntax-aware, so presumably
it got most comments as well (except where there were typos).

Use a consistent coding style, and make proper use of the WS_DLL_* defines.

Group the functions appropriately in the header.

I ended up getting rid of most of the explanatory comments since many of them
duplicated what was in the value_string.c file (and were out of sync with the
recent updates I made to those in r48633). Presumably most of the comments
should be in the .h file not the .c file, but there's enough churn ahead that
it's not worth fixing yet.

Part of https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=8467

svn path=/trunk/; revision=48634

1 files changed, 75 insertions, 126 deletions

diff --git a/epan/value_string.h b/epan/value_string.h
index bfdb33bb05..cdb8a8272a 100644
--- a/epan/value_string.h
+++ b/epan/value_string.h
@@ -28,93 +28,31 @@
 #include <glib.h>
 #include "ws_symbol_export.h"
 
-/* Struct for the val_to_str, match_strval_idx, and match_strval functions */
+/* VALUE TO STRING MATCHING */
 
 typedef struct _value_string {
   guint32  value;
   const gchar   *strptr;
 } value_string;
 
-/* Struct for the str_to_str, match_strstr_idx, and match_strstr functions */
+WS_DLL_PUBLIC
+const gchar*
+val_to_str(const guint32 val, const value_string *vs, const char *fmt);
 
-typedef struct _string_string {
-  const gchar   *value;
-  const gchar   *strptr;
-} string_string;
-
-/* Struct for the rval_to_str, match_strrval_idx, and match_strrval functions */
-typedef struct _range_string {
-  guint32        value_min;
-  guint32        value_max;
-  const gchar   *strptr;
-} range_string;
-
-/* #define VS_DEF(x) { x, #x } */
-/* #define VS_END    { 0, NULL } */
-
-/* Tries to match val against each element in the value_string array vs.
-   Returns the associated string ptr, and sets "*idx" to the index in
-   that table, on a match, and returns NULL, and sets "*idx" to -1,
-   on failure. */
-WS_DLL_PUBLIC const gchar* match_strval_idx(const guint32 val, const value_string *vs, gint *idx);
-
-/* Like match_strval_idx(), but doesn't return the index. */
-WS_DLL_PUBLIC const gchar* match_strval(const guint32 val, const value_string *vs);
-
-/* Tries to match val against each element in the value_string array vs.
-   Returns the associated string ptr on a match.
-   Formats val with fmt, and returns the resulting string, on failure. */
-WS_DLL_PUBLIC const gchar* val_to_str(const guint32 val, const value_string *vs, const char *fmt);
+WS_DLL_PUBLIC
+const gchar*
+val_to_str_const(const guint32 val, const value_string *vs, const char *unknown_str);
 
+WS_DLL_PUBLIC
+const gchar*
+try_val_to_str(const guint32 val, const value_string *vs);
 
-/* Tries to match val against each element in the value_string array vs.
-   Returns the associated string ptr on a match.
-   Returns 'unknown_str', on failure. */
-WS_DLL_PUBLIC const gchar* val_to_str_const(const guint32 val, const value_string *vs, const char *unknown_str);
+WS_DLL_PUBLIC
+const gchar*
+try_val_to_str_idx(const guint32 val, const value_string *vs, gint *idx);
 
-/* Tries to match val against each element in the string_string array vs.
-   Returns the associated string ptr, and sets "*idx" to the index in
-   that table, on a match, and returns NULL, and sets "*idx" to -1,
-   on failure. */
-extern const gchar* match_strstr_idx(const gchar *val, const string_string *vs, gint *idx);
+/* EXTENDED VALUE TO STRING MATCHING */
 
-/* Like match_strstr_idx(), but doesn't return the index. */
-extern const gchar* match_strstr(const gchar *val, const string_string *vs);
-
-/* Tries to match val against each element in the string_string array vs.
-   Returns the associated string ptr on a match.
-   Formats val with fmt, and returns the resulting string, on failure. */
-WS_DLL_PUBLIC const gchar* str_to_str(const gchar *val, const string_string *vs, const char *fmt);
-
-/* --------------------------------------------------------------------*/
-/* value_string_ext functions
- *
- *   Extended value strings allow fast(er) value_string array lookups by
- *    using (if possible) direct access or a binary search of the array.
- *
- *    If the values in the value_string array are a contiguous range of values
- *    from min to max, the value will be used as as a direct index into the array.
- *
- *    If the values in the array are not contiguous (ie: there are "gaps"),
- *    but are in assending order a binary search will be used.
- *
- *    If direct access or binary search cannot be used, then a linear search
- *    is used.
- *
- *    Note that the value_string array used with VALUE_STRING_EXT_INIT
- *     *must* be terminated with {0, NULL}).
- *
- *    Extended value strings are defined at compile time as follows:
- *      static const value_string vs[] = { {value1, "string1"}, {value2, "string2"}, ..., {0, NULL}};
- *      static value_string_ext vse = VALUE_STRING_EXT_INIT(vs);
- *
- *    Extended value strings can be created at runtime by calling
- *      value_string_ext_new(<ptr to value_string array>,
- *                           <total number of entries in the value_string_array>,
- *                           <value_string_name>);
- *      Note: <total number of entries in the value_string_array> should include the {0, NULL} entry
- */
-/* --------------------------------------------------------------------*/
 struct _value_string_ext;
 typedef const value_string *(*_value_string_match2_t)(const guint32, const struct _value_string_ext *);
 
@@ -127,50 +65,78 @@ typedef struct _value_string_ext {
   const gchar *_vs_name;      /* vse "Name" (for error messages)             */
 } value_string_ext;
 
-/* "Accessors" */
 #define VALUE_STRING_EXT_VS_P(x) (x)->_vs_p
 #define VALUE_STRING_EXT_VS_NUM_ENTRIES(x) (x)->_vs_num_entries
 #define VALUE_STRING_EXT_VS_NAME(x) (x)->_vs_name
 
-/* (Fcns for use by proto_registrar_dump_values() [See proto.c]) */
-gboolean value_string_ext_validate(const value_string_ext *vse);
-const gchar *value_string_ext_match_type_str(const value_string_ext *vse);
-/* --- --- */
+WS_DLL_PUBLIC
+const value_string*
+_try_val_to_str_ext_init(const guint32 val, const value_string_ext *vse);
+#define VALUE_STRING_EXT_INIT(x) { _try_val_to_str_ext_init, 0, array_length(x)-1, x, #x }
 
-WS_DLL_PUBLIC const value_string *_match_strval_ext_init(const guint32 val, const value_string_ext *vse);
-#define VALUE_STRING_EXT_INIT(x) { _match_strval_ext_init, 0, array_length(x)-1, x, #x }
+WS_DLL_PUBLIC
+value_string_ext*
+value_string_ext_new(value_string *vs, guint vs_tot_num_entries, const gchar *vs_name);
 
-/* Create a value_string_ext given a ptr to a value_string array and the total number of entries. */
-/* Note: vs_tot_num_entries should include the required {0, NULL} terminating entry of the array. */
-/* Return: a pointer to a gmalloc'd and initialized value_string_ext struct.                      */
-extern value_string_ext *value_string_ext_new(value_string *vs, guint vs_tot_num_entries, const gchar *vs_name);
+WS_DLL_PUBLIC
+const gchar*
+val_to_str_ext(const guint32 val, const value_string_ext *vs, const char *fmt);
 
-/* Looks up val in a value_string array using access method (direct, binary search
- *  or linear) determined at rutime during the initial access); (see _match_strval_ext_init)
- * Returns the associated string ptr on a match or NULL on failure.
- */
-WS_DLL_PUBLIC const gchar* match_strval_ext(const guint32 val, const value_string_ext *vse);
+WS_DLL_PUBLIC
+const gchar*
+val_to_str_ext_const(const guint32 val, const value_string_ext *vs, const char *unknown_str);
 
-/* Tries to match val against each element in the value_string array vs.
- *  Returns the associated string ptr, and sets "*idx" to the index in
- *  that table, on a match, and returns NULL, and sets "*idx" to -1,
- *  on failure.
- */
-const gchar* match_strval_idx_ext(const guint32 val, value_string_ext *vse, gint *idx);
+WS_DLL_PUBLIC
+const gchar*
+try_val_to_str_ext(const guint32 val, const value_string_ext *vse);
 
-/*
- Similar to match_strval_ext except that on failure
- * Formats val with fmt, and returns the resulting string
- */
-WS_DLL_PUBLIC const gchar* val_to_str_ext(const guint32 val, const value_string_ext *vs, const char *fmt);
+WS_DLL_PUBLIC
+const gchar*
+try_val_to_str_idx_ext(const guint32 val, value_string_ext *vse, gint *idx);
 
-/*
- Similar to match_strval_ext except that on failure
- *  Returns 'unknown_str'
- */
-WS_DLL_PUBLIC const gchar* val_to_str_ext_const(const guint32 val, const value_string_ext *vs, const char *unknown_str);
+/* STRING TO STRING MATCHING */
+
+typedef struct _string_string {
+  const gchar   *value;
+  const gchar   *strptr;
+} string_string;
+
+WS_DLL_PUBLIC
+const gchar*
+str_to_str(const gchar *val, const string_string *vs, const char *fmt);
+
+WS_DLL_PUBLIC
+const gchar*
+try_str_to_str(const gchar *val, const string_string *vs);
+
+WS_DLL_PUBLIC
+const gchar*
+try_str_to_str_idx(const gchar *val, const string_string *vs, gint *idx);
+
+/* RANGE TO STRING MATCHING */
+
+typedef struct _range_string {
+  guint32        value_min;
+  guint32        value_max;
+  const gchar   *strptr;
+} range_string;
+
+WS_DLL_PUBLIC
+const gchar*
+rval_to_str(const guint32 val, const range_string *rs, const char *fmt);
+
+WS_DLL_PUBLIC
+const gchar*
+try_rval_to_str(const guint32 val, const range_string *rs);
+
+WS_DLL_PUBLIC
+const gchar*
+try_rval_to_str_idx(const guint32 val, const range_string *rs, gint *idx);
+
+/* MISC (generally do not use) */
 
-/* ---- ---- */
+gboolean value_string_ext_validate(const value_string_ext *vse);
+const gchar *value_string_ext_match_type_str(const value_string_ext *vse);
 
 /* Generate a string describing an enumerated bitfield (an N-bit field
    with various specific values having particular names). */
@@ -182,21 +148,4 @@ WS_DLL_PUBLIC const char *decode_enumerated_bitfield(const guint32 val, const gu
 WS_DLL_PUBLIC const char *decode_enumerated_bitfield_shifted(const guint32 val, const guint32 mask,
   const int width, const value_string *tab, const char *fmt);
 
-
-/* ranges aware versions */
-
-/* Tries to match val against each range in the range_string array rs.
-   Returns the associated string ptr on a match.
-   Formats val with fmt, and returns the resulting string, on failure. */
-WS_DLL_PUBLIC const gchar* rval_to_str(const guint32 val, const range_string *rs, const char *fmt);
-
-/* Tries to match val against each range in the range_string array rs.
-   Returns the associated string ptr, and sets "*idx" to the index in
-   that table, on a match, and returns NULL, and sets "*idx" to -1,
-   on failure. */
-WS_DLL_PUBLIC const gchar *match_strrval_idx(const guint32 val, const range_string *rs, gint *idx);
-
-/* Like match_strrval_idx(), but doesn't return the index. */
-WS_DLL_PUBLIC const gchar *match_strrval(const guint32 val, const range_string *rs);
-
 #endif /* __VALUE_STRING_H__ */