We have added what we think is some significant new functionality for how you can get, use and display date and time information in Rainmeter.

These fall into a couple of categories, each with new options and option values. I will touch on each of these individually, then do a post with an example skin that should demonstrate how it all fits together.

Input - Reading and evaluating a date and time string.

TimeStamp

The first and most important new capability is that you can now define a TimeStamp option for a Time measure that consists of a date and / or time representation in just about any format.

The documentation for TimeStamp is probably the best explanation of this, but in general this means you can define something like:

This TimeStamp string can be ANY format you might get from a web site, or any format you define yourself. The key is that you are going to follow that TimeStamp value with another new option, that will tell the measure how to "decode" it.

TimeStampFormat

When you use a formatted string in the TimeStamp option, it will require that you also have a TimeStampFormat option that creates a "mask" for the format. In effect you tell the measure what those bits and pieces of the string mean as Time measure Format codes.

Again, the documentation for TimeStampFormat is the most complete way to understand this, but as an example you might use:

What that does is "mask" the formatted TimeStamp string, telling it what the different components mean as Time Format codes. It can be any combination of Format codes, spaces and text that you need to create the mask that matches the string.

TimeStampLocale

One last new option to complete the "input" part of things. If the string that you get, for instance from a WebParser measure, is in a different "language / locale" than "English" which is what the Time measure uses by default, you can tell it what language / locale it is in so it will be read and decoded properly. For that we use the new TimeStampLocale option. This option consists of a NLS Language / Locale Identifiers code, that identifies the language, or language and country, desired.

For example, if we assume that the date / time string you are getting is in German, you might use:

The effect of this is that any formatted date and / or time string is decoded by the measure, and will set the value of the measure to the appropriate Windows timestamp number. This is a number of seconds since January 1, 1601, and is what the Time measure uses, and has always used, to define the date and time for the measure.

This Windows timestamp number can then be used in Calc measures or other formulas to do "math" on the date, to compare the date from the measure with the current date for instance, or it can be formatted for display in a String meter, which we will now address.

Output - Formatting the display

Format

The Time measure has always used the Format option to format the Windows timestamp value of the measure into a readable date / time string that you define. This has not changed with the new functionality.

This would display "Wednesday, February 18, 2015 14:58:00" when the value of [MeasureTime] is used in a String meter.

So what we have done is "input" a formatted date / time string, "decoded" it into a valid timestamp the measure can use, and "formatted" it any way we like for display.

So the string "2015-02-18T14:58:00Z" from our WebParser RSS feed (for instance) is turned into "Wednesday, February 18, 2015 14:58:00" in our skin. Very powerful stuff.

FormatLocale

One last new option to complete the "output" part of things. Remember above, we used the new TimeStampLocale option to tell the measure what language / locale the "input" TimeStamp string is in.

By default the "output" of the Format option will always be in "English" in a Rainmeter Time measure. So if your system's locale is other than "English", or you want to set the output to some other desired language, you can simply use the FormatLocale option, which will use the same NLS Language / Locale Identifiers codes to define the language / locale that should be used when the measure value is formatted with the Format option.

This would accept and decode the date / time string in English, and output the result in the French language and locale. Doesn't matter a bit that your system is in German. If you wanted the output in German, you would use FormatLocale=de-DE.

Output - The result

So we are now able to use any formatted date / time string in the measure, that is any format, in any language. We "decode" that string to create a Time measure value, and using the Format and FormatLocale options, output the result in any format and language we want in a String meter.

There are a couple of other new options that are somewhat related to this, that I will touch on in additional posts following this one, then we will look at an example skin that sorta pulls it all together.

One of the things that occurred to us when we were working on the changes to the date / time functionality in the post above, is that this new functionality is going to make it pretty easy to get a date / time from some source like an RSS feed, and compare the Windows timestamp value that creates with a Time measure getting the current system or GMT time. In effect a way to ask "how old is that item?".

Any mathematical comparison of two Windows timestamp values will end up with a result in "seconds". That is as it should be, but what if you want display that as "days, hours, minutes, seconds" instead. We needed a way to facilitate that.

What we have done is add a new SecondsValue option to the UpTime measure.

If defined, this will override and change the default behavior of UpTime. Instead of getting and formatting the number of seconds since the system was last restarted, it will then use that SecondsValue number of seconds as the "input" for the measure, and allow you to format that as "days, hours, minutes, seconds" as desired using the Format option.

Another thing we found when working on the changes to the date / time functionality in the first post above, is that there is, and always has been, an annoying limitation with how a Time measure returns "number" values.

The way it works is that if there is no Format option on a Time measure, then the number value of the measure will be the Windows timestamp number representing that date / time. If there IS a Format option on the measure, then the number value will be one of two things.

First possibility is a number that the Format option results in. For instance Format=%H will return the number of "hours" at 15:00 as "15" which is a valid number and will be the number value of the measure.

Second possibility is that the Format option does not return a valid "number", like Format=%A (Wednesday). In this case, the number value of the measure will be "zero".

In either of those cases, the Windows timestamp number of the measure is in effect "lost", and can't be used in calculations or formulas. This means that often you have to create two identical Time measures, one WITH the Format option, for "display" and one WITHOUT the Format option, for "math".

We have added a new :Timestamp Section Variable modifier. This will only be valid when applied to a Time measure, and will return the Windows timestamp value of that measure whether it has a Format option on it or not. That value can then be used in calculations or formulas, without needing to create additional Time measures.

Here is an example skin that demonstrates much of the new and changed functionality described in the first three posts in this thread.

Let's get the skin and take a look at the output, then we can tear it apart a bit and describe what it is doing:

FormatTime_1.0.rmskin

FormatTime.jpg

First let's look at the general goals and result:

We are getting the first ATOM feed <entry> from the Breaking News site at http://www.breakingnews.com/feeds/rss/. One of the bits of information we can get, and now properly use, is the <updated> date and time of the entry item.

As you can see in the first date / time we display, the feed is returning "2015-02-18T17:27:33Z" as a "string" in the feed.

So what we want to do is get and format that date and time in a nice, readable format in both the original GMT and our local time. We then want to evaluate and display how "old" that entry is.

The goal of this measure is to turn that <updated> string from the feed, remember it was something like "2015-02-18T17:27:33Z", into a valid Time measure we can use.

TimeStamp=[MeasureEntryUpdated]
This will use the value of the WebParser child measure as the input to the TimeStamp option.TimeStampFormat=%Y-%m-%dT%H:%M:%S
This sets up the "mask", that allows the measure to "decode" that string from the feed.TimeStampLocale=#LocaleID#
This tells the measure what language / locale the feed string is in. We set that to "en-US" (US English) in the [Variables] section at the beginning of the skin.FormatLocale=#LocaleID#
This tells the measure that the output "Format" should also be in US English. We could have set this to French or Russian or any other language we wanted.Format=#OuputFormat#
This is just the normal Format option for a time measure, which we set in [Variables] to "%#c" or "Long date and time representation for system or defined locale." That will give us the formatted output we want when used in a String meter.

Next, we are going to figure out how "old" this entry is. Let's look at the first part of the Calc measure initially:

What we are doing is getting the difference between the Windows timestamp from the ATOM feed, and the current GMT time. We use the Abs() function to ensure it is a positive number, so we can use it later as the "age" of the post.

At the end of that [MeasureTimeDiff] measure above, we are examining the result and using !SetOption to set the Format option of an UpTime measure to show the result in "days, hours, minutes, seconds" as needed, but only when needed. If its only 120 seconds old, we only need "minutes, seconds".

Ok, so we have the formatted date / time in GMT, and we know how "old" it is, let's turn that GMT time into our local time:

You are right moshi, It was my mistake to assume that the system "locale" would be used by default. In fact, Rainmeter Time measures always assume "English", and you will need to use FormatLocale to effect the output "language / locale".

I have corrected as best I can in the docs and here in the change announcement. Thanks for catching that.

I would also like to note that we (as in Rainmeter code itself) aren't exactly decoding any of the format codes - rather, we are simply passing it on to the system and asking it to figure it all out for us.

That isn't to say we couldn't come up with "something" to address this before we pass it on to Windows, however like jsmorley pointed out, it would be near impossible to get "right" since no one follows any sort of "rules" on the matter. There might be a fix for this (see below).

While testing this new feature I have noticed a few things other than the %z/%Z issue.
#1. Some locales do not use a 12 hour time format, so %p will not read/return anything.
#2. Some locales use a different year system, and the year will be converted to the locales year. For example, try Arabic. FormatLocale=ar The year will be converted to a Hijri year used in the Islamic Calendar.
#3. The date parsed from the TimeStamp will attempt to validate if possible, meaning that certain format codes might be ignored to get the correct date. I have no idea which codes will be ignored (or in which order). I noticed this with an invalid weekday name (%a). For example:

This parses the date correctly, however, July 1st 2014 was a Tuesday not a Friday. The output will validate the rest of the date, and then output the correct day of the week (in this case: Tuesday).

It is also worth noting that sometime in the future %z will be changed to support the ISO8601 offset from UTC (ie. +1000). Likewise, new format specifiers: %C, %D, %e, %F, %g, %G, %h, %n, %r, %R, %t, %T, %u, and %V will be supported. E/O modifiers might be available as well. I won't get into what these new specifiers mean at this time since it is unclear "when" these all these options will be available. We will find out when VS2015 comes out.

Brian wrote:...
we are simply passing it on to the system and asking it to figure it all out for us.
...
It is also worth noting that sometime in the future %z will be changed to support the ISO8601 offset from UTC (ie. +1000).

sounds great. i am pretty confident that it will be parsed by the system then. this would be exactly what i have been asking for.

Brian wrote:Some locales do not use a 12 hour time format, so %p will not read/return anything.

i noticed that too. that is something to keep in mind for skins using relative (R) Y coordinates.

Brian wrote: The date parsed from the TimeStamp will attempt to validate if possible, meaning that certain format codes might be ignored to get the correct date. I have no idea which codes will be ignored (or in which order). I noticed this with an invalid weekday name

ignoring weekdays makes sense as they are not unique. it would have been nice if a combination of weekday and week number would work, but that does not seem to be the case.