www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - how to migrate to std.datetime

reply Adam D. Ruppe <destructionator gmail.com> writes:
I decided to update my compiler today, and regret it for a lot of
reasons, but meh.

One of the things is std.datetime. A lot of my code uses std.date. It
works very, very well for me and I like it.

But, the compile process is nagging me about it. I want it to shut up.


However, I'm not even sure where to start with std.datetime...

Which one of it's functions does the same as std.date.getUTCtime()?

It looks like sysTimeToDTime is almost sorta kinda related, but it's
got that same ugly deprecation text.

sysTimeToDTime(Clock.currTime(UTC())); // best we can do?


Note that it's important to me that the numbers match up - I have
some stored and comparisons need to work the same way.

What about std.date.toUTCString()? There's a lot of toBlahString
in there, but none seem to match up.

Another thing it's bitching at me about is std.file.lastModifed. I
just want to check the file's age. With the old function, this is
simple subtraction. How can I ask the new system "is this file
greater than 8 hours old?"


Last question: my app handles timezones on it's own by means of
addition and subtraction of offsets against the getUTCtime() result.
(it's a web app that fetches the offset from javascript so the server
knows what the user's local time is relative to it's internal
representation).

std.date was pretty timezone agnostic.

It looks like the DateTime doesn't mess around with them, so as
long as I always ask for things in UTC, shouldn't be a problem, right?


There's some more, but I think I can make the rest work with
DateTimes by multiplying the numbers before input.
May 08 2011
next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On 2011-05-08 17:46, Adam D. Ruppe wrote:

 I decided to update my compiler today, and regret it for a lot of
 reasons, but meh.
 
 One of the things is std.datetime. A lot of my code uses std.date. It
 works very, very well for me and I like it.
 
 But, the compile process is nagging me about it. I want it to shut up.


Well, std.date is going away. While it may work for what you've been doing, 
it's highly buggy.


 However, I'm not even sure where to start with std.datetime...


Well, it is true that it doesn't function anything like std.date.


 Which one of it's functions does the same as std.date.getUTCtime()?
 
 It looks like sysTimeToDTime is almost sorta kinda related, but it's
 got that same ugly deprecation text.
 
 sysTimeToDTime(Clock.currTime(UTC())); // best we can do?
 
 
 Note that it's important to me that the numbers match up - I have
 some stored and comparisons need to work the same way.


std.date and the values that it uses (i.e. d_time) are going away entirely. 
sysTimeToDTime is there entirely to ease the transition. Anything that 
std.date it is going to have to be redesigned so that it doesn't, unless you 
want to copy the code to your own project and continue using that.
 

 What about std.date.toUTCString()? There's a lot of toBlahString
 in there, but none seem to match up.
 
 Another thing it's bitching at me about is std.file.lastModifed. I
 just want to check the file's age. With the old function, this is
 simple subtraction. How can I ask the new system "is this file
 greater than 8 hours old?"
 
 
 Last question: my app handles timezones on it's own by means of
 addition and subtraction of offsets against the getUTCtime() result.
 (it's a web app that fetches the offset from javascript so the server
 knows what the user's local time is relative to it's internal
 representation).
 
 std.date was pretty timezone agnostic.
 
 It looks like the DateTime doesn't mess around with them, so as
 long as I always ask for things in UTC, shouldn't be a problem, right?
 
 
 There's some more, but I think I can make the rest work with
 DateTimes by multiplying the numbers before input.


Okay. Basic overiew.

Date: Represents a date of the year. It holds a year, month, and day 
internally. It has no relation to time zones.

TimeOfDay: Represents a time of day. It holds an hour, minute, and second 
internally. It has no relation to time zones.

DateTime: Represents a specific time of day on a specific day of the year. It 
holds a Date and TimeOfDay internally. It has no relation to time zones.

SysTime: Represents a specific date and time like DateTime does, except it 
holds it internally in hecto-nanoseconds (100ns) from midnight January 1st, 1 
A.D. (rather than holding the pieces of the date and time separately), and it 
_does_ care about time zone. It also has precision up to hecto-nanoseconds 
whereas DateTime only goes to the second.

