expand description of poly_int conversions

Message ID 8944eea9-f10b-f367-731a-39be7208e9e6@gmail.com
State New
Headers show
Series
  • expand description of poly_int conversions
Related show

Commit Message

Martin Sebor Feb. 26, 2018, 6:08 p.m.
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?

Thanks
Martin

Comments

Richard Sandiford Feb. 26, 2018, 7:45 p.m. | #1
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}.

?

> +loss of precision.  The following example illustrates using the function

> +to convert a @code{poly64_int} to @code{HOST_WIDE_INT} and to

> +@code{offset_int}.

> +@smallexample

> +void f (poly64_int pi)


poly_int64

> +@{

> +  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.

>  When using this function, please add a comment explaining why the


No need for the extra blank line.

Thanks,
Richard
Martin Sebor Feb. 26, 2018, 8:19 p.m. | #2
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.
Richard Sandiford Feb. 26, 2018, 9:09 p.m. | #3
Martin Sebor <msebor@gmail.com> writes:
> 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.


LGTM (but I can't approve).

Thanks,
Richard
Jeff Law Feb. 28, 2018, 11:13 p.m. | #4
On 02/26/2018 02:09 PM, Richard Sandiford wrote:
> Martin Sebor <msebor@gmail.com> writes:

>> 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.

> 

> LGTM (but I can't approve).

That, IMHO, is a technicality :-)  You know these bits better than
anyone.  So if you're OK with them, that's good enough for me :-)

Rubber-stamped for the trunk.


jeff

Patch

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
+loss of precision.  The following example illustrates using the function
+to convert a @code{poly64_int} to @code{HOST_WIDE_INT} and to
+@code{offset_int}.
+@smallexample
+void f (poly64_int 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.
 When using this function, please add a comment explaining why the