Dates, Times, and Durations

Blawx allows you to record and deal with information about dates, times, and durations of time.

It does this by providing four data types; date, time, datetime, and duration; by providing value blocks for each, and by providing statements that you can use to manipulate those values.

Date, Time, Datetime, and Duration Types and Values

The date, time, datetime, and duration data types can be used when creating attributes on a category. For example, in the Net 30 example that comes with Blawx, Invoices are defined as having an invoice date and a payment due date. That code looks like this:

To create date, time, datetime, and duration values in Blawx you can simply type them in using the value blocks that appear in the Dates drawer of the toolbox.

A test in the Net 30 example uses the date value block to specify a date like this:

Understanding Dates

Blawx represents dates, datetimes, times, and durations as a number that indicates a number of seconds. With regard to dates and datetimes, it represents the number of seconds that have passed since January 1, 1977 UCT. With regard to times, it represents the number of seconds that have passed since the immediately previous midnight. With regard to durations, it simply represents a number of sections. Durations can be negative, indicating a period of time into the past.

When entering dates (and the date portion of a datetime), you provide a year, month, and a day. The year is an integer, which means that it can be zero, or a negative number. In Blawx, the year zero is the year prior to the year 1 CE (1 BCE), and the year -1 is the year prior to that (2 BCE).

Months can only be integers between 1 and 12, and days can only be integers between 1 and 31. If you specify an invalid date, such as February 30, or February 29 on a year that was not a leap year, Blawx will not tell you that the date is invalid, but your calculations may fail.

Understanding Durations

Durations are represented as a sign, and four numbers. The sign is either "+" or "-", indicating whether it is a duration forward in time, or a duration backward in time. The six numbers represent the number of days, hours, minutes, and seconds respectively, in the duration.

Days, hours, and minutes must be non-negative integers. Seconds must be a number greater than 0.

Understanding Times

Times are represented by three numbers, for hours, minutes, and seconds. Hours must be an integer between 0 and 23, Minutes must be an integer between 0 and 59, and seconds must be a non-negative number.

The main use of a time value is to be able to combine it with a date value to get a datetime value. Most calculations are performed using datetimes and durations.

Understanding DateTimes

A DateTime is a combination of a date and a time. In Blawx, all datetimes are "local", which means that there is no way to indicate the time zone of a date time. If you are dealing with dates and times from different areas of the world in the same encoding, you will want to ensure that all of your dates and times are as of the same timezone, such as UCT.

Date, Time, Datetime, and Duration Statements

In addition to the blocks that allow you to generate date, time, datetime and duration values, there are the following additional statements available in the Toolbox in the Dates drawer.

Most blocks that accept a date in a given input will accept either a date or a datetime.

Now and Today

The now and today blocks allow you bind a variable to the date or datetime of the Blawx server at the time a question is run.

Note that calculating the current date and time is done once only, at the start of the execution of the question, so there will only every be one value bound from using the Now and Today blocks. You cannot, for instance, use the Now block twice in order to determine how much time has passed while answering a question.

Date Comparison

The date comparison block allows you to check whether one date is before, after, the same as, no earlier than or no later than the other date.

Duration Comparison

The duration comparison block allows you to check whether one duration is larger, smaller, not larger, not smaller, equal to, or not equal to another duration.

The duration comparison block compares the integer representaiton of the duration, not the absolute value. Negative durations will all be "less than" positive durations, and vice-versa.

Date Add Block

The date add block allows you to find solutions where the difference between the two dates or datetimes is equal to the duration. If you know the two dates, it can derive the duration (which is more like date subtracting). If you know the duration and one date, it will derive the other date. If the duration provided represents a duration "into the past", the date add block will subtract that amount of time from a date.

For example, the Net 30 example uses a date add block to find the due date of an invoice by adding a duration of 30 days to its date of issue, like this:

Datetime Combination

The datetime combination block allows you to either generate a datetime from a date and a time (which is the primary use of time values in Blawx), or to extract a date and time from a datetime.

Blawx Understands Leap Years

When calculating days and durations between dates, adding durations to dates, and comparing durations to one another, Blawx is aware of the effect of leap years. If you ask for the date that is one day after February 28, 2004, you will get Feburary 29, 2004. If you ask for the date one day after February 28, 2000, you will get March 1, 2000.

Blawx does not currently take into account leap seconds.

Using Times in the Scenario Editor and with the Blawx Reasoner API

When using the code editor or test editor interface, seconds can be specified to a precision of 6 decimal points. That is to say, 23.456789 is a valid number of seconds inside the code editor and test editor.

When using the scenario editor and the Blawx Reasoner API on which it is based, seconds are not available. This will change in a future version of Blawx.

Generating Dates, Datetimes, and Times from Numbers

There are also blocks that will allow you to generate dates, times, and datetimes from numbers. Numbers cannot be used directly in the place of dates or datetimes or times, in Blawx, but if you happen to know the timestamp you are interested in, or if you are generating a date from a posix timestamp provided by the user over API, these blocks can be useful.