Date, TimeOfDay, and DateTime are meant to handle basic calendar-based 
operations where you don't care about the time zone. SysTime is intended for 
dealing with the system time, and it incorporates time zones. You can convert 
between SysTime and the other types (SysTime will cast to the other types, and 
it'll take the other types in its constructors), but you do risk problems with 
DST when converting from the other types to SysTime due to the fact that one 
hour of the year exists twice and another doesn't exist at all due to DST 
changes. But unfortunately, that's unavoidable. The only way to avoid the 
problem entirely is to keep times internally in UTC at all times (which 
SysTime does), though if the Date, TimeOfDay, or DateTime that you're 
constructing a SysTime from represents a time in UTC, and you give it UTC as 
its time zone, then you don't have that problem, since UTC doesn't have DST.

What you want to use is almost certainly SysTime. Clock.currTime() returns a 
SysTime with the current time in the local time zone. Clock.currTime(UTC()) 
returns a SysTime with the current time in UTC. If you give it another 
TimeZone object, it gives the current time in whatever time zone that object 
represents. SysTime always holds the time internally in UTC and converts to 
its time zone when queried for values such as its year or day, or when you do 
something like convert it to a string.

The way that I would write the time out would be to use SysTime and either 
have it in UTC already or call toUTC on it to get one in UTC, and then call 
its toISOExtString (it was toISOExtendedString until dmd 2.053) function to 
convert it to a string to write it out. When reading it in again, I'd then use 
SysTime's fromISOExtString. You could just write it and read it with its time 
zone being in the local time, but then that loses the time zone.

If you have a time in UTC with its time zone as numbers representing its 
offset from UTC and DST, you could use SimpleTimeZone. It just has the offset 
from UTC though, since it has no way of knowing when DST applies, so you would 
have to add/subtract its DST offset to it if DST was in effect.

I really don't know what the best way to handle time is for your particular 
application, since I'm not familiar with it. But the way that std.datetime 
would handle it best would be to use either ISO or ISO Extendend strings, 
which are obviously standard, since they're ISO. It really is _not_ meant to 
do things the C way and have a number that you're passing around. You _can_ 
get at a SysTime's internal representation (of hnsecs since midnight, January 
1st 1 A.D.) by calling its stdTime function if you really want a number. The 
unixTime function will also give you a number by giving you a time_t like 
you'd have in C. sysTimeToDTime converts a SysTime to a d_time, so it'll give 
you what you've been using, but since d_time is going away along with 
std.date, sysTimeToDTime will be going away as well.

Really, you're either going to have to convert your program to deal with time 
the way that std.datetime does, or you're going to have to worry about 
converting a SysTime or DateTime or whatever you want to use in std.datetime 
to whatever representation you want to use in your program.

As for the functions in std.file, new functions were required in order to 
avoid breaking old code. So, it's now timeLastModified instead of 
lastModified. lastModified still returns a d_time and will be around until 
std.date is gone. timeLastModified returns a SysTime. SysTimes can be compared 
by simply comparing them as you would any number. If you want to ask whether 
one is at least 8 hours older than another, you would do that in one of two 
ways.

auto diff = sysTime2 - sysTime1;
auto olderByAtLeast8Hours = diff >= dur!"hours"(8);

or

auto olderByAtLeast8Hours = sysTime2 > sysTime1 + dur!"hours"(8);

dur!"hours"(8) creates a core.time.Duration of 8 hours. Subtracting one 
SysTime from another (or Date, TimeOfDay, or Datetime from another value of 
the same type) results in a core.time.Duration. And you can add or subtract a 
Duration from a Date, TimeOfDay, DateTime, or SysTime.

So, you'll probably want to use SysTime, but you can use DateTime if you want. 
You can even add or subtract the appopriate minutes or hours for UTC and DST 
offsets to/from a DateTime if you want to handle it that way. e.g.

auto utcOffset = dur!"hours"(8);
auto dstOffset = dur!"minutes(60);
auto adjusted = dt + utcOffset - dstOffset;

