Index: base/debug/format.h |
diff --git a/base/debug/format.h b/base/debug/format.h |
new file mode 100644 |
index 0000000000000000000000000000000000000000..ad2690139bed9818348a00984c845aae3f250fba |
--- /dev/null |
+++ b/base/debug/format.h |
@@ -0,0 +1,407 @@ |
+// Copyright (c) 2013 The Chromium Authors. All rights reserved. |
+// Use of this source code is governed by a BSD-style license that can be |
+// found in the LICENSE file. |
+// |
+// Author: markus@chromium.org |
+ |
+#ifndef BASE_DEBUG_FORMAT_H_ |
+#define BASE_DEBUG_FORMAT_H_ |
+ |
+#include <stddef.h> |
+#include <stdint.h> |
+#include <stdlib.h> |
+ |
+#if defined(__unix__) |
+// For ssize_t |
+#include <unistd.h> |
+#endif |
+ |
+#include "base/base_export.h" |
+#include "base/basictypes.h" |
+ |
+namespace base { |
+namespace debug { |
+ |
+#if defined(_MSC_VER) |
+// Define ssize_t inside of our namespace. |
jln (very slow on Chromium)
2013/08/01 00:03:15
The comment is a bit misleading since this won't b
|
+#if defined(_WIN64) |
+typedef __int64 ssize_t; |
+#else |
+typedef long ssize_t; |
+#endif |
+#endif |
+ |
+// Format() is a type-safe and async-signal-safe version of snprintf(). |
+// |
+// FormatN() is an alternative function signature that can be used when |
+// not dealing with fixed-sized buffers. When possible, Format() should always |
+// be used in favor of FormatN() |
jln (very slow on Chromium)
2013/08/01 00:03:15
s/in favor/instead/ ?
|
+// |
+// These functions allow for formatting complicated messages from contexts that |
+// require strict async-signal-safety. In fact, it is safe to call them from |
+// any low-level execution context; even from contexts that have stricter |
+// requirements than just async-signal-safety. |
+// |
+// The code currently only supports a subset of format characters: |
+// %c, %d, %x, %X, %p, and %s. |
+// |
+// Format() aims to be as liberal as reasonably possible. Integer-like values |
+// of arbitrary width can be passed to all of the format characters that expect |
+// integers. Thus, it is explicitly legal to pass an "int" to "%c", and output |
+// will automatically look at the LSB only. It is also explicitly legal to |
+// pass either signed or unsigned values, and the format characters will |
+// automatically interpret the arguments accordingly. |
+// |
+// It is still not legal to mix-and-match integer-like values with pointer |
+// values. For instance, you cannot pass a pointer to %x, nor can you pass an |
+// integer to %p. |
+// |
+// The one exception is "0" zero being accepted by "%p". This works-around |
+// the problem of C++ defining NULL as an integer-like value. |
+// |
+// All format characters take an optional width parameter. This must be a |
+// positive integer. For %d, %x, %X and %p, if the width starts with |
+// a leading '0', padding is done with '0' instead of ' ' characters. |
+// |
+// There are a few features of snprintf-style format strings, that Format() |
+// does not support at this time. If an actual user shows up, I would not be |
jln (very slow on Chromium)
2013/08/01 00:03:15
Could you try to phrase without the first person ?
|
+// opposed to adding support for these features. But that assumes that the |
+// trade-offs between complexity and utility are favorable. |
+// |
+// For example, adding support for negative padding widths, for %n and for |
+// octal numbers are all likely to be viewed positively. |
+// |
+// On the other hands, adding support for alternate forms, positional |
+// arguments, grouping, wide characters, localization or floating point numbers |
+// are all unlikely to ever be added. |
+// |
+// Format() and FormatN() mimicks the behavior of snprintf() and they return |
+// the number of bytes needed to store the untruncated output. This does *not* |
+// include the terminating NUL byte. |
+// |
+// They return -1, iff a fatal error happened. This typically can only happen, |
+// if the buffer size is a) negative, b) zero (i.e. not even the NUL byte can |
+// be written), or c) bigger than SSIZE_MAX. |
+// |
+// While the code supports type checking and while it is generally very careful |
+// to avoid printing incorrect values, it tends to be conservative in printing |
+// as much as possible, even when given incorrect parameters. Typically, in |
+// case of an error, the format string will not be expanded. (i.e. something |
+// like Format(buf, "%p %d", 1, 2) results in "%p 2"). |
+// |
+// The pre-C++11 version cannot handle more than ten arguments. |
+// |
+// Basic example: |
+// char buf[20]; |
+// base::debug::Format(buf, "The answer: %2d", 42); |
+// |
+// Example with dynamically sized buffer (async-signal-safe); this code won't |
+// work on Visual studio, as it requires dynamically allocating arrays on the |
+// stack: |
+// const size_t kInitialSize = 128; |
+// size_t sz = kInitialSize; |
+// for (;;) { |
+// char buf[sz]; |
jln (very slow on Chromium)
2013/08/01 00:03:15
I'm a bit uneasy with recommending such a pattern.
|
+// sz = FormatN(buf, sz, "Error message \"%s\"\n", err) + 1; |
+// if (sz > sizeof(buf)) |
+// continue; |
+// write(2, buf, sz-1); |
+// break; |
+// } |
+ |
+namespace internal { |
+ // Helpers that use C++ overloading, templates, and specializations to deduce |
+ // and record type information from function arguments. This allows us to |
+ // later write a type-safe version of snprintf(). |
+ |
+ struct Arg { |
+ // Any integer-like value. |
+ Arg(signed char c) : i_(c), width_(sizeof(char)), type_(INT) { } |
+ Arg(unsigned char c) : i_(c), width_(sizeof(char)), type_(UINT) { } |
+ Arg(signed short i) : i_(i), width_(sizeof(short)), type_(INT) { } |
+ Arg(unsigned short i) : i_(i), width_(sizeof(short)), type_(UINT) { } |
+ Arg(signed int i) : i_(i), width_(sizeof(int)), type_(INT) { } |
+ Arg(unsigned int i) : i_(i), width_(sizeof(int)), type_(UINT) { } |
+ Arg(signed long i) : i_(i), width_(sizeof(long)), type_(INT) { } |
+ Arg(unsigned long i) : i_(i), width_(sizeof(long)), type_(UINT) { } |
+ Arg(signed long long i) : i_(i), width_(sizeof(long long)), |
+ type_(INT) { } |
+ Arg(unsigned long long i) : i_(i), width_(sizeof(long long)), |
+ type_(UINT) { } |
+ |
+ // A C-style text string. |
+ Arg(const char* s) : s_(s), type_(STRING) { } |
+ Arg(char* s) : s_(s), type_(STRING) { } |
+ |
+ // Any pointer value that can be cast to a "void*". |
+ template<class T> Arg(T* ptr) : ptr_((void*)ptr), type_(POINTER) { } |
+ |
+ union { |
+ // An integer-like value. |
+ struct { |
+ int64_t i_; |
+ unsigned char width_; |
+ }; |
+ |
+ // A C-style text string. |
+ const char* s_; |
+ |
+ // A pointer to an arbitrary object. |
+ const void* ptr_; |
+ }; |
+ const enum { INT, UINT, STRING, POINTER } type_; |
jln (very slow on Chromium)
2013/08/01 00:03:15
Typedefs and enum should be first, please look at
|
+ }; |
+ |
+ // This is the internal function that performs the actual formatting of |
+ // an snprintf()-style format string. |
+ BASE_EXPORT ssize_t FormatN(char* buf, size_t sz, const char* fmt, |
+ const Arg* args, size_t max_args); |
+} // namespace internal |
+ |
+#if __cplusplus >= 201103 // C++11 |
+ |
+template<typename... Args> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, Args... args) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { args... }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, typename... Args> |
+ssize_t Format(char (&buf)[N], const char* fmt, Args... args) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { args... }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+#else // Pre-C++11 |
+ |
+// TODO(markus): C++11 has a much more concise and readable solution for |
+// expressing what we are doing here. Delete the fall-back code for older |
+// compilers as soon as we have fully switched to C++11 |
jln (very slow on Chromium)
2013/08/01 00:03:15
Nit: final dot.
|
+ |
+template<class T0, class T1, class T2, class T3, class T4, |
+ class T5, class T6, class T7, class T8, class T9> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, |
+ T5 arg5, T6 arg6, T7 arg7, T8 arg8, T9 arg9) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { |
+ arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9 |
+ }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, |
+ class T0, class T1, class T2, class T3, class T4, |
+ class T5, class T6, class T7, class T8, class T9> |
+ssize_t Format(char (&buf)[N], const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, |
+ T5 arg5, T6 arg6, T7 arg7, T8 arg8, T9 arg9) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { |
+ arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9 |
+ }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<class T0, class T1, class T2, class T3, class T4, |
+ class T5, class T6, class T7, class T8> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, |
+ T5 arg5, T6 arg6, T7 arg7, T8 arg8) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { |
+ arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8 |
+ }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, |
+ class T0, class T1, class T2, class T3, class T4, class T5, |
+ class T6, class T7, class T8> |
+ssize_t Format(char (&buf)[N], const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, |
+ T5 arg5, T6 arg6, T7 arg7, T8 arg8) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { |
+ arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8 |
+ }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<class T0, class T1, class T2, class T3, class T4, class T5, |
+ class T6, class T7> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, |
+ T5 arg5, T6 arg6, T7 arg7) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { |
+ arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7 |
+ }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, |
+ class T0, class T1, class T2, class T3, class T4, class T5, |
+ class T6, class T7> |
+ssize_t Format(char (&buf)[N], const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, |
+ T5 arg5, T6 arg6, T7 arg7) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { |
+ arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7 |
+ }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<class T0, class T1, class T2, class T3, class T4, class T5, |
+ class T6> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, |
+ T5 arg5, T6 arg6) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { |
+ arg0, arg1, arg2, arg3, arg4, arg5, arg6 |
+ }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, |
+ class T0, class T1, class T2, class T3, class T4, class T5, |
+ class T6> |
+ssize_t Format(char (&buf)[N], const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, T5 arg5, T6 arg6) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { |
+ arg0, arg1, arg2, arg3, arg4, arg5, arg6 |
+ }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<class T0, class T1, class T2, class T3, class T4, class T5> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, T5 arg5) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1, arg2, arg3, arg4, arg5 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, |
+ class T0, class T1, class T2, class T3, class T4, class T5> |
+ssize_t Format(char (&buf)[N], const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4, T5 arg5) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1, arg2, arg3, arg4, arg5 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<class T0, class T1, class T2, class T3, class T4> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1, arg2, arg3, arg4 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, class T0, class T1, class T2, class T3, class T4> |
+ssize_t Format(char (&buf)[N], const char* fmt, T0 arg0, T1 arg1, |
+ T2 arg2, T3 arg3, T4 arg4) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1, arg2, arg3, arg4 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<class T0, class T1, class T2, class T3> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1, arg2, arg3 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, class T0, class T1, class T2, class T3> |
+ssize_t Format(char (&buf)[N], const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2, T3 arg3) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1, arg2, arg3 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<class T0, class T1, class T2> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, |
+ T0 arg0, T1 arg1, T2 arg2) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1, arg2 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, class T0, class T1, class T2> |
+ssize_t Format(char (&buf)[N], const char* fmt, T0 arg0, T1 arg1, T2 arg2) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1, arg2 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<class T0, class T1> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, T0 arg0, T1 arg1) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, class T0, class T1> |
+ssize_t Format(char (&buf)[N], const char* fmt, T0 arg0, T1 arg1) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0, arg1 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<class T0> |
+ssize_t FormatN(char* buf, size_t N, const char* fmt, T0 arg0) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+ |
+template<size_t N, class T0> |
+ssize_t Format(char (&buf)[N], const char* fmt, T0 arg0) { |
+ // Use Arg() object to record type information and then copy arguments to an |
+ // array to make it easier to iterate over them. |
+ const internal::Arg arg_array[] = { arg0 }; |
+ return internal::FormatN(buf, N, fmt, arg_array, arraysize(arg_array)); |
+} |
+#endif |
+ |
+// Fast-path when we don't actually need to substitute any arguments. |
+BASE_EXPORT ssize_t FormatN(char* buf, size_t N, const char* fmt); |
+template<size_t N> |
+inline ssize_t Format(char (&buf)[N], const char* fmt) { |
+ return FormatN(buf, N, fmt); |
+} |
+ |
+} // namespace debug |
+} // namespace base |
+ |
+#endif // BASE_DEBUG_FORMAT_H_ |