Proposal for custom time string formatting in std.datetime

[Jonathan M Davis]

On Thursday, December 22, 2011 12:59:15 Stewart Gordon wrote:
> On 22/12/2011 03:41, Jonathan M Davis wrote:
> <snip>
> 
> > http://jmdavis.github.com/d-programming-language.org/std_datetime.html
> 
> Have I got all this right?
> 
> - a flag goes from % up to another %, a {, a whitespace or punctuation
> character - flags with [...] portions are exceptions to this rule,
> extending to the closing ] - %{ or %} is a literal { or }
> - all literal characters that aren't classed as whitespace or punctuation
> must be enclosed in {...}
> - {%} is just a literal %
> - in %C2* and %Cn* flags, C must be either _ (space) or 0

Yes. I believe that that's correct.

> To look at the detail:
> 
> - In %nY, does "up to n" mean that it truncates years longer than that to
> that many characters?  Does it strip any leading 0s that result from this
> truncation?  (Under %3Y, does 2011 become 11 or 011?)

It becomes 11. There's no filler character. For instance, the example section 
gives

assert(SysTime(Date(8, 7, 4)).toCustomString!"%2Y"() == "8");

But I guess that I need to find a clearer way to state the flag's definition.

> - But the approach to formatting the year is nicely systematic.  (I've
> thought of possibly adding to my scheme a means of formatting dates to
> arbitrary length with sign, in order to support the ISO format for years
> that may be outside the 1BC-9999 range.

I tried to be extremely systematic about all of the flags. As a result, I 
believe that the system is very consistent with itself.

> - If you're going to have the ISO week number in the system, it seems to me
> you should also have the week-numbering year.  (I've thought about possibly
> adding these to my scheme.)

%isoweek and %C2isoweek

> - In %F, What does "as many digits as necessary" mean?  In particular, why
> in the example code does it give 12/100000 and not 3/25000 despite the
> latter being shorter?

Obviously, that needs to be clearer. The denominator is always a multiple of 
10. It's what the mpeg-7 standard uses, which is why it's there.

> - Can only literal stuff be included within %BC[...] and %AD[...]?

That was the idea. I don't think that it needs to be any fancier than that. 
You could just use %cond or %func otherwise. That should probably clearer 
though.

> - %cond and %func - I'm made to wonder to what extent this would be used and
> to what extent it would just be simpler to use if / ?: / ~.  Anyway, I
> assume that if there's more than one, they will reference the template
> arguments in order.  Can %cond contain other %*[...] flags?  Indeed, can
> %cond's be nested to arbitrary depth?

In theory, %cond is supposed to be arbitrarily nestable, though I question 
that it would generally be a good idea to do so. And yes, as the text 
underneath that section of flags mentions, functions are associated with flags 
the same way that arguments to format or writefln would be.

> - Does %localeDate give the short or the long date format?  (This and
> %localeTime are handled by separate functions in my library - I didn't
> think there was any real use case for including such a thing within a
> longer formatted date/time string.)

I have no idea. It's strftime which has that functionality (%x and %X). The 
idea is that std.datetime would parse that to determine the correct format, 
but I don't know how well it will work, since I haven't written it yet. 
They're flags that are only there, because I was trying to make it possible to 
to use toCustomString to do everything that strftime can do. It does occur to 
me though that I don't have a way to do %c (which would be both the date and 
time in the preferred format). I guess that that would be %localeDateTime.

But these _are_ flags that might have to get the axe if I can't do what I think 
that I'm going to be able to do to figure out what strftime is doing and use 
the same format.

> On the whole, it seems a powerful system.  The format strings can get quite
> obfuscated, but at least the flags that are likely to be commonly used
> aren't too bad.

The idea at least is that the common use cases are fairly easy but that it's 
also powerful to do most any format without much difficulty. Some of the 
standard formats _do_ get a bit convoluted however.

> It seems strange to require explicit notations both for flags and for
> alphanumeric literals.  But I suppose it makes the literals easier to read
> than having to follow where all those % signs are.

It makes the parsing easier (particularly with multi-character flags), and 
makes it somewhat easier to read IMHO, since it does clearly separate out the 
portions that _aren't_ flags. I'm not sure that I would have thought of that on 
my own however. It seemed like a good idea from your scheme.

> One thing I noticed doesn't appear in your scheme is ordinal suffix.  OK, so
> arbitrary alignment fields and collapsible portions aren't to be seen
> either, but those are quite rare in format string schemes anyway.

I was debating that. A flag for it could certainly be added. I don't have a way 
to deal with it in a locale-specific manner though, unfortunately. It's also a 
bit nasty, since it has to be tied to a specific number. I think that it only 
really makes sense with the days, however. So, at that point, you either 
create alternate versions of some of the day flags that have a th suffix or 
something similar, or you create a separate day flag which only does the 
ordinal suffix (similar %yplus). I may add such a flag.

Regardless, some of the specific flags are definitely up for debate (e.g. several 
of them are only there because strftime has something similar), and if there 
are flags that are likely to be generally useful which I'm missing, they may be 
worth adding.

- Jonathan M Davis