So, whatever the best way to handle dates and times in your program is going 
to depend on what your program is doing and how you want to adjust it. But 
d_time and std.date are going away. The values that they use will no longer be 
used by Phobos or be present in Phobos at all. std.datetime is how dates and 
times will be handled. So, you really should get used to dealing with 
std.datetime unless you want to be dealing with the date and time stuff 
yourself. I can understand if there may be some migration issues in programs 
which use std.date, but std.date is definitely buggy (even if it works for 
what you've been doing), and it's going away.

- Jonathan M Davis
May 08 2011
parent reply "Nick Sabalausky" <a a.a> writes:
"Jonathan M Davis" <jmdavisProg gmx.com> wrote in message 
news:mailman.74.1304905547.14074.digitalmars-d-learn puremagic.com...

 On 2011-05-08 17:46, Adam D. Ruppe wrote:

 I decided to update my compiler today, and regret it for a lot of
 reasons, but meh.

 One of the things is std.datetime. A lot of my code uses std.date. It
 works very, very well for me and I like it.

 But, the compile process is nagging me about it. I want it to shut up.


 Well, std.date is going away. While it may work for what you've been 
 doing,
 it's highly buggy.


 However, I'm not even sure where to start with std.datetime...


 Well, it is true that it doesn't function anything like std.date.


 Which one of it's functions does the same as std.date.getUTCtime()?

 It looks like sysTimeToDTime is almost sorta kinda related, but it's
 got that same ugly deprecation text.

 sysTimeToDTime(Clock.currTime(UTC())); // best we can do?


 Note that it's important to me that the numbers match up - I have
 some stored and comparisons need to work the same way.


 std.date and the values that it uses (i.e. d_time) are going away 
 entirely.
 sysTimeToDTime is there entirely to ease the transition. Anything that
 std.date it is going to have to be redesigned so that it doesn't, unless 
 you
 want to copy the code to your own project and continue using that.


 What about std.date.toUTCString()? There's a lot of toBlahString
 in there, but none seem to match up.

 Another thing it's bitching at me about is std.file.lastModifed. I
 just want to check the file's age. With the old function, this is
 simple subtraction. How can I ask the new system "is this file
 greater than 8 hours old?"


 Last question: my app handles timezones on it's own by means of
 addition and subtraction of offsets against the getUTCtime() result.
 (it's a web app that fetches the offset from javascript so the server
 knows what the user's local time is relative to it's internal
 representation).

 std.date was pretty timezone agnostic.

 It looks like the DateTime doesn't mess around with them, so as
 long as I always ask for things in UTC, shouldn't be a problem, right?


 There's some more, but I think I can make the rest work with
 DateTimes by multiplying the numbers before input.


 Okay. Basic overiew.

 Date: Represents a date of the year. It holds a year, month, and day
 internally. It has no relation to time zones.

 TimeOfDay: Represents a time of day. It holds an hour, minute, and second
 internally. It has no relation to time zones.

 DateTime: Represents a specific time of day on a specific day of the year. 
 It
 holds a Date and TimeOfDay internally. It has no relation to time zones.

 SysTime: Represents a specific date and time like DateTime does, except it
 holds it internally in hecto-nanoseconds (100ns) from midnight January 
 1st, 1
 A.D. (rather than holding the pieces of the date and time separately), and 
 it
 _does_ care about time zone. It also has precision up to hecto-nanoseconds
 whereas DateTime only goes to the second.

 Date, TimeOfDay, and DateTime are meant to handle basic calendar-based
 operations where you don't care about the time zone. SysTime is intended 
 for
 dealing with the system time, and it incorporates time zones. You can 
 convert
 between SysTime and the other types (SysTime will cast to the other types, 
 and
 it'll take the other types in its constructors), but you do risk problems 
 with
 DST when converting from the other types to SysTime due to the fact that 
 one
 hour of the year exists twice and another doesn't exist at all due to DST
 changes. But unfortunately, that's unavoidable. The only way to avoid the
 problem entirely is to keep times internally in UTC at all times (which
 SysTime does), though if the Date, TimeOfDay, or DateTime that you're
 constructing a SysTime from represents a time in UTC, and you give it UTC 
 as
 its time zone, then you don't have that problem, since UTC doesn't have 
 DST.

 What you want to use is almost certainly SysTime. Clock.currTime() returns 
 a
 SysTime with the current time in the local time zone. 
 Clock.currTime(UTC())
 returns a SysTime with the current time in UTC. If you give it another
 TimeZone object, it gives the current time in whatever time zone that 
 object
 represents. SysTime always holds the time internally in UTC and converts 
 to
 its time zone when queried for values such as its year or day, or when you 
 do
 something like convert it to a string.

 The way that I would write the time out would be to use SysTime and either
 have it in UTC already or call toUTC on it to get one in UTC, and then 
 call
 its toISOExtString (it was toISOExtendedString until dmd 2.053) function 
 to
 convert it to a string to write it out. When reading it in again, I'd then 
 use
 SysTime's fromISOExtString. You could just write it and read it with its 
 time
 zone being in the local time, but then that loses the time zone.

 If you have a time in UTC with its time zone as numbers representing its
 offset from UTC and DST, you could use SimpleTimeZone. It just has the 
 offset
 from UTC though, since it has no way of knowing when DST applies, so you 
 would
 have to add/subtract its DST offset to it if DST was in effect.

 I really don't know what the best way to handle time is for your 
 particular
 application, since I'm not familiar with it. But the way that std.datetime
 would handle it best would be to use either ISO or ISO Extendend strings,
 which are obviously standard, since they're ISO. It really is _not_ meant 
 to
 do things the C way and have a number that you're passing around. You 
 _can_
 get at a SysTime's internal representation (of hnsecs since midnight, 
 January
 1st 1 A.D.) by calling its stdTime function if you really want a number. 
 The
 unixTime function will also give you a number by giving you a time_t like
 you'd have in C. sysTimeToDTime converts a SysTime to a d_time, so it'll 
 give
 you what you've been using, but since d_time is going away along with
 std.date, sysTimeToDTime will be going away as well.

 Really, you're either going to have to convert your program to deal with 
 time
 the way that std.datetime does, or you're going to have to worry about
 converting a SysTime or DateTime or whatever you want to use in 
 std.datetime
 to whatever representation you want to use in your program.

 As for the functions in std.file, new functions were required in order to
 avoid breaking old code. So, it's now timeLastModified instead of
 lastModified. lastModified still returns a d_time and will be around until
 std.date is gone. timeLastModified returns a SysTime. SysTimes can be 
 compared
 by simply comparing them as you would any number. If you want to ask 
 whether
 one is at least 8 hours older than another, you would do that in one of 
 two
 ways.

 auto diff = sysTime2 - sysTime1;
 auto olderByAtLeast8Hours = diff >= dur!"hours"(8);

 or

 auto olderByAtLeast8Hours = sysTime2 > sysTime1 + dur!"hours"(8);

 dur!"hours"(8) creates a core.time.Duration of 8 hours. Subtracting one
 SysTime from another (or Date, TimeOfDay, or Datetime from another value 
 of
 the same type) results in a core.time.Duration. And you can add or 
 subtract a
 Duration from a Date, TimeOfDay, DateTime, or SysTime.

 So, you'll probably want to use SysTime, but you can use DateTime if you 
 want.
 You can even add or subtract the appopriate minutes or hours for UTC and 
 DST
 offsets to/from a DateTime if you want to handle it that way. e.g.

 auto utcOffset = dur!"hours"(8);
 auto dstOffset = dur!"minutes(60);
 auto adjusted = dt + utcOffset - dstOffset;

 So, whatever the best way to handle dates and times in your program is 
 going
 to depend on what your program is doing and how you want to adjust it. But
 d_time and std.date are going away. The values that they use will no 
 longer be
 used by Phobos or be present in Phobos at all. std.datetime is how dates 
 and
 times will be handled. So, you really should get used to dealing with
 std.datetime unless you want to be dealing with the date and time stuff
 yourself. I can understand if there may be some migration issues in 
 programs
 which use std.date, but std.date is definitely buggy (even if it works for
 what you've been doing), and it's going away.


This is great info, and very helpful. Perhaps it could be summarized into a 
general overview at the top of std.datetime's documentation page?
May 08 2011
next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On 2011-05-08 22:33, Nick Sabalausky wrote:

 "Jonathan M Davis" <jmdavisProg gmx.com> wrote in message
 news:mailman.74.1304905547.14074.digitalmars-d-learn puremagic.com...
 

 On 2011-05-08 17:46, Adam D. Ruppe wrote:

 I decided to update my compiler today, and regret it for a lot of
 reasons, but meh.
 
 One of the things is std.datetime. A lot of my code uses std.date. It
 works very, very well for me and I like it.
 
 But, the compile process is nagging me about it. I want it to shut up.


 
 Well, std.date is going away. While it may work for what you've been
 doing,
 it's highly buggy.
 

 However, I'm not even sure where to start with std.datetime...


 
 Well, it is true that it doesn't function anything like std.date.
 

 Which one of it's functions does the same as std.date.getUTCtime()?
 
 It looks like sysTimeToDTime is almost sorta kinda related, but it's
 got that same ugly deprecation text.
 
 sysTimeToDTime(Clock.currTime(UTC())); // best we can do?
 
 
 Note that it's important to me that the numbers match up - I have
 some stored and comparisons need to work the same way.


 
 std.date and the values that it uses (i.e. d_time) are going away
 entirely.
 sysTimeToDTime is there entirely to ease the transition. Anything that
 std.date it is going to have to be redesigned so that it doesn't, unless
 you
 want to copy the code to your own project and continue using that.
 

 What about std.date.toUTCString()? There's a lot of toBlahString
 in there, but none seem to match up.
 
 Another thing it's bitching at me about is std.file.lastModifed. I
 just want to check the file's age. With the old function, this is
 simple subtraction. How can I ask the new system "is this file
 greater than 8 hours old?"
 
 
 Last question: my app handles timezones on it's own by means of
 addition and subtraction of offsets against the getUTCtime() result.
 (it's a web app that fetches the offset from javascript so the server
 knows what the user's local time is relative to it's internal
 representation).
 
 std.date was pretty timezone agnostic.
 
 It looks like the DateTime doesn't mess around with them, so as
 long as I always ask for things in UTC, shouldn't be a problem, right?
 
 
 There's some more, but I think I can make the rest work with
 DateTimes by multiplying the numbers before input.


 
 Okay. Basic overiew.
 
 Date: Represents a date of the year. It holds a year, month, and day
 internally. It has no relation to time zones.
 
 TimeOfDay: Represents a time of day. It holds an hour, minute, and second
 internally. It has no relation to time zones.
 
 DateTime: Represents a specific time of day on a specific day of the
 year. It
 holds a Date and TimeOfDay internally. It has no relation to time zones.
 
 SysTime: Represents a specific date and time like DateTime does, except
 it holds it internally in hecto-nanoseconds (100ns) from midnight
 January 1st, 1
 A.D. (rather than holding the pieces of the date and time separately),
 and it
 _does_ care about time zone. It also has precision up to
 hecto-nanoseconds whereas DateTime only goes to the second.
 
 Date, TimeOfDay, and DateTime are meant to handle basic calendar-based
 operations where you don't care about the time zone. SysTime is intended
 for
 dealing with the system time, and it incorporates time zones. You can
 convert
 between SysTime and the other types (SysTime will cast to the other
 types, and
 it'll take the other types in its constructors), but you do risk problems
 with
 DST when converting from the other types to SysTime due to the fact that
 one
 hour of the year exists twice and another doesn't exist at all due to DST
 changes. But unfortunately, that's unavoidable. The only way to avoid the
 problem entirely is to keep times internally in UTC at all times (which
 SysTime does), though if the Date, TimeOfDay, or DateTime that you're
 constructing a SysTime from represents a time in UTC, and you give it UTC
 as
 its time zone, then you don't have that problem, since UTC doesn't have
 DST.
 
 What you want to use is almost certainly SysTime. Clock.currTime()
 returns a
 SysTime with the current time in the local time zone.
 Clock.currTime(UTC())
 returns a SysTime with the current time in UTC. If you give it another
 TimeZone object, it gives the current time in whatever time zone that
 object
 represents. SysTime always holds the time internally in UTC and converts
 to
 its time zone when queried for values such as its year or day, or when
 you do
 something like convert it to a string.
 
 The way that I would write the time out would be to use SysTime and
 either have it in UTC already or call toUTC on it to get one in UTC, and
 then call
 its toISOExtString (it was toISOExtendedString until dmd 2.053) function
 to
 convert it to a string to write it out. When reading it in again, I'd
 then use
 SysTime's fromISOExtString. You could just write it and read it with its
 time
 zone being in the local time, but then that loses the time zone.
 
 If you have a time in UTC with its time zone as numbers representing its
 offset from UTC and DST, you could use SimpleTimeZone. It just has the
 offset
 from UTC though, since it has no way of knowing when DST applies, so you
 would
 have to add/subtract its DST offset to it if DST was in effect.
 
 I really don't know what the best way to handle time is for your
 particular
 application, since I'm not familiar with it. But the way that
 std.datetime would handle it best would be to use either ISO or ISO
 Extendend strings, which are obviously standard, since they're ISO. It
 really is _not_ meant to
 do things the C way and have a number that you're passing around. You
 _can_
 get at a SysTime's internal representation (of hnsecs since midnight,
 January
 1st 1 A.D.) by calling its stdTime function if you really want a number.
 The
 unixTime function will also give you a number by giving you a time_t like
 you'd have in C. sysTimeToDTime converts a SysTime to a d_time, so it'll
 give
 you what you've been using, but since d_time is going away along with
 std.date, sysTimeToDTime will be going away as well.
 
 Really, you're either going to have to convert your program to deal with
 time
 the way that std.datetime does, or you're going to have to worry about
 converting a SysTime or DateTime or whatever you want to use in
 std.datetime
 to whatever representation you want to use in your program.
 
 As for the functions in std.file, new functions were required in order to
 avoid breaking old code. So, it's now timeLastModified instead of
 lastModified. lastModified still returns a d_time and will be around
 until std.date is gone. timeLastModified returns a SysTime. SysTimes can
 be compared
 by simply comparing them as you would any number. If you want to ask
 whether
 one is at least 8 hours older than another, you would do that in one of
 two
 ways.
 
 auto diff = sysTime2 - sysTime1;
 auto olderByAtLeast8Hours = diff >= dur!"hours"(8);
 
 or
 
 auto olderByAtLeast8Hours = sysTime2 > sysTime1 + dur!"hours"(8);
 
 dur!"hours"(8) creates a core.time.Duration of 8 hours. Subtracting one
 SysTime from another (or Date, TimeOfDay, or Datetime from another value
 of
 the same type) results in a core.time.Duration. And you can add or
 subtract a
 Duration from a Date, TimeOfDay, DateTime, or SysTime.
 
 So, you'll probably want to use SysTime, but you can use DateTime if you
 want.
 You can even add or subtract the appopriate minutes or hours for UTC and
 DST
 offsets to/from a DateTime if you want to handle it that way. e.g.
 
 auto utcOffset = dur!"hours"(8);
 auto dstOffset = dur!"minutes(60);
 auto adjusted = dt + utcOffset - dstOffset;
 
 So, whatever the best way to handle dates and times in your program is
 going
 to depend on what your program is doing and how you want to adjust it.
 But d_time and std.date are going away. The values that they use will no
 longer be
 used by Phobos or be present in Phobos at all. std.datetime is how dates
 and
 times will be handled. So, you really should get used to dealing with
 std.datetime unless you want to be dealing with the date and time stuff
 yourself. I can understand if there may be some migration issues in
 programs
 which use std.date, but std.date is definitely buggy (even if it works
 for what you've been doing), and it's going away.


 
 This is great info, and very helpful. Perhaps it could be summarized into a
 general overview at the top of std.datetime's documentation page?


Really, it's all there in the documentation, and some of it is in the 
documentation at the top of the page. I could probably put more of it in the 
documentation at the top of the page, but it risks getting really long, and 
some of it depends on what you're really trying to do. I can look at improving 
that documentation though. It could probably do a better job of 
differentiating between the 4 time point types (Date, TimeOfDay, DateTime, and 
SysTime) than it does, but it's all in their documentation, and I don't want 
to be too repetitive, so I'm not quite sure how best to improve it. I see what 
I can do though.

Overall, the basics of std.datetime really aren't particularly complicated, 
but there's a lot there. At some point here, I'll probably do something with 
std.datetime's function links similar to what Andrei did with std.algorithm's 
which should improve things.

- Jonathan M Davis
May 08 2011
prev sibling next sibling parent reply Russel Winder <russel russel.org.uk> writes:
On Mon, 2011-05-09 at 01:33 -0400, Nick Sabalausky wrote:

 "Jonathan M Davis" <jmdavisProg gmx.com> wrote in message=20


[ . . . ]

=20
 This is great info, and very helpful. Perhaps it could be summarized into=


 a=20

 general overview at the top of std.datetime's documentation page?


My reaction was very much "This material is really great, but why isn't
it directly associated with the std.datetime package somewhere?"  My
second reaction was "Jonathan should not have had to write such a long
email in reply, he should have been able to say 'Please go read <URL>'
for an explanation."

Jonathan,  Please can you take time to put the material of these and a
couple of other long emails you have written in the past about
std.datetime into pages ion the Web somewhere.  This one should clearly
be part of a page "Moving from std.date to std.datetime.=20

Go could really do with a new date/time handling package, one that is as
good as D's!

--=20
Russel.
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D
Dr Russel Winder      t: +44 20 7585 2200   voip: sip:russel.winder ekiga.n=
et
41 Buckmaster Road    m: +44 7770 465 077   xmpp: russel russel.org.uk
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder
May 08 2011
parent Adam D. Ruppe <destructionator gmail.com> writes:
Russel Winder wrote:

 My second reaction was "Jonathan should not have had to write such
 a long email in reply, he should have been able to say 'Please go
 read <URL>' for an explanation."


Better yet, that url could be right there in the deprecated message.

"std.date and std.dateparse are deprecated. Use std.datetime instead.
More: <wiki link to migration guide>"


When something is renamed, just listing the new name is enough since
that's everything you need to know. But a whole new module needs
a brain shift and a link can do that better than a one line message.

While it looks like everything I'd need to know is in the std.
datetime docs, they are just rather long... I looked at that
and figured reading from front to back would take too long,
especially considering the basic tasks I was asking of it.

So then I did a search for the std.date names, and only got the
deprecated functions! So it was a scary way to get started.
May 09 2011
prev sibling next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On 2011-05-08 23:22, Russel Winder wrote:

 On Mon, 2011-05-09 at 01:33 -0400, Nick Sabalausky wrote:

 "Jonathan M Davis" <jmdavisProg gmx.com> wrote in message


 
 [ . . . ]
 

 This is great info, and very helpful. Perhaps it could be summarized into
 a general overview at the top of std.datetime's documentation page?


 
 My reaction was very much "This material is really great, but why isn't
 it directly associated with the std.datetime package somewhere?"  My
 second reaction was "Jonathan should not have had to write such a long
 email in reply, he should have been able to say 'Please go read <URL>'
 for an explanation."
 
 Jonathan,  Please can you take time to put the material of these and a
 couple of other long emails you have written in the past about
 std.datetime into pages ion the Web somewhere.  This one should clearly
 be part of a page "Moving from std.date to std.datetime.
 
 Go could really do with a new date/time handling package, one that is as
 good as D's!


I could look at writing an article on moving from std.date to std.datetime, I 
suppose. We already have an article contest going, and it would make sense to 
put such an article on the site.

I don't really have anywhere online that I can post anything myself though, 
let alone links to whatever newsgroup posts might be useful for understanding 
std.datetime.

I would have hoped that the documentation in std.datetime would have been 
sufficient, but either it isn't and/or it's just too overwhelming for some 
folks, given some of the things that have been posted. There haven't been a 
lot of questions about it though since it got into Phobos, so either a fair 
number of people are understanding it well enough, or they aren't using it.

Part of the problem with better explaining std.datetime though is that it's 
pretty much all in the documentation, so it's not generally clear what I 
should be explaining further without people asking specific questions.

- Jonathan M Davis
May 08 2011
parent "Nick Sabalausky" <a a.a> writes:
"Jonathan M Davis" <jmdavisProg gmx.com> wrote in message 
news:mailman.80.1304923988.14074.digitalmars-d-learn puremagic.com...

 I could look at writing an article on moving from std.date to 
 std.datetime, I
 suppose. We already have an article contest going, and it would make sense 
 to
 put such an article on the site.

 I don't really have anywhere online that I can post anything myself 
 though,
 let alone links to whatever newsgroup posts might be useful for 
 understanding
 std.datetime.


You could put it on the D Wiki: http://prowiki.org/wiki4d/wiki.cgi

Or if you just want to post some non-wiki pages, I'd be happy to post them 
on my server for you: www.semitwist.com


 I would have hoped that the documentation in std.datetime would have been
 sufficient, but either it isn't and/or it's just too overwhelming for some
 folks, given some of the things that have been posted. There haven't been 
 a
 lot of questions about it though since it got into Phobos, so either a 
 fair
 number of people are understanding it well enough, or they aren't using 
 it.


All the info that's there is good, but I think the problems, at least as I 
see it are:

- Like others said, it could use a migration guide. It's a fantastic module, 
but I think one of the biggest use-cases for it right now is migration from 
std.date and the old deprected funcs in std.file. And since is it so very 
different, a simple migration guide would be very helpful. Without that, I 
had a little bit of touble migrating some stuff, too (although I'm sure part 
of that was just me being lazy and trying to minimize effort to just get it 
done).

- Some of the important "overview" concepts and typical use-cases are spread 
out a bit much. Of course, they should certainly stay where they are for 
reference purposes. But it would be a big help if, for instance, what you 
told Adam about Durations, subtracting/comparing SysTimes, dur!"hours"(8), 
and olderByAtLeast8Hours were summed up in the overview. Another good thing 
to put up there would be this fantastic idiom, which I probably wouldn't 
have even noticed if someone hadn't submitted a bug report to me for Goldie 
that just happened to use it:

Adapted from: http://www.dsource.org/projects/goldie/ticket/18

  StopWatch sw;
  sw.start();
  scope(exit)
      writeln(sw.peek.msecs);

And maybe a quick little example of "benchmark" added to the overview. I 
didn't even realize that existed until I was looking through the whole page.

And of course, like you said, something like what Andrei added to the top of 
the std.algorithm docs would be great, too.


 Part of the problem with better explaining std.datetime though is that 
 it's
 pretty much all in the documentation, so it's not generally clear what I
 should be explaining further without people asking specific questions.


Yea, that's definitely understandable.
May 09 2011
prev sibling parent reply Russel Winder <russel russel.org.uk> writes:
On Sun, 2011-05-08 at 23:52 -0700, Jonathan M Davis wrote:
[ . . . ]

 I could look at writing an article on moving from std.date to std.datetim=


e, I=20

 suppose. We already have an article contest going, and it would make sens=


e to=20

 put such an article on the site.


I suspect many people would be happy if you did do this, but I was
thinking more copy and paste the material into a wiki page and then let
everyone who has knowledge/interest help refine it.


 I don't really have anywhere online that I can post anything myself thoug=


h,=20

 let alone links to whatever newsgroup posts might be useful for understan=


ding=20

 std.datetime.


If there isn't a D/Phobos wiki then now is the time for Those in
Authority, to make one so that this sort of material can go up there and
be "crowd edited".


 I would have hoped that the documentation in std.datetime would have been=


=20

 sufficient, but either it isn't and/or it's just too overwhelming for som=


e=20

 folks, given some of the things that have been posted. There haven't been=


 a=20

 lot of questions about it though since it got into Phobos, so either a fa=


ir=20

 number of people are understanding it well enough, or they aren't using i=


t.

I'd put it another way.  For someone coming new to using D dates and
times, as long as they are told in no uncertain terms not to use
std.date but to use std.datetime then I am fairly sure the documentation
is good and complete.  It was for me and what I needed.  Though I do
find the indexing of the functions by signature something of a turn off
as the signatures look so ugly and frightening.

The problem here is though people who are D knowledgeable and have used
std.date.  These people are in need of an incremental update so as to
help evolve their current knowledge to the new knowledge.  Definitely
analogous to incremental backups.  If people are force to take their
current knowledge and the new knowledge and do the diffs, interpolations
and extrapolations themselves, then they see this as a barrier,
sometimes of mountainous rather than molehillish proportions.  If these
people are offered a "diff" route from old to new, it turns the barrier
into a bit of a pimple, something that can be squeezed out of existence
quickly.  Updating documents definitely smooth updating.


 Part of the problem with better explaining std.datetime though is that it=


's=20

 pretty much all in the documentation, so it's not generally clear what I=


=20

 should be explaining further without people asking specific questions.


Definitely, questions are indicators to lines of reasoning that need
explanation.  Without these questions then it is nigh on impossible to
guess what material to offer.  Another reason for a wiki that everyone
can write to.  Questions can be asked, answered, referred to, refined,
etc.  Email is great for the initial question and initial short answer,
it is not a good medium for knowledge!=20

--=20
Russel.
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D
Dr Russel Winder      t: +44 20 7585 2200   voip: sip:russel.winder ekiga.n=
et
41 Buckmaster Road    m: +44 7770 465 077   xmpp: russel russel.org.uk
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder
May 09 2011
parent "Lars T. Kyllingstad" <public kyllingen.NOSPAMnet> writes:
On Mon, 09 May 2011 09:49:04 +0100, Russel Winder wrote:


 On Sun, 2011-05-08 at 23:52 -0700, Jonathan M Davis wrote: [ . . . ]

 I could look at writing an article on moving from std.date to
 std.datetime, I suppose. We already have an article contest going, and
 it would make sense to put such an article on the site.


 
 I suspect many people would be happy if you did do this, but I was
 thinking more copy and paste the material into a wiki page and then let
 everyone who has knowledge/interest help refine it.
 

 I don't really have anywhere online that I can post anything myself
 though, let alone links to whatever newsgroup posts might be useful for
 understanding std.datetime.


 
 If there isn't a D/Phobos wiki then now is the time for Those in
 Authority, to make one so that this sort of material can go up there and
 be "crowd edited".


There certainly is:  http://prowiki.org/wiki4d/wiki.cgi

-Lars
May 09 2011
prev sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
I would point out though that'll be a while before std.date and its related 
functions actually go away, so any code which needs to be converted to 
std.datetime definitely has time to be reworked however is appropriate.

Currently, they're scheduled for deprecation, which just results in the 
compiler complaining at you in the cases where it can tell that you've used a 
type or function which has been scheduled for deprecation. Later, they'll 
actually be deprecated, so then -d will then be required when compiling if you 
want to use them. _Then_ they will finally be removed. It has never been 
officially decided how long each of those phases is supposed to be, so it 
could be quite a while before std.date is actually gone. Walter definitely 
wants to avoid breaking people's code when API changes are made, so it's going 
to be a gradual process. My first guess would be that it'll be around 6 months 
of "scheduled for deprecation" followed by 6 months of deprecated before 
something actually is removed, but I really don't know. It could be longer. 
Which reminds me that I need to bring up that topic again on the Phobos list. 
We really should have a plan for how long each of the phases of deprecation 
take.

- Jonathan M Davis
May 08 2011
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
Jonathan M Davis wrote:

 I would point out though that'll be a while before std.date and its
 related functions actually go away, so any code which needs to be
 converted to std.datetime definitely has time to be reworked
 however is appropriate.


Yeah, but I figure it's better to do it sooner than later. The more
I wait, the more data I've got to deal with converting and the more
users I risk angering too.
May 08 2011
parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On 2011-05-08 21:29, Adam D. Ruppe wrote:

 Jonathan M Davis wrote:

 I would point out though that'll be a while before std.date and its
 related functions actually go away, so any code which needs to be
 converted to std.datetime definitely has time to be reworked
 however is appropriate.


 
 Yeah, but I figure it's better to do it sooner than later. The more
 I wait, the more data I've got to deal with converting and the more
 users I risk angering too.


Oh, I totally agree that it's generally better to switch sooner rather than 
later, but you do have time to figure out what the best solution is in your 
situation rather then being in a situation where all of your code is about to 
break because std.date is eminently disappearing.

Also, any insights into where std.datetime might have problems integrating 
with formats that you might have to keep your time in (other than d_time) 
would be useful. So, if you see areas where std.datetime is just plain lacking 
(as opposed to just being different), feel free to point them out. It's a very 
different type of solution than std.date was though, so it could take some 
getting used to. std.date was essentially the same solution as C except that 
it made d_time hold milliseconds whereas time_t holds seconds. std.datetime, 
on the other hand, is very much an object-oriented solution.

- Jonathan M Davis
May 08 2011