2 * Routines for value_strings
4 * Wireshark - Network traffic analyzer
5 * By Gerald Combs <gerald@wireshark.org>
6 * Copyright 1998 Gerald Combs
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License
10 * as published by the Free Software Foundation; either version 2
11 * of the License, or (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
29 #include "wmem/wmem.h"
32 #include "value_string.h"
34 /* REGULAR VALUE STRING */
36 /* Tries to match val against each element in the value_string array vs.
37 Returns the associated string ptr on a match.
38 Formats val with fmt, and returns the resulting string, on failure. */
40 val_to_str(const guint32 val, const value_string *vs, const char *fmt)
44 DISSECTOR_ASSERT(fmt != NULL);
46 ret = try_val_to_str(val, vs);
50 return ep_strdup_printf(fmt, val);
53 /* Tries to match val against each element in the value_string array vs.
54 Returns the associated string ptr on a match.
55 Returns 'unknown_str', on failure. */
57 val_to_str_const(const guint32 val, const value_string *vs,
58 const char *unknown_str)
62 DISSECTOR_ASSERT(unknown_str != NULL);
64 ret = try_val_to_str(val, vs);
71 /* Tries to match val against each element in the value_string array vs.
72 Returns the associated string ptr, and sets "*idx" to the index in
73 that table, on a match, and returns NULL, and sets "*idx" to -1,
76 try_val_to_str_idx(const guint32 val, const value_string *vs, gint *idx)
80 DISSECTOR_ASSERT(idx != NULL);
83 while (vs[i].strptr) {
84 if (vs[i].value == val) {
96 /* Like try_val_to_str_idx(), but doesn't return the index. */
98 try_val_to_str(const guint32 val, const value_string *vs)
101 return try_val_to_str_idx(val, vs, &ignore_me);
104 /* 64-BIT VALUE STRING */
107 val64_to_str(const guint64 val, const val64_string *vs, const char *fmt)
111 DISSECTOR_ASSERT(fmt != NULL);
113 ret = try_val64_to_str(val, vs);
117 return ep_strdup_printf(fmt, val);
121 val64_to_str_const(const guint64 val, const val64_string *vs,
122 const char *unknown_str)
126 DISSECTOR_ASSERT(unknown_str != NULL);
128 ret = try_val64_to_str(val, vs);
136 try_val64_to_str_idx(const guint64 val, const val64_string *vs, gint *idx)
140 DISSECTOR_ASSERT(idx != NULL);
143 while (vs[i].strptr) {
144 if (vs[i].value == val) {
146 return(vs[i].strptr);
157 try_val64_to_str(const guint64 val, const val64_string *vs)
160 return try_val64_to_str_idx(val, vs, &ignore_me);
163 /* REVERSE VALUE STRING */
165 /* We use the same struct as for regular value strings, but we look up strings
166 * and return values instead */
168 /* Like val_to_str except backwards */
170 str_to_val(const gchar *val, const value_string *vs, const guint32 err_val)
174 i = str_to_val_idx(val, vs);
183 /* Find the index of a string in a value_string, or -1 when not present */
185 str_to_val_idx(const gchar *val, const value_string *vs)
191 while (vs[i].strptr) {
193 if (strcmp(vs[i].strptr, val) == 0) {
205 /* EXTENDED VALUE STRING */
207 /* Extended value strings allow fast(er) value_string array lookups by
208 * using (if possible) direct access or a binary search of the array.
210 * If the values in the value_string array are a contiguous range of values
211 * from min to max, the value will be used as as a direct index into the array.
213 * If the values in the array are not contiguous (ie: there are "gaps"),
214 * but are in assending order a binary search will be used.
216 * If direct access or binary search cannot be used, then a linear search
217 * is used and a warning is emitted.
219 * Note that the value_string array used with VALUE_STRING_EXT_INIT
220 * *must* be terminated with {0, NULL}).
222 * Extended value strings are defined at compile time as follows:
223 * static const value_string vs[] = { {value1, "string1"},
224 * {value2, "string2"},
227 * static value_string_ext vse = VALUE_STRING_EXT_INIT(vs);
229 * Extended value strings can be created at runtime by calling
230 * value_string_ext_new(<ptr to value_string array>,
231 * <total number of entries in the value_string_array>,
232 * <value_string_name>);
233 * Note: The <total number of entries in the value_string_array> should include
234 * the {0, NULL} entry.
237 /* Create a value_string_ext given a ptr to a value_string array and the total
238 * number of entries. Note that the total number of entries should include the
239 * required {0, NULL} terminating entry of the array.
240 * Returns a pointer to an epan-scoped'd and initialized value_string_ext
243 value_string_ext_new(const value_string *vs, guint vs_tot_num_entries,
244 const gchar *vs_name)
246 value_string_ext *vse;
248 DISSECTOR_ASSERT (vs_name != NULL);
249 DISSECTOR_ASSERT (vs_tot_num_entries > 0);
250 /* Null-terminated value-string ? */
251 DISSECTOR_ASSERT (vs[vs_tot_num_entries-1].strptr == NULL);
253 vse = wmem_new(wmem_epan_scope(), value_string_ext);
255 vse->_vs_num_entries = vs_tot_num_entries - 1;
256 /* We set our 'match' function to the init function, which finishes by
257 * setting the match function properly and then calling it. This is a
258 * simple way to do lazy initialization of extended value strings.
259 * The init function also sets up _vs_first_value for us. */
260 vse->_vs_first_value = 0;
261 vse->_vs_match2 = _try_val_to_str_ext_init;
262 vse->_vs_name = vs_name;
268 value_string_ext_free(const value_string_ext *vse)
270 wmem_free(wmem_epan_scope(), (void *)vse);
273 /* Like try_val_to_str for extended value strings */
275 try_val_to_str_ext(const guint32 val, value_string_ext *vse)
278 const value_string *vs = vse->_vs_match2(val, vse);
288 /* Like try_val_to_str_idx for extended value strings */
290 try_val_to_str_idx_ext(const guint32 val, value_string_ext *vse, gint *idx)
293 const value_string *vs = vse->_vs_match2(val, vse);
295 *idx = (gint) (vs - vse->_vs_p);
303 /* Like val_to_str for extended value strings */
305 val_to_str_ext(const guint32 val, value_string_ext *vse, const char *fmt)
309 DISSECTOR_ASSERT(fmt != NULL);
311 ret = try_val_to_str_ext(val, vse);
315 return ep_strdup_printf(fmt, val);
318 /* Like val_to_str_const for extended value strings */
320 val_to_str_ext_const(const guint32 val, value_string_ext *vse,
321 const char *unknown_str)
325 DISSECTOR_ASSERT(unknown_str != NULL);
327 ret = try_val_to_str_ext(val, vse);
334 /* Fallback linear matching algorithm for extended value strings */
335 static const value_string *
336 _try_val_to_str_linear(const guint32 val, value_string_ext *vse)
338 const value_string *vs_p = vse->_vs_p;
340 for (i=0; i<vse->_vs_num_entries; i++) {
341 if (vs_p[i].value == val)
347 /* Constant-time matching algorithm for contiguous extended value strings */
348 static const value_string *
349 _try_val_to_str_index(const guint32 val, value_string_ext *vse)
353 i = val - vse->_vs_first_value;
354 if (i < vse->_vs_num_entries) {
355 g_assert (val == vse->_vs_p[i].value);
356 return &(vse->_vs_p[i]);
361 /* log(n)-time matching algorithm for sorted extended value strings */
362 static const value_string *
363 _try_val_to_str_bsearch(const guint32 val, value_string_ext *vse)
368 for (low = 0, max = vse->_vs_num_entries; low < max; ) {
370 item = vse->_vs_p[i].value;
377 return &(vse->_vs_p[i]);
382 /* Initializes an extended value string. Behaves like a match function to
383 * permit lazy initialization of extended value strings.
384 * - Goes through the value_string array to determine the fastest possible
386 * - Verifies that the value_string contains no NULL string pointers.
387 * - Verifies that the value_string is terminated by {0, NULL}
390 _try_val_to_str_ext_init(const guint32 val, value_string_ext *vse)
392 const value_string *vs_p = vse->_vs_p;
393 const guint vs_num_entries = vse->_vs_num_entries;
395 /* The matching algorithm used:
396 * VS_SEARCH - slow sequential search (as in a normal value string)
397 * VS_BIN_TREE - log(n)-time binary search, the values must be sorted
398 * VS_INDEX - constant-time index lookup, the values must be contiguous
400 enum { VS_SEARCH, VS_BIN_TREE, VS_INDEX } type = VS_INDEX;
402 /* Note: The value_string 'value' is *unsigned*, but we do a little magic
403 * to help with value strings that have negative values.
405 * { -3, -2, -1, 0, 1, 2 }
406 * will be treated as "ascending ordered" (although it isn't technically),
407 * thus allowing constant-time index search
409 * { -3, -2, 0, 1, 2 } and { -3, -2, -1, 0, 2 }
410 * will both be considered as "out-of-order with gaps", thus falling
411 * back to the slow linear search
413 * { 0, 1, 2, -3, -2 } and { 0, 2, -3, -2, -1 }
414 * will be considered "ascending ordered with gaps" thus allowing
415 * a log(n)-time 'binary' search
417 * If you're confused, think of how negative values are represented, or
418 * google two's complement.
425 DISSECTOR_ASSERT((vs_p[vs_num_entries].value == 0) &&
426 (vs_p[vs_num_entries].strptr == NULL));
428 vse->_vs_first_value = vs_p[0].value;
429 first_value = vs_p[0].value;
430 prev_value = first_value;
432 for (i = 0; i < vs_num_entries; i++) {
433 DISSECTOR_ASSERT(vs_p[i].strptr != NULL);
434 if ((type == VS_INDEX) && (vs_p[i].value != (i + first_value))) {
437 /* XXX: Should check for dups ?? */
438 if (type == VS_BIN_TREE) {
439 if (prev_value > vs_p[i].value) {
440 g_warning("Extended value string '%s' forced to fall back to linear search:\n"
441 " entry %u, value %u [%#x] < previous entry, value %u [%#x]",
442 vse->_vs_name, i, vs_p[i].value, vs_p[i].value, prev_value, prev_value);
446 if (first_value > vs_p[i].value) {
447 g_warning("Extended value string '%s' forced to fall back to linear search:\n"
448 " entry %u, value %u [%#x] < first entry, value %u [%#x]",
449 vse->_vs_name, i, vs_p[i].value, vs_p[i].value, first_value, first_value);
455 prev_value = vs_p[i].value;
460 vse->_vs_match2 = _try_val_to_str_linear;
463 vse->_vs_match2 = _try_val_to_str_bsearch;
466 vse->_vs_match2 = _try_val_to_str_index;
469 g_assert_not_reached();
473 return vse->_vs_match2(val, vse);
476 /* STRING TO STRING MATCHING */
478 /* string_string is like value_string except the values being matched are
479 * also strings (instead of unsigned integers) */
481 /* Like val_to_str except for string_string */
483 str_to_str(const gchar *val, const string_string *vs, const char *fmt)
487 DISSECTOR_ASSERT(fmt != NULL);
489 ret = try_str_to_str(val, vs);
493 return ep_strdup_printf(fmt, val);
496 /* Like try_val_to_str_idx except for string_string */
498 try_str_to_str_idx(const gchar *val, const string_string *vs, gint *idx)
503 while (vs[i].strptr) {
504 if (!strcmp(vs[i].value,val)) {
506 return(vs[i].strptr);
516 /* Like try_val_to_str except for string_string */
518 try_str_to_str(const gchar *val, const string_string *vs)
521 return try_str_to_str_idx(val, vs, &ignore_me);
524 /* RANGE TO STRING MATCHING */
526 /* range_string is like value_string except the values being matched are
527 * integer ranges (for example, 0-10, 11-19, etc.) instead of single values. */
529 /* Like val_to_str except for range_string */
531 rval_to_str(const guint32 val, const range_string *rs, const char *fmt)
533 const gchar *ret = NULL;
535 DISSECTOR_ASSERT(fmt != NULL);
537 ret = try_rval_to_str(val, rs);
541 return ep_strdup_printf(fmt, val);
544 /* Like val_to_str_const except for range_string */
546 rval_to_str_const(const guint32 val, const range_string *rs,
547 const char *unknown_str)
549 const gchar *ret = NULL;
551 DISSECTOR_ASSERT(unknown_str != NULL);
553 ret = try_rval_to_str(val, rs);
560 /* Like try_val_to_str_idx except for range_string */
562 try_rval_to_str_idx(const guint32 val, const range_string *rs, gint *idx)
567 while(rs[i].strptr) {
568 if( (val >= rs[i].value_min) && (val <= rs[i].value_max) ) {
570 return (rs[i].strptr);
580 /* Like try_val_to_str except for range_string */
582 try_rval_to_str(const guint32 val, const range_string *rs)
585 return try_rval_to_str_idx(val, rs, &ignore_me);
590 /* Functions for use by proto_registrar_dump_values(), see proto.c */
593 value_string_ext_validate(const value_string_ext *vse)
597 #ifndef _WIN32 /* doesn't work on Windows for refs from another DLL ?? */
598 if ((vse->_vs_match2 != _try_val_to_str_ext_init) &&
599 (vse->_vs_match2 != _try_val_to_str_linear) &&
600 (vse->_vs_match2 != _try_val_to_str_bsearch) &&
601 (vse->_vs_match2 != _try_val_to_str_index))
608 value_string_ext_match_type_str(const value_string_ext *vse)
610 if (vse->_vs_match2 == _try_val_to_str_ext_init)
611 return "[Not Initialized]";
612 if (vse->_vs_match2 == _try_val_to_str_linear)
613 return "[Linear Search]";
614 if (vse->_vs_match2 == _try_val_to_str_bsearch)
615 return "[Binary Search]";
616 if (vse->_vs_match2 == _try_val_to_str_index)
617 return "[Direct (indexed) Access]";
622 * Editor modelines - http://www.wireshark.org/tools/modelines.html
627 * indent-tabs-mode: nil
630 * vi: set shiftwidth=4 tabstop=8 expandtab:
631 * :indentSize=4:tabSize=8:noTabs=true: