c++: prefer 'emplace' to 'build'

[Akim Demaille]

I have also left a few occurrences of build in the test suite.

commit 42f0b949ec06411df2626545c3d195e4b6a9fbdf
Author: Akim Demaille <address@hidden>
Date:   Sat Oct 20 10:32:27 2018 +0200

    c++: prefer 'emplace' to 'build'
    
    When we introduced variants in Bison, C++ did not have the 'emplace'
    functions, and we chose 'build'.  Let's align with modern C++ and
    promote 'emplace' rather than 'build'.
    
    * data/lalr1.cc, data/variant.hh (emplace): New.
    (build): Deprecate in favor of emplace.
    * doc/bison.texi: Adjust.

diff --git a/data/lalr1.cc b/data/lalr1.cc
index 7470ceda..6633cbd2 100644
--- a/data/lalr1.cc
+++ b/data/lalr1.cc
@@ -862,7 +862,7 @@ b4_dollar_popdef])[]dnl
       /* Variants are always initialized to an empty instance of the
          correct type. The default '$$ = $1' action is NOT applied
          when using variants.  */
-      b4_symbol_variant(address@hidden@}]], [yylhs.value], [build])], [
+      b4_symbol_variant(address@hidden@}]], [yylhs.value], [emplace])], [
       /* If YYLEN is nonzero, implement the default value of the
          action: '$$ = $1'.  Otherwise, use the top of the stack.
 
diff --git a/data/variant.hh b/data/variant.hh
index f76d5d7f..089e04fa 100644
--- a/data/variant.hh
+++ b/data/variant.hh
@@ -117,7 +117,7 @@ m4_define([b4_variant_define],
     /// Instantiate an empty \a T in here.
     template <typename T>
     T&
-    build ()
+    emplace ()
     {]b4_parse_assert_if([
       YYASSERT (!yytypeid_);
       YYASSERT (sizeof (T) <= S);
@@ -128,7 +128,7 @@ m4_define([b4_variant_define],
     /// Instantiate a \a T in here from \a t.
     template <typename T>
     T&
-    build (const T& t)
+    emplace (const T& t)
     {]b4_parse_assert_if([
       YYASSERT (!yytypeid_);
       YYASSERT (sizeof (T) <= S);
@@ -136,6 +136,24 @@ m4_define([b4_variant_define],
       return *new (yyas_<T> ()) T (t);
     }
 
+    /// Instantiate an empty \a T in here.
+    /// Obsolete, use emplace.
+    template <typename T>
+    T&
+    build ()
+    {
+      return emplace<T> ();
+    }
+
+    /// Instantiate a \a T in here from \a t.
+    /// Obsolete, use emplace.
+    template <typename T>
+    T&
+    build (const T& t)
+    {
+      return emplace<T> (t);
+    }
+
     /// Accessor to a built \a T.
     template <typename T>
     T&
@@ -182,7 +200,7 @@ m4_define([b4_variant_define],
     void
     move (self_type& other)
     {
-      build<T> ();
+      emplace<T> ();
 # if defined __cplusplus && 201103L <= __cplusplus
       as<T> () = std::move (other.as<T> ());
 # else
@@ -197,7 +215,7 @@ m4_define([b4_variant_define],
     void
     move (self_type&& other)
     {
-      build<T> ();
+      emplace<T> ();
       as<T> () = std::move (other.as<T> ());
       other.destroy<T> ();
     }
@@ -208,7 +226,7 @@ m4_define([b4_variant_define],
     void
     copy (const self_type& other)
     {
-      build<T> (other.as<T> ());
+      emplace<T> (other.as<T> ());
     }
 
     /// Destroy the stored \a T.
diff --git a/doc/bison.texi b/doc/bison.texi
index eda5eb65..fcee42fe 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -10835,12 +10835,12 @@ of alternative types such as @samp{$<int>2} or 
@samp{$<std::string>$}, even
 in midrule actions.  It is mandatory to use typed midrule actions
 (@pxref{Typed Midrule Actions}).
 
address@hidden {semantic_type} {T&} build<T> ()
address@hidden {semantic_type} {T&} emplace<T> ()
 Initialize, but leave empty.  Returns the address where the actual value may
 be stored.  Requires that the variant was not initialized yet.
 @end deftypemethod
 
address@hidden {semantic_type} {T&} build<T> (const T& @var{t})
address@hidden {semantic_type} {T&} emplace<T> (const T& @var{t})
 Initialize, and copy-construct from @var{t}.
 @end deftypemethod
 
@@ -11166,11 +11166,11 @@ initialized.  So the code would look like:
 
 @example
 [0-9]+   @{
-           yylval->build<int> () = text_to_int (yytext);
+           yylval->emplace<int> () = text_to_int (yytext);
            return yy::parser::token::INTEGER;
          @}
 [a-z]+   @{
-           yylval->build<std::string> () = yytext;
+           yylval->emplace<std::string> () = yytext;
            return yy::parser::token::IDENTIFIER;
          @}
 @end example
@@ -11180,11 +11180,11 @@ or
 
 @example
 [0-9]+   @{
-           yylval->build (text_to_int (yytext));
+           yylval->emplace (text_to_int (yytext));
            return yy::parser::token::INTEGER;
          @}
 [a-z]+   @{
-           yylval->build (yytext);
+           yylval->emplace (yytext);
            return yy::parser::token::IDENTIFIER;
          @}
 @end example