tracker issue | What iT iS dESign studios

Title:

Add granularity to createDateTime()

| View in Tracker

Status/Resolution/Reason: Closed/Fixed/

Reporter/Name(from Bugbase): Adam Cameron / Adam Cameron (Adam Cameron)

Created: 11/29/2012

Components: Language

Versions: 10.0

Failure Type: Enhancement Request

Found In Build/Fixed In Build: Final /

Priority/Frequency: Trivial / Unknown

Locale/System: English / Platforms All

Vote Count: 1

Listed in the version 2016.0.0.297996 Issues Fixed doc

Verification notes: verified_fixed on March 11, 2016 using build 2016.0.01.298513

It would be good if createDateTime() was "overloaded" with variations as follows:

justYearWasSet = createDateTime(2012); // all other components use either now() or 0/1 as most appropriate (probably the former)
monthWasSetToo = createDateTime(2012, 11);
dayWasSetToo = createDateTime(2012, 11, 29);
hourWasSetToo = createDateTime(2012, 11, 29, 15);
minWasSetToo = createDateTime(2012, 11, 29, 15, 7);

Better yet would be able to do this:

monthWasSet = createDateTime(month=11);
dayWasSet = createDateTime(day=29);

Often I have a date/time which is mostly correct, but I want to change just the month and the day, or the hour and the minute or something.

This can be worked-around with dateAdd(), but it's clumsy and masks the intent of the code. It'd be better to just be able to set the individual components.

Better still, would be able to do this:
myDate.setYear(2012) (with setMonth() setDay(), etc)

This would be at odds with the rest of CFML's function(object, args) approach, but perhaps it's time for CFML to move on from that (as a bigger body of work).

-- 
Adam

----------------------------- Additional Watson Details -----------------------------

Watson Bug ID:	3374275

External Customer Info:
External Company:  
External Customer Name: Adam Cameron.
External Customer Email:  
External Test Config: My Hardware and Environment details:

Attachments:

Comments:

1) adding member functions setYear(), setMonth(), setHour(), setMinute(), setSecond() for a date object
2) adding following additional createDateTime() functions
    YearWasSet = createDateTime(2012); // all other components use 0/1 as most appropriate
    monthWasSetToo = createDateTime(2012, 11);
    dayWasSetToo = createDateTime(2012, 11, 29);
    hourWasSetToo = createDateTime(2012, 11, 29, 15);
    minWasSetToo = createDateTime(2012, 11, 29, 15, 7);

Comment by Nikhil S.

17073 | October 26, 2015 09:08:34 AM GMT

Excellent! Thanks!

Comment by External U.

17074 | October 26, 2015 09:16:59 AM GMT

But please do *not* add those functions as procedural ones: they just add clutter. Just add them as object methods.

Comment by External U.

17075 | October 26, 2015 09:17:57 AM GMT

added the member function setDayOfMonth()

Comment by Nikhil S.

17076 | October 27, 2015 01:05:27 AM GMT

+1 ...................... now to add support for milliseconds :)

Vote by External U.

17098 | December 05, 2015 01:00:01 AM GMT

Why setDayOfMonth() instead of following the precedent set by all the other methods, and have setDay()? This - barring a decent rationalisation from you, Nikhil - is an implementation bug IMO.

Comment by External U.

17077 | December 08, 2015 04:07:00 AM GMT

Hi Nikhil,

+1 to what Adam said. It should be simply setDay().

Thanks!,
-Aaron

Comment by External U.

17078 | December 08, 2015 04:17:14 AM GMT

changed setDayOfMonth() to setDay()

Comment by Nikhil S.

17079 | December 11, 2015 04:35:23 AM GMT

Hi Nikhil,

Can setMillisecond() also be added?

Thanks!,
-Aaron

Comment by External U.

17080 | December 11, 2015 05:26:00 AM GMT

What would additionally be handy here is to have a variation:

DateTime createDateTime(Struct parts)

