Add an equal_range utility function

This is to make the equal_range method of multimap easier to use.
The usage is illustrated in this commit by an example in
java_static_initializers which allows use to use range-for.
This will be also useful in following commits.

Author: romainbrenguier

jbmc/src/java_bytecode/java_static_initializers.cpp

@@ -988,21 +988,21 @@ code_blockt stub_global_initializer_factoryt::get_stub_initializer_body(
   // class. Note this is the same invocation used in
   // java_static_lifetime_init.
 
-  auto class_globals = stub_globals_by_class.equal_range(*class_id);
+  auto class_globals = equal_range(stub_globals_by_class, *class_id);
   INVARIANT(
-    class_globals.first != class_globals.second,
+    !class_globals.empty(),
     "class with synthetic clinit should have at least one global to init");
 
   java_object_factory_parameterst parameters = object_factory_parameters;
   parameters.function_id = function_id;
 
-  for(auto it = class_globals.first; it != class_globals.second; ++it)
+  for(const auto &pair : class_globals)
   {
     const symbol_exprt new_global_symbol =
-      symbol_table.lookup_ref(it->second).symbol_expr();
+      symbol_table.lookup_ref(pair.second).symbol_expr();
 
     parameters.min_null_tree_depth =
-      is_non_null_library_global(it->second)
+      is_non_null_library_global(pair.second)
         ? object_factory_parameters.min_null_tree_depth + 1
         : object_factory_parameters.min_null_tree_depth;
 

src/util/range.h

@@ -533,4 +533,15 @@ auto make_range(containert &container) -> ranget<decltype(container.begin())>
     container.begin(), container.end());
 }
 
+/// Utility function to make equal_range method of multimap easier to use by
+/// returning a ranget object. For instance, we can write:
+/// `for(auto value : equal_range(map, key).filter(...).map(...)) {...}`.
+template <typename multimapt>
+ranget<typename multimapt::const_iterator>
+equal_range(const multimapt &multimap, const typename multimapt::key_type &key)
+{
+  auto iterator_pair = multimap.equal_range(key);
+  return make_range(iterator_pair.first, iterator_pair.second);
+}
+
 #endif // CPROVER_UTIL_RANGE_H