I agree with the idea of adding caveats to the POD for using the set_* methods.
I had a colleague who tried to add 4 days to a DateTime like so:
$dt->set_day($dt->day + 4)
And it worked fine in the beginning of the month.
This is similar to the erroneous use of set_year below.
Of course, no matter how clearly or thoroughly a document is written
there will always be someone that will misread and misuse it.
On Mar 2, 2012, at 12:32 PM, Michael G Schwern wrote:
> On 2012.3.2 11:17 AM, Dave Rolsky wrote:
>> However, I will point out that what you were doing is weird. If you want to
>> do
>> DateTime math, you need to use ->add and ->subtract (although these can
>> _also_
>> come up with invalid datetimes in the face of DST changes). The DST issue is
>> documented pretty clearly in the "How Datetime Math Works" section of the
>> docs.
>
> While there may be a section about DateTime math, there's little in the docs
> about set caveats. It's non-obvious that $dt->set_year( $dt->year + 1 ) is
> significantly different than $dt->add( years => 1 ) or that there's anything
> wrong with using set in that manner. There needs to be a warning or pointer
> in the set docs, because a user has no motivation to fish further.
>
> I'd suggest a section about when to use set_* and when to use add_* and what
> their caveats are. Put pointers to it in the set_* and add_* documentation.
>
>
> --
> 10. Not allowed to purchase anyone's soul on government time.
> -- The 213 Things Skippy Is No Longer Allowed To Do In The U.S. Army
> http://skippyslist.com/list/
