diff mbox series

[PATCH/doc] correct cast to a union description (PR 89106)

Message ID 239aaab6-a3d3-c6b2-288b-27587a225142@gmail.com
State New
Headers show
Series [PATCH/doc] correct cast to a union description (PR 89106) | expand

Commit Message

Martin Sebor Jan. 31, 2019, 12:25 a.m. UTC 
A change I made a couple of years ago to the Cast To a Union section
of the manual incorrectly stated that the cast yields an lvalue when
it, in fact, yields an rvalue.  The attached patch corrects this
mistake and expands the description to further clarify the construct
based on a discussion with Alexander in the PR.

Martin

Comments

Joseph Myers Jan. 31, 2019, 1:37 a.m. UTC | #1 
On Wed, 30 Jan 2019, Martin Sebor wrote:

> A change I made a couple of years ago to the Cast To a Union section
> of the manual incorrectly stated that the cast yields an lvalue when
> it, in fact, yields an rvalue.  The attached patch corrects this
> mistake and expands the description to further clarify the construct
> based on a discussion with Alexander in the PR.

OK.
diff mbox series

Patch

PR other/89106 - cast-to-union documentation incorrect w.r.t. lvalueness

gcc/ChangeLog:

	PR other/89106
	* doc/extend.texi (cast to a union): Correct and expand.

Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi	(revision 268398)
+++ gcc/doc/extend.texi	(working copy)
@@ -2275,27 +2275,46 @@  case 1...5:
 @cindex cast to a union
 @cindex union, casting to a
 
-A cast to union type looks similar to other casts, except that the type
-specified is a union type.  You can specify the type either with the
-@code{union} keyword or with a @code{typedef} name that refers to
-a union.  A cast to a union actually creates a compound literal and
-yields an lvalue, not an rvalue like true casts do.
+A cast to a union type is a C extension not available in C++.  It looks
+just like ordinary casts with the constraint that the type specified is
+a union type.  You can specify the type either with the @code{union}
+keyword or with a @code{typedef} name that refers to a union.  The result
+of a cast to a union is a temporary rvalue of the union type with a member
+whose type matches that of the operand initialized to the value of
+the operand.  The effect of a cast to a union is similar to a compound
+literal except that it yields an rvalue like standard casts do.
 @xref{Compound Literals}.
 
-The types that may be cast to the union type are those of the members
-of the union.  Thus, given the following union and variables:
+Expressions that may be cast to the union type are those whose type matches
+at least one of the members of the union.  Thus, given the following union
+and variables:
 
 @smallexample
 union foo @{ int i; double d; @};
 int x;
 double y;
+union foo z;
 @end smallexample
 
 @noindent
-both @code{x} and @code{y} can be cast to type @code{union foo}.
+both @code{x} and @code{y} can be cast to type @code{union foo} and
+the following assignments
+@smallexample
+  z = (union foo) x;
+  z = (union foo) y;
+@end smallexample
+are shorthand equivalents of these
+@smallexample
+  z = (union foo) @{ .i = x @};
+  z = (union foo) @{ .d = y @};
+@end smallexample
 
+However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
+has no member of type @code{float}.
+
 Using the cast as the right-hand side of an assignment to a variable of
-union type is equivalent to storing in a member of the union:
+union type is equivalent to storing in a member of the union with
+the same type
 
 @smallexample
 union foo u;