[m-rev.] for review: timestamps

[Fergus Henderson]

On 31-May-2001, Simon Taylor <stayl at cs.mu.OZ.AU> wrote:
> +++ library/time.m	2001/05/31 10:46:56
> @@ -37,6 +37,12 @@
>  	% calendar times.
>  :- type time_t.
>  
> +	% A `timestamp' is similar to a `time_t' except that
> +	% timestamps are operating system independent. A timestamp
> +	% string (obtained using time__timestamp_to_string) written
> +	% on one system can be read on any other system.
> +:- type timestamp.
> +
>  	% The `tm' type is a concrete type that represents calendar
>  	% times, broken down into their constituent components.
>  :- type tm
> @@ -145,11 +151,34 @@
>  :- func time__ctime(time_t) = string.
>  
>  %-----------------------------------------------------------------------------%
> +
> +	% time__time_t_to_timestamp(Time) = Timestamp:
> +	%	Converts the calendar time value `Time' into a timestamp.
> +	%	Equivalent to `gm_time_to_timestamp(gmtime(Time))'.
> +:-func time__time_t_to_timestamp(time_t) = timestamp.
> +
> +	% time__gmtime_to_timestamp(TM) = Timestamp:
> +	%	Converts the broken-down UTC time value `TM'
> +	%	into a timestamp.
> +:- func time__gmtime_to_timestamp(tm) = timestamp.
> +
> +	% time__timestamp_to_string(Timestamp) = String:
> +	%	Converts `Timestamp' into a string with format
> +	%	"yyyy-mm-dd hh:mm:ss", expressed as UTC. 
> +:- func time__timestamp_to_string(timestamp) = string.
> +
> +	% time__string_to_timestamp(String) = Timestamp:
> +	%	Converts a string formatted as "yyyy-mm-dd hh:mm:ss",
> +	%	into a timestamp. Fails if `String' does not have the
> +	%	correct format.
> +:- func time__string_to_timestamp(string) = timestamp is semidet.

When I suggested making timestamps an ADT earlier, I was thinking
of making them an ADT in the compiler, not in the standard library.

Now, it may be that having this typestamp ADT in the library might be
a good idea.  But from the documentation there, it's very hard to see
what the point of the `timestamp' type is.  In what sense are timestamps
"OS independent", and why would you ever use `timestamp'
and `timestamp_to_string(X)', rather than `time_t' and
`timestamp_to_string(time_t_to_timestamp(X))'?

So, either the `timestamp' type should be removed here, or made into a concrete
type rather than an abstract type, or the documentation should be improved to
better explain the rationale for why you might want to use it.

The documentation of `timestamp' (if it is not removed) should give some
indication as to whether you can rely on compare/3 for it.

The fields for type tm are in an unfortunate ordering, since it means
that compare/3 won't do the right thing.  Since you've just changed
the arity of the `tm' constructor, which breaks backwards compatibility
anyway, it might be a good to take this opportunity to reorder them.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
                                    |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------