gdbsupport/intrusive-list: make insert return an iterator

Make the insert method return an iterator to the inserted element.  This
mimics what boost does [1] and what the standard library insert methods
generally do [2].

[1] https://www.boost.org/doc/libs/1_79_0/doc/html/boost/intrusive/list.html#idm33771-bb
[2] https://en.cppreference.com/w/cpp/container/vector/insert

Change-Id: I59082883492c60ee95e8bb29a18c9376283dd660
Reviewed-by: Keith Seitz <keiths@redhat.com>

gdb/unittests/intrusive_list-selftests.c

@@ -446,15 +446,18 @@ struct intrusive_list_test
       ListType list;
 
 
-      list.insert (list.begin (), a);
+      auto a_it = list.insert (list.begin (), a);
+      SELF_CHECK (&*a_it == &a);
       expected = {&a};
       verify_items (list, expected);
 
-      list.insert (list.begin (), b);
+      auto b_it = list.insert (list.begin (), b);
+      SELF_CHECK (&*b_it == &b);
       expected = {&b, &a};
       verify_items (list, expected);
 
-      list.insert (list.begin (), c);
+      auto c_it = list.insert (list.begin (), c);
+      SELF_CHECK (&*c_it == &c);
       expected = {&c, &b, &a};
       verify_items (list, expected);
     }
@@ -465,15 +468,18 @@ struct intrusive_list_test
       ListType list;
 
 
-      list.insert (list.end (), a);
+      auto a_it = list.insert (list.end (), a);
+      SELF_CHECK (&*a_it == &a);
       expected = {&a};
       verify_items (list, expected);
 
-      list.insert (list.end (), b);
+      auto b_it = list.insert (list.end (), b);
+      SELF_CHECK (&*b_it == &b);
       expected = {&a, &b};
       verify_items (list, expected);
 
-      list.insert (list.end (), c);
+      auto c_it = list.insert (list.end (), c);
+      SELF_CHECK (&*c_it == &c);
       expected = {&a, &b, &c};
       verify_items (list, expected);
     }
@@ -486,7 +492,8 @@ struct intrusive_list_test
       list.push_back (a);
       list.push_back (b);
 
-      list.insert (list.iterator_to (b), c);
+      auto c_it = list.insert (list.iterator_to (b), c);
+      SELF_CHECK (&*c_it == &c);
       expected = {&a, &c, &b};
       verify_items (list, expected);
     }
@@ -496,7 +503,8 @@ struct intrusive_list_test
       item_type a ("a");
       ListType list;
 
-      list.insert (list.end (), a);
+      auto a_it = list.insert (list.end (), a);
+      SELF_CHECK (&*a_it == &a);
       expected = {&a};
       verify_items (list, expected);
     }

gdbsupport/intrusive_list.h

@@ -334,8 +334,10 @@ public:
       this->push_back_non_empty (elem);
   }
 
-  /* Inserts ELEM before POS.  */
-  void insert (const_iterator pos, reference elem) noexcept
+  /* Inserts ELEM before POS.
+
+     Returns an iterator to the inserted element.  */
+  iterator insert (const_iterator pos, reference elem) noexcept
   {
     if (this->empty ())
       return this->push_empty (elem);
@@ -359,6 +361,8 @@ public:
     prev_node->next = &elem;
     elem_node->next = pos_elem;
     pos_node->prev = &elem;
+
+    return this->iterator_to (elem);
   }
 
   /* Move elements from LIST at the end of the current list.  */
@@ -402,7 +406,7 @@ public:
 
 private:
   /* Push ELEM in the list, knowing the list is empty.  */
-  void push_empty (reference elem) noexcept
+  iterator push_empty (reference elem) noexcept
   {
     gdb_assert (this->empty ());
 
@@ -415,10 +419,12 @@ private:
     m_back = &elem;
     elem_node->prev = nullptr;
     elem_node->next = nullptr;
+
+    return this->iterator_to (elem);
   }
 
   /* Push ELEM at the front of the list, knowing the list is not empty.  */
-  void push_front_non_empty (reference elem) noexcept
+  iterator push_front_non_empty (reference elem) noexcept
   {
     gdb_assert (!this->empty ());
 
@@ -432,10 +438,12 @@ private:
     front_node->prev = &elem;
     elem_node->prev = nullptr;
     m_front = &elem;
+
+    return this->iterator_to (elem);
   }
 
   /* Push ELEM at the back of the list, knowing the list is not empty.  */
-  void push_back_non_empty (reference elem) noexcept
+  iterator push_back_non_empty (reference elem) noexcept
   {
     gdb_assert (!this->empty ());
 
@@ -449,6 +457,8 @@ private:
     back_node->next = &elem;
     elem_node->next = nullptr;
     m_back = &elem;
+
+    return this->iterator_to (elem);
   }
 
   void erase_element (reference elem) noexcept