%template scope enforcement and class definition fixes

The scoping rules around %template have been specified and enforced.
The %template directive for a class template is the equivalent to an
explicit instantiation of a C++ class template. The scope for a valid
%template instantiation is now the same as the scope required for a
valid explicit instantiation of a C++ template. A definition of the
template for the explicit instantiation must be in scope where the
instantiation is declared and must not be enclosed within a different
namespace.

For example, a few %template and explicit instantiations of std::vector
are shown below:

  // valid
  namespace std {
    %template(vin) vector<int>;
    template class vector<int>;
  }

  // valid
  using namespace std;
  %template(vin) vector<int>;
  template class vector<int>;

  // valid
  using std::vector;
  %template(vin) vector<int>;
  template class vector<int>;

  // ill-formed
  namespace unrelated {
    using std::vector;
    %template(vin) vector<int>;
    template class vector<int>;
  }

  // ill-formed
  namespace unrelated {
    using namespace std;
    %template(vin) vector<int>;
    template class vector<int>;
  }

  // ill-formed
  namespace unrelated {
    namespace std {
      %template(vin) vector<int>;
      template class vector<int>;
    }
  }

  // ill-formed
  namespace unrelated {
    %template(vin) std::vector<int>;
    template class std::vector<int>;
  }

When the scope is incorrect, an error now occurs such as:

cpp_template_scope.i:34: Error: 'vector' resolves to 'std::vector' and
was incorrectly instantiated in scope 'unrelated' instead of within scope 'std'.

Previously SWIG accepted the ill-formed examples above but this led to
numerous subtle template scope problems especially in the presence of
using declarations and using directives as well as with %feature and %typemap.

Actually, a valid instantiation is one which conforms to the C++03
standard as C++11 made a change to disallow using declarations and
using directives to find a template.

  // valid C++03, ill-formed C++11
  using std::vector;
  template class vector<int>;

Similar fixes for defining classes using forward class references have
also been put in place. For example:

namespace Space1 {
  struct A;
}
namespace Space2 {
  struct Space1::A {
    void x();
  }
}

will now error out with:

cpp_class_definition.i:5: Error: 'Space1::A' resolves to 'Space1::A' and
was incorrectly instantiated in scope 'Space2' instead of within scope 'Space1'.

Source/Swig/misc.c

@@ -823,10 +823,11 @@ String *Swig_string_emangle(String *s) {
 
 
 /* -----------------------------------------------------------------------------
- * Swig_scopename_prefix()
+ * Swig_scopename_split()
  *
- * Take a qualified name like "A::B::C" and return the scope name.
- * In this case, "A::B".   Returns NULL if there is no base.
+ * Take a qualified name like "A::B::C" and splits off the last name.
+ * In this case, returns "C" as last and "A::B" as prefix.
+ * Always returns non NULL for last, but prefix may be NULL if there is no prefix.
  * ----------------------------------------------------------------------------- */
 
 void Swig_scopename_split(const String *s, String **rprefix, String **rlast) {
@@ -882,6 +883,12 @@ void Swig_scopename_split(const String *s, String **rprefix, String **rlast) {
   }
 }
 
+/* -----------------------------------------------------------------------------
+ * Swig_scopename_prefix()
+ *
+ * Take a qualified name like "A::B::C" and return the scope name.
+ * In this case, "A::B".   Returns NULL if there is no base.
+ * ----------------------------------------------------------------------------- */
 
 String *Swig_scopename_prefix(const String *s) {
   char *tmp = Char(s);
@@ -1067,6 +1074,31 @@ String *Swig_scopename_suffix(const String *s) {
   }
 }
 
+/* -----------------------------------------------------------------------------
+ * Swig_scopename_tolist()
+ *
+ * Take a qualified scope name like "A::B::C" and convert it to a list.
+ * In this case, return a list of 3 elements "A", "B", "C".
+ * Returns an empty list if the input is empty.
+ * ----------------------------------------------------------------------------- */
+
+List *Swig_scopename_tolist(const String *s) {
+  List *scopes = NewList();
+  String *name = Len(s) == 0 ? 0 : NewString(s);
+
+  while (name) {
+    String *last = 0;
+    String *prefix = 0;
+    Swig_scopename_split(name, &prefix, &last);
+    Insert(scopes, 0, last);
+    Delete(last);
+    Delete(name);
+    name = prefix;
+  }
+  Delete(name);
+  return scopes;
+}
+
 /* -----------------------------------------------------------------------------
  * Swig_scopename_check()
  *

Source/Swig/swig.h

@@ -326,6 +326,7 @@ extern int        ParmList_is_compactdefargs(ParmList *p);
   extern String *Swig_scopename_last(const String *s);
   extern String *Swig_scopename_first(const String *s);
   extern String *Swig_scopename_suffix(const String *s);
+  extern List *Swig_scopename_tolist(const String *s);
   extern int Swig_scopename_check(const String *s);
   extern String *Swig_string_lower(String *s);
   extern String *Swig_string_upper(String *s);