Posted: 05/28/08 15:38:41
simas wrote:
Don't understand me wrong. Tango is great and i know that this was a hard work.
But, what me confusing is
(i) the naming of some objects and functions
(ii) the leak of simple examples that shows me the handling and relationship of the objects
(iii) and the diversity of (time) objects.
There was so many questions, the first time i use tango.time.
I understand that you are confused. Time is a complicated thing to implement, which requires different ways of looking at it. The diversity of the functions and objects used to represent and manipulate time are there to meet the requirements that people who are using time functionality might have. The problem is that not everyone needs to use time in the same way, and there is not one representation which satisfies all needs. I'll try to respond to all your points.
simas wrote:
The function Time.date doesn't return a Date-object, they round the time (units of 100ns) to a day. Why not roundToDay?
There was some pressure to retain the old function names from the previous implementation. Previous to this implementation, DateTime (which was changed to be just Time) contained the same date function. I agree that the name is somewhat misleading, but there is a tradeoff between clarity and brevity, and since brevity had precedence, the resulting function exists.
simas wrote:
The function Wallclock.toDate doesn't return a Date-object, they returns a DateTime?-object. Why not toDateTime?
Again, brevity and precedence.
simas wrote:
This seems like a trivial issue to me. I doubt it will change (although I agree it seems inconsistent).
simas wrote:
What is wall-time? Is this the local time? Where are the definitions?
This is the local time. The definitions are in the ChapterDateTime ("tango.time.Clock and WallClock modules represent UTC and local wall time respectively").
simas wrote:
The Time-object is a time point but is also a timespan (internal).
The Time struct is not a TimeSpan. There are subtle but important differences, such as one cannot add two Time structs together, but one can certainly add two TimeSpans together. They are purposely separated to enforce the relationships. They used to not be separated, and this caused confusion as coders would re-use a struct to mean both a point in time and a time span.
simas wrote:
The Time-object can be a UTC time or local time (wall-time), right? The user must store the information separately, right?
Correct. Just like when you see 10:00pm, you need to know what time zone you are in to know what it really means. A Time struct is only part of the information. Generally, one only uses UTC or local time, so there is no confusion.
simas wrote:
The chrono.* objects only holds helper functions (as i understand that), to convert a Time object to a calendar representation and back.
Yes, we have split the calendar functionality out of Time to make Time simple for everyday use, and only use calendar stuff when necessary. For example, if you are just timing things in an application, one does not need to know the year/month/day.
The other reason they are separate is because one cannot assume which calendar is being used. Time is universal, and defined by science. Calendars, though somewhat defined by science, are subject to human beliefs and arbitrary decisions.
simas wrote:
The Wallclock object has functions to convert Time objects to DateTime? and back via OS functions. Why is this necessary?
Currently there is no time zone capabilities in Tango. When there are (it is planned), these functions will likely be deprecated as they are not consistent across OSes and have limitations.
simas wrote:
The Wallclock functions should be members of Time object.
There is an effort in most of tango to split implementation into usable chunks. The reason is because the D compiler will include all the implementation from a module whether it is used or not. To put the functionality of WallClock and Clock into Time means that objects which store Time or TimeSpans but do not use all the functionality of Clock or WallClock will import all that functionality anyways.
The other reason is that a goal of the interfaces of Tango is to include as little implementation as possible. Since Time is a very common thing for interfaces to use (it really should be treated as a built-in type), we restrict Time to contain only basic implementation. To include all the Clock and WallClock code in every interface which might use a TimeSpan would be against that goal.
There are a lot of decisions made in Tango based on these goals, and I can't say I always agree with them. However, this is the situation we have, and it's probably not going to change.
simas wrote:
The DateTime? is also a calendar represantation, right? Gregorian?
DateTime represents a point in time based on a calendar. The calendar is not specified in the DateTime, so it must be known somewhere else. The clocks return the DateTime based on the OS calendar, which is generally Gregorian.
simas wrote:
What should i use? chrono.* or Wallclock to convert Time objects to calendar and back? What is faster?
WallClock is used specifically to convert UTC to and from local time. If you want to just convert a Time to a DateTime, use chrono.*, which should be faster as it does not involve system calls.
simas wrote:
ISO8601 holds helper functions to convert a string to binary time represantation. Why not name them DateParser?.
ISO8601 functions converts a string to local time objects, right? If so, i must convert time to UTC to store it time zone independent, right?
I did not write ISO8601, but it is named after an ISO standard for parsing date and time. I'm not sure how it is used because I don't use it.
simas wrote:
The user can use Time, DateTime?, TimeOfDay? or a Date to represent a timepoint. Important is, what the user want to do.
If the user want primary and often to calculate with time, he should use Time and TimeSpan?.
If the user want only to store a timepoint, he should use DateTime?.
For points in time, If the user needs to get access to the calendar information, then store things as DateTime. Otherwise, store as a Time. The TimeOfDay can easily be extracted from a Time, and it only uses 8 bytes to store it.
simas wrote:
I suggest to improve the documentation and to add some examples, that shows the handling and relationship.
What examples would you suggest aside from those already in the documentation? I'll be happy to include them.