Re: [PATCH] expand description of poly_int conversions

[Martin Sebor <msebor at gmail dot com>]

On 02/26/2018 12:45 PM, Richard Sandiford wrote:
> Martin Sebor <msebor@gmail.com> writes:
> > Richard,
> >
> > If you agree, I'd like to update the conversion section of
> > the poly_int manual to make the conversion to make it clearer
> > that the to_constant() function can be used even with class
> > types like offset_int besides scalars.
> >
> > Also, when testing this I also tried converting poly64_int
> > into wide_int but that doesn't work.  Is there a way to do
> > that?
>
> Not in one go, because you have to specify the intended precision
> of the wide_int when constructing it from something like HOST_WIDE_INT.
> (That's deliberate.)
>
> > Thanks
> > Martin
> >
> > gcc/ChangeLog:
> >
> > 	* doc/poly-int.texi (is_constant): Expand.
> >
> > Index: gcc/doc/poly-int.texi
> > ===================================================================
> > --- gcc/doc/poly-int.texi	(revision 258004)
> > +++ gcc/doc/poly-int.texi	(working copy)
> > @@ -836,9 +836,24 @@ Return true if @code{poly_int} @var{value} is a co
> >
> >  @item @var{value}.is_constant (&@var{c1})
> >  Return true if @code{poly_int} @var{value} is a compile-time constant,
> > -storing it in @var{c1} if so.  @var{c1} must be able to hold all
> > -constant values of @var{value} without loss of precision.
> > +storing it in @var{c1} if so.  @var{c1} may be a scalar or a wide int
> > +class type capable of holding all constant values of @var{value} without
>
> Not sure about "a scalar or a wide int", since that implies that wide ints
> aren't scalar.  Even more pedantic, sorry, but c1 is an object rather than
> a type.
>
> At a higher level, I'm a bit nervous about singling this out as a special
> case, since all the poly_int stuff allows HOST_WIDE_INT, offset_int and
> wide_int to be combined in the (hopefully) natural way.  E.g. you can
> add offset_ints to poly_int64s, assign HOST_WIDE_INTs to poly_offset_ints,
> and so on.
>
> But if we do keep it like this, how about:
>
>   @var{c1} must be some form of integer object that can hold all constant
>   values of @var{value} without loss of precision; it can be either a normal
>   C++ integer or a wide-int class like @code{offset_int}.
>
> ?

Sure.  Attached is an update with your change.

Martin

gcc/ChangeLog:

	* doc/poly-int.texi (is_constant): Expand.

Index: gcc/doc/poly-int.texi
===================================================================
--- gcc/doc/poly-int.texi	(revision 258004)
+++ gcc/doc/poly-int.texi	(working copy)
@@ -836,8 +836,23 @@ Return true if @code{poly_int} @var{value} is a co
 
 @item @var{value}.is_constant (&@var{c1})
 Return true if @code{poly_int} @var{value} is a compile-time constant,
-storing it in @var{c1} if so.  @var{c1} must be able to hold all
-constant values of @var{value} without loss of precision.
+storing it in @var{c1} if so.  @var{c1} must be some form of integer
+object that can hold all constant values of @var{value} without loss
+of precision; it can be either a normal C++ integer or a wide-int class
+like @code{offset_int}.  The following example illustrates using
+the function to convert a @code{poly_int64} to @code{HOST_WIDE_INT}
+and to @code{offset_int}.
+@smallexample
+void f (poly_int64 pi)
+@{
+  HOST_WIDE_INT hwi;
+  if (pi.is_constant (&hwi))
+    ; // Use hwi...
+  offset_int off;
+  if (pi.is_constant (&off))
+    ; // Use off...
+@}
+@end smallexample
 
 @item @var{value}.to_constant ()
 Assert that @var{value} is a compile-time constant and return its value.