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.

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([[yyr1_@{yyn@}]], [yylhs.value], [build])], [
+      b4_symbol_variant([[yyr1_@{yyn@}]], [yylhs.value], [emplace])], [
       /* If YYLEN is nonzero, implement the default value of the
          action: '$$ = $1'.  Otherwise, use the top of the stack.
 

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.

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}).
 
-@deftypemethod {semantic_type} {T&} build<T> ()
+@deftypemethod {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
 
-@deftypemethod {semantic_type} {T&} build<T> (const T& @var{t})
+@deftypemethod {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