[ast] Allow for VarDecls to have a Parent back pointer that points at a different var decl.

I did not wire anything up to it.

This is in preparation for fixing issues around SILGenPattern fallthrough
emission and bad rename/edit all in scope of case stmt var decls. Specifically,
I am going to ensure that we can get from any VarDecl in the following to any
other VarDecl:

switch x {
case .a(let v1, let v2), .b(let v1, let v2):
  ...
  fallthrough
case .c(let v1, let v2), .d(let v1, let v2):
  ...
}

This will be done by:

1. Pointing the var decls in .d at the corresponding var decls in .c.
2. Pointing the var decls in .c at the corresponding var decls in .b.
3. Pointing the var decls in .b at the corresponding var decls in .a.
4. Pointing the var decls in .a at the case stmt. Recognizing that we are asking
for the next VarDecl, but have a case stmt, we check if we have a fallthrough
case stmt (which I am going to add in a subsequent commit). If so, follow down
the fallthrough case stmts until you find a fallthrough case stmt that doesn't
fallthrough itself and then return the corresponding var decl in the last case
label item in that var decl (in the above .d).

I also put in some asserts to make sure that we never try to vend a parent value
that is a nullptr.

rdar://47467128

Author: gottesmm

include/swift/AST/Decl.h

@@ -4577,7 +4577,7 @@ class VarDecl : public AbstractStorageDecl {
   };
 
 protected:
-  llvm::PointerUnion<PatternBindingDecl*, Stmt*> ParentPattern;
+  PointerUnion3<PatternBindingDecl *, Stmt *, VarDecl *> Parent;
 
   VarDecl(DeclKind Kind, bool IsStatic, Specifier Sp, bool IsCaptureList,
           SourceLoc NameLoc, Identifier Name, DeclContext *DC)
@@ -4648,12 +4648,15 @@ class VarDecl : public AbstractStorageDecl {
   /// Return the parent pattern binding that may provide an initializer for this
   /// VarDecl.  This returns null if there is none associated with the VarDecl.
   PatternBindingDecl *getParentPatternBinding() const {
-    return ParentPattern.dyn_cast<PatternBindingDecl *>();
+    if (!Parent)
+      return nullptr;
+    return Parent.dyn_cast<PatternBindingDecl *>();
   }
   void setParentPatternBinding(PatternBindingDecl *PBD) {
-    ParentPattern = PBD;
+    assert(PBD);
+    Parent = PBD;
   }
-  
+
   /// Return the Pattern involved in initializing this VarDecl.  However, recall
   /// that the Pattern may be involved in initializing more than just this one
   /// vardecl.  For example, if this is a VarDecl for "x", the pattern may be
@@ -4668,10 +4671,28 @@ class VarDecl : public AbstractStorageDecl {
   /// Return the statement that owns the pattern associated with this VarDecl,
   /// if one exists.
   Stmt *getParentPatternStmt() const {
-    return ParentPattern.dyn_cast<Stmt*>();
+    if (!Parent)
+      return nullptr;
+    return Parent.dyn_cast<Stmt *>();
+  }
+  void setParentPatternStmt(Stmt *s) {
+    assert(s);
+    Parent = s;
   }
-  void setParentPatternStmt(Stmt *S) {
-    ParentPattern = S;
+
+  /// Returns the var decl that this var decl is an implicit reference to if
+  /// such a var decl exists.
+  VarDecl *getParentVarDecl() const {
+    if (!Parent)
+      return nullptr;
+    return Parent.dyn_cast<VarDecl *>();
+  }
+
+  /// Set \p v to be the pattern produced VarDecl that is the parent of this
+  /// var decl.
+  void setParentVarDecl(VarDecl *v) {
+    assert(v);
+    Parent = v;
   }
 
   /// True if the global stored property requires lazy initialization.

include/swift/Basic/LLVM.h

@@ -43,6 +43,7 @@ namespace llvm {
   template<typename T> class TinyPtrVector;
   template<typename T> class Optional;
   template <typename PT1, typename PT2> class PointerUnion;
+  template <typename PT1, typename PT2, typename PT3> class PointerUnion3;
   class SmallBitVector;
 
   // Other common classes.
@@ -62,22 +63,23 @@ namespace swift {
   using llvm::cast_or_null;
 
   // Containers.
+  using llvm::ArrayRef;
+  using llvm::MutableArrayRef;
   using llvm::None;
   using llvm::Optional;
-  using llvm::SmallPtrSetImpl;
+  using llvm::PointerUnion;
+  using llvm::PointerUnion3;
+  using llvm::SmallBitVector;
   using llvm::SmallPtrSet;
+  using llvm::SmallPtrSetImpl;
+  using llvm::SmallSetVector;
   using llvm::SmallString;
-  using llvm::StringRef;
-  using llvm::StringLiteral;
-  using llvm::Twine;
-  using llvm::SmallVectorImpl;
   using llvm::SmallVector;
-  using llvm::ArrayRef;
-  using llvm::MutableArrayRef;
+  using llvm::SmallVectorImpl;
+  using llvm::StringLiteral;
+  using llvm::StringRef;
   using llvm::TinyPtrVector;
-  using llvm::PointerUnion;
-  using llvm::SmallSetVector;
-  using llvm::SmallBitVector;
+  using llvm::Twine;
 
   // Other common classes.
   using llvm::APFloat;