Where the parts argument is a struct which can have any combination of year, month, day, hour, minute, second, millisecond.

Comment by External U.

17081 | December 15, 2015 02:52:29 AM GMT

Hi Adam,

+1 to that!

Thanks,
-Aaron

Comment by External U.

17082 | December 15, 2015 03:48:43 AM GMT

Aaron,
Can you please raise a separate ER for setMillisecond method.

On another note, we are considering changing the name of the setHour, setMinute, setSecond to setHours, setMinutes and setSeconds respectively,

Comment by Piyush K.

17083 | December 15, 2015 09:02:17 AM GMT

Hi Piyush,

Sure, I'll log an ER.

When referring to timestamp parts, we say "the year", "the month", "the day", "the hour", "the minute". But I guess we say "the seconds" and "the milliseconds". Maybe just [.]setSeconds() and [.]setMilliseconds() and the rest be singular? I dunno; I'd like to hear other opinions too.

Perhaps this question can be raised in the PR forum to gather more opinions? I can create the thread unless you want to, or unless Adam wants to since this is his ticket. I think we need more opinions from developers.

Thanks!,
-Aaron

Comment by External U.

17084 | December 15, 2015 08:08:08 PM GMT

> On another note, we are considering changing the name of the setHour, setMinute, setSecond to setHours, setMinutes and setSeconds respectively,

What prompted that decision? Are you saying you're implementing setYear() (singular) but setHours() plural?

I see that JS follows this mishmash, and java.util.Date used to, but Java's got its act together with Calendar and standardises on singular (albeit the implementation is slightly different, but the parallel still applies I think).

Comment by External U.

17085 | December 16, 2015 03:11:04 AM GMT

Set the millisecond/second/minute/hour/day/week/year value to ()... should all be singular (IMO)

Comment by External U.

17086 | December 16, 2015 06:42:22 AM GMT

I'd prefer all singular as well. The mishmash doesn't quite sit right. Especially since second() already exists in the language.

Thanks!,
-Aaron

Comment by External U.

17087 | December 16, 2015 09:45:46 AM GMT

Hi Piyush,

Could setMillisecond() please be considered part of CF-3429713?

I've added a comment asking if that ticket's title can be changed.

Thanks!,
-Aaron

Comment by External U.

17088 | December 16, 2015 09:48:00 AM GMT

For modifying a date object, keep the names singular!
DateObj.setHour(Number) = good
DateObj.setHours(Number) = bad

Plural does make sense in other situations:
DateObj.getHoursSince(DateObj) = good
DateObj.getHourSince(DateObj) = bad

But for the basic set/get functions, singular is consistent and correct.

Comment by External U.

17089 | December 16, 2015 10:05:41 AM GMT

I can't edit, so I'll repost with corrections...

For modifying a date object, keep the names singular!
DateObj.setHour(Number) = good
DateObj.setHours(Number) = bad

Plural does make sense in other situations:
DateObj.getHoursSince(OtherDateObj) = good
DateObj.getHourSince(OtherDateObj) = bad

(that's a made up method to indicate this point)

But for the basic set/get functions, singular is consistent and correct.

Comment by External U.

17090 | December 16, 2015 10:07:18 AM GMT

I prefer Date to be immutable.  I am not a fan of having setters on a date object.  Having add() method that returns a new Date object is fine.

Comment by External U.

17091 | December 16, 2015 01:52:57 PM GMT

I surveyed the community, and got 50 responses. This is hardly statistically meaningful, but the trend was clear: most people prefer the conformity of keeping all these methods singular.

http://blog.adamcameron.me/2015/12/survey-results-singular-or-plural-for.html

Comment by External U.

17092 | December 18, 2015 02:59:21 PM GMT

When's this scheduled for release?

Comment by External U.

17093 | February 25, 2016 07:01:44 AM GMT

Hi Adam,

It looks like this is fixed in CF2016 final? Here's what I ran:

<cfscript>
  foo=[];
  foo.append(createDateTime(2012));
  foo.append(createDateTime(2012, 11));
  foo.append(createDateTime(2012, 11, 29));
  foo.append(createDateTime(2012, 11, 29, 15));
  foo.append(createDateTime(2012, 11, 29, 15, 7));
  foo.append(createDateTime(2012, 11, 29, 15, 7, 8));
  //foo.append(createDateTime(2012, 11, 29, 15, 7, 8, 9));//throws "The function accepts 1 to 6 parameters." :/
  writeDump(var=foo, format="text");
</cfscript>

Result:

-----------
array

1) {ts '2012-01-01 00:00:00'} 
2) {ts '2012-11-01 00:00:00'} 
3) {ts '2012-11-29 00:00:00'} 
4) {ts '2012-11-29 15:00:00'} 
5) {ts '2012-11-29 15:07:00'} 
6) {ts '2012-11-29 15:07:08'} 
-----------

<cfscript>
  bar = now();
  bar.setYear(2011);
  bar.setMonth(1);
  bar.setDay(1);
  bar.setHour(1);
  bar.setMinute(1);
  bar.setSecond(1);
  //bar.setMillisecond(0);//throws "The setMillisecond method was not found." :/
  writeOutput(bar.dateTimeFormat("yyyymmdd HH:nn:ss:l"));
</cfscript>

Result:

-----------
20110101 01:01:01:487
-----------

I guess Adobe needs to populate the "Fixed In Build". Adobe, please?

Thanks!,
-Aaron

Comment by External U.

17094 | March 11, 2016 01:54:14 PM GMT

Hi Adam,

Ah, I see they didn't implement the following (which I've previously +1'd BTW):

-----------
What would additionally be handy here is to have a variation:

DateTime createDateTime(Struct parts)

Where the parts argument is a struct which can have any combination of year, month, day, hour, minute, second, millisecond. 
-----------

I agree that'd be handy.

Thanks!,
-Aaron

Comment by External U.

17095 | March 11, 2016 01:57:53 PM GMT

And update the docs, which do not mention any of this.

As docs are part of enhancement implementation, I don't consider this "fixed" yet. Should be reopened until the docs are done.

Cheers for the research, Aaron.

Comment by External U.

17096 | March 11, 2016 01:58:23 PM GMT

Hi Adam,

You're very welcome! Sorry, I just now saw your message. Not sure how I missed it. Also, I now see the following docs were updated:

CreateDateTime(): https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-c-d/CreateDateTime.html

Using the member functions: https://helpx.adobe.com/coldfusion/developing-applications/building-blocks-of-coldfusion-applications/using-the-member-functions.html

Thanks!,
-Aaron

Comment by External U.

17097 | March 26, 2016 10:05:12 PM GMT

Hi all,

`myDateTime.setYear(2018)` mutates myDateTime. This is bad b/c CF treats strings as date-time whenever possible.

Let's say an array is set earlier in the code:

<cfset myArray = ["1/1/2017","2/1/2017"]>

….then, somewhere later in the code (even within another .cfm or .cfc or UDF body), the array is used:

<cfscript>
  for(stringDate in myArray) {
      writeOutput(stringDate.setYear(2018))
  }
  writeDump(myArray)
</cfscript>

Then, in future, that 1st line is changed to: `<myArray = [createDateTime(2017,1),createDateTime(2017,2)]>` and then the other code starts breaking.

Then, we hear: "my code used to work, why doesn't it work no more??"

See?

Date-time must be immutable.

Thanks!,
-Aaron

Comment by Aaron N.

29859 | October 27, 2018 02:46:42 AM GMT

Please see ticket https://tracker.adobe.com/#/view/CF-4199892

Comment by Aaron N.

29860 | October 27, 2018 02:47:01 AM GMT

I retract the 2nd half of my 03/11/2016 13:54:14 GMT comment.

Comment by Aaron N.

29861 | October 27, 2018 02:48:28 AM GMT

tracker issue : CF-3374275

Add granularity to createDateTime()