[PATCH v2] enum_flags to_string (was: Re: [PATCH v2 07/29] Thread options & clone events (core + remote))

[Pedro Alves <pedro@palves.net>]

Some self review.  :-)

On 2022-10-27 8:55 p.m., Pedro Alves wrote:

> 
>  static std::string
>  to_string (some_flags flags)
>  {
>  #define CASE(X) { X, #X }
>    static constexpr test_flags::string_map_element mapping[] = {
>      CASE (SOME_FLAG1),
>      CASE (SOME_FLAG2),
>      CASE (SOME_FLAG3),
>    };
>  #undef CASE
> 
>    return flags.to_string (mapping);
>  }

I was looking at this again, and noticed I named the macro "CASE".  That's just
because that style of macro is typically used in a switch/case, my first approach
used one.  That isn't what's being done in the end, so better rename it.  And while doing that,
I realized that you don't even need to name the array or its type.  Like so:

static std::string
to_string (some_flags flags)
{
#define MAP_ENUM_FLAG(X) { X, #X }
  return flags.to_string ({
    MAP_ENUM_FLAG (SOME_FLAG1),
    MAP_ENUM_FLAG (SOME_FLAG3),
  });
#undef MAP_ENUM_FLAG
}

But then, every enum_flags to_string implementation will end up defining/undefining that
same macro, so might as well put it in gdbsupport/enum-flags.h, resulting in:

static std::string
to_string (test_flags flags)
{
  return flags.to_string ({
    MAP_ENUM_FLAG (FLAG1),
    MAP_ENUM_FLAG (FLAG3),
  });
}

> +  /* Convert this object to a std::string, using MAPPING as
> +     enumerator-to-string mapping array.  This is not meant to be
> +     called directly.  Instead, enum_flags specializations that have
> +     their own to_string function wrapping this one, thus hidding the
> +     mapping array from callers.  */

Something's off in that last sentence.  Fixed.

> +    /* If there were flags not included in the mapping, print them as
> +       an hex number.  */

Typo: "an hex" -> "a hex".  Fixed.

Here's the updated patch.

-- >8 --
From 957f039d7fab9bf515bb2c12d485cf2747fa78cc Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Tue, 25 Oct 2022 15:39:37 +0100
Subject: [PATCH v2] enum_flags to_string

This commit introduces shared infrastructure that can be used to
implement enum_flags -> to_string functions.  With this, if we want to
support converting a given enum_flags specialization to string, we
just need to implement a function that provides the enumerator->string
mapping, like so:

 enum some_flag
   {
     SOME_FLAG1 = 1 << 0,
     SOME_FLAG2 = 1 << 1,
     SOME_FLAG3 = 1 << 2,
   };

 DEF_ENUM_FLAGS_TYPE (some_flag, some_flags);

 static std::string
 to_string (some_flags flags)
 {
   return flags.to_string ({
     MAP_ENUM_FLAG (SOME_FLAG1),
     MAP_ENUM_FLAG (SOME_FLAG2),
     MAP_ENUM_FLAG (SOME_FLAG3),
   };
 }

.. and then to_string(SOME_FLAG2 | SOME_FLAG3) produces a string like
"0x6 [SOME_FLAG2 SOME_FLAG3]".

If we happen to forget to update the mapping array when we introduce a
new enumerator, then the string representation will pretty-print the
flags it knows about, and then the leftover flags in hex (one single
number).  For example, if we had missed mapping SOME_FLAG2 above, we'd
end up with:

  to_string(SOME_FLAG2 | SOME_FLAG3)  => "0x6 [SOME_FLAG2 0x4]");

Other than in the unit tests included, no actual usage of the
functionality is added in this commit.

Change-Id: I835de43c33d13bc0c95132f42c3f97318b875779
---
 gdb/unittests/enum-flags-selftests.c | 23 +++++++++++
 gdbsupport/enum-flags.h              | 57 ++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/gdb/unittests/enum-flags-selftests.c b/gdb/unittests/enum-flags-selftests.c
index f52fc7220a1..474b7ba43c8 100644
--- a/gdb/unittests/enum-flags-selftests.c
+++ b/gdb/unittests/enum-flags-selftests.c
@@ -374,6 +374,19 @@ enum test_uflag : unsigned
 DEF_ENUM_FLAGS_TYPE (test_flag, test_flags);
 DEF_ENUM_FLAGS_TYPE (test_uflag, test_uflags);
 
+/* to_string enumerator->string mapping function used to test
+   enum_flags::to_string.  This intentionally misses mapping one
+   enumerator (FLAG2).  */
+
+static std::string
+to_string (test_flags flags)
+{
+  return flags.to_string ({
+    MAP_ENUM_FLAG (FLAG1),
+    MAP_ENUM_FLAG (FLAG3),
+  });
+}
+
 static void
 self_test ()
 {
@@ -581,6 +594,16 @@ self_test ()
 
     SELF_CHECK (ok);
   }
+
+  /* Check string conversion.  */
+  {
+    SELF_CHECK (to_string (0) == "0x0 []");
+    SELF_CHECK (to_string (FLAG1) == "0x2 [FLAG1]");
+    SELF_CHECK (to_string (FLAG1 | FLAG3) == "0xa [FLAG1 FLAG3]");
+    SELF_CHECK (to_string (FLAG1 | FLAG2 | FLAG3) == "0xe [FLAG1 FLAG3 0x4]");
+    SELF_CHECK (to_string (FLAG2) == "0x4 [0x4]");
+    SELF_CHECK (to_string (test_flag (0xff)) == "0xff [FLAG1 FLAG3 0xf5]");
+  }
 }
 
 } /* namespace enum_flags_tests */
diff --git a/gdbsupport/enum-flags.h b/gdbsupport/enum-flags.h
index cd500f55ff3..2bf2f9a4638 100644
--- a/gdbsupport/enum-flags.h
+++ b/gdbsupport/enum-flags.h
@@ -130,6 +130,17 @@ class enum_flags
   typedef E enum_type;
   typedef typename enum_underlying_type<enum_type>::type underlying_type;
 
+  /* For to_string.  Maps one enumerator of E to a string.  */
+  struct string_map_element
+  {
+    E flag;
+    const char *str;
+  };
+
+  /* Convenience for to_string implementations, to build a
+     string_map_element array.  */
+#define MAP_ENUM_FLAG(ENUM_FLAG) { ENUM_FLAG, #ENUM_FLAG }
+
 public:
   /* Allow default construction.  */
   constexpr enum_flags ()
@@ -183,6 +194,52 @@ class enum_flags
   /* Binary operations involving some unrelated type (which would be a
      bug) are implemented as non-members, and deleted.  */
 
+  /* Convert this object to a std::string, using MAPPING as
+     enumerator-to-string mapping array.  This is not meant to be
+     called directly.  Instead, enum_flags specializations should have
+     their own to_string function wrapping this one, thus hidding the
+     mapping array from callers.  */
+
+  template<size_t N>
+  std::string
+  to_string (const string_map_element (&mapping)[N]) const
+  {
+    enum_type flags = raw ();
+    std::string res = hex_string (flags);
+    res += " [";
+
+    bool need_space = false;
+    for (const auto &entry : mapping)
+      {
+	if ((flags & entry.flag) != 0)
+	  {
+	    /* Do op~ in the underlying type, because if enum_type's
+	       underlying type is signed, op~ won't be defined for
+	       it.  */
+	    flags &= (enum_type) ~(underlying_type) entry.flag;
+
+	    if (need_space)
+	      res += " ";
+	    res += entry.str;
+
+	    need_space = true;
+	  }
+      }
+
+    /* If there were flags not included in the mapping, print them as
+       a hex number.  */
+    if (flags != 0)
+      {
+	if (need_space)
+	  res += " ";
+	res += hex_string (flags);
+      }
+
+    res += "]";
+
+    return res;
+  }
+
 private:
   /* Stored as enum_type because GDB knows to print the bit flags
      neatly if the enum values look like bit flags.  */

base-commit: 508ccf9b3e1db355037a4a1c9004efe0d6d3ffbf
-- 
2.36.0