Example script of functions discussed in this post: 

#define			FIVE_DAYS		4320000000000

string			datestring;
qword			filetime;
qword			futuretime;
int			unixtime;

// We can get the current filetime and print it out
filetime = GetLocalTime();
AddMessage("Filetime: %d",filetime);

// We can convert it to UNIX time and print it out
unixtime = DateToUnix(filetime);
AddMessage("Unix Time: %d",unixtime);

// We can convert the filetime to a formatted string, and print 
// out a few examples of different formats
datestring = FormatDate(filetime);
AddMessage("Default String Format: %s",datestring);

datestring = FormatDate(filetime,"l, F dS, Y");
AddMessage("Using a Custom Defined Format: %s",datestring);

datestring = FormatDate(filetime, DS_DATE_AT_TIME);
AddMessage("Using a Legato Defined Format: %s",datestring);


// We can use simple math to get five days from now, and print it
// out in a nice date format
futuretime = filetime + FIVE_DAYS;
datestring = FormatDate(futuretime,"l, F dS, Y");
AddMessage("Five Days From Now: %s",datestring);

// StringToDate can try to handle a poorly formatted date and make it
// a normalized format in Windows filetime
datestring = "2-20/17";
filetime = StringToDate(datestring, SD_AMERICAN);
datestring = FormatDate(filetime,"l, F dS, Y");
AddMessage("Reformatted Time: %s",datestring);

// When using StringToDate, you may want to test if it was understood or
// not. If the GetLastError function is ERROR_SYNTAX, it means the date 
// was not understood.
datestring = "2-20, Two Thousand Seventeen";
filetime = StringToDate(datestring, SD_AMERICAN);
if(GetLastError()==ERROR_SYNTAX){
    AddMessage("Cannot convert date %s, unknown format",datestring);
    }
    
// Converting from well-formed MySQL date times is also possible with
// StringToDate.
datestring = "2017-01-05 12:00:00";
filetime = StringToDate(datestring, SD_AMERICAN);
if(GetLastError()==ERROR_SYNTAX){
    AddMessage("Cannot convert date, unknown format");
    }
else{
    AddMessage("Converted MySQL Date is: %d",filetime);
    datestring = FormatDate(filetime,"1, F dS, Y");
    AddMessage("Reformatted MySQL Date is: %s", datestring);
    }

For comparing dates or doing any sort of math with dates, you need to use date-time values. These are stored in Legato as 64-bit qwords, based on the Filetime format described in the Windows SDK. They represent the number of 100 nanosecond intervals since January 1, 1601. With this number, you can store dates as numbers and easily compare them against each other. Legato provides a script function to get this value, called the GetLocalTime function. Once you have this number, you can add a number of 100 nanosecond intervals to it in order to get the time of a future event or subtract time from it. So if you want to get five days from now, it would be the result from the GetLocalTime SDK function plus 4320000000000 100-nanosecond intervals. As we did above, you can store values like that number of intervals using the define statement in your script to make the code more readable.

Comparing dates is easy with this as well. Use normal “less than” (<) and “greater than: (>) operators. Testing for equivalence is a bit trickier because with such a high resolution of the date-time value, you might need to write a function to see if they are equal enough to your particular purpose. If two dates happened within 1 second of each other, for example, is that enough to consider them equal? You could get the difference and compare it against a number of 100-nanosecond intervals, and if the difference is less than that, your function could return true for equivalence.

Another common type of date-time value that you may encounter is POSIX time, also known as Unix time, or Epoch time. This is the number of seconds since January 1, 1970. It is commonly used in a lot of Unix based systems and is very common in web environments. Legato does have functions that will convert Windows Filetime to Unix time and back (the DateToUnix and UnixToDate functions, respectively) in case you need to switch between the two. Make sure whenever you are doing comparisons or date math operations, you know which type of date-time value you are using.

Legato also provides a way for you to convert date strings into Windows Filetime dwords. The SDK function StringToDate takes a date time string and a format value as parameters and returns a Filetime value. It is pretty good at picking up most common types of date time formats (such as MySQL default string formats, a very common date format), but if you specify the format of the incoming data it helps to ensure a proper conversion. The defined values for formats are:

Of course, if you actually want to display time to a user in an intelligible way, you need to convert from Unix time or Windows Filetime formats to a string value. Legato has a very useful function called the FormatDate function that can take either a Windows Filetime date-time qword or an ISO-8601 formatted date string and convert it into whatever date format you want. The date format output can be a normal ISO-8601 style (ISO-8601 is a common way of writing dates, and more information on it can be found here), or it can be anything specified by a format string. The format string can use the following substitution characters (based on PHP 5.x):

You can also use one of the predefined formats specified in Legato. Formatting codes can be combined with bitwise operators. Therefore, if you want a mm-dd-yy format but with spaces instead of dashes in the format, you would use the code:

datestring = FormatDate(filetime, DS_DDMMYY | DS_SPACES);

Of course you could replicate this exact style with a custom string format, but this is another way to define the format of the string. The defined formatting codes are:

In summary, working with dates and times is commonly a part of scripting, and Legato provides multiple powerful tools to make date-time values easy to create, convert from format to format, and display to users.

Steven Horowitz has been working for Novaworks for over five years as a technical expert with a focus on EDGAR HTML and XBRL. Since the creation of the Legato language in 2015, Steven has been developing scripts to improve the GoFiler user experience. He is currently working toward a Bachelor of Sciences in Software Engineering at RIT and MCC.

Additional Resources

Novaworks’ Legato Resources

Legato Script Developers LinkedIn Group

Primer: An Introduction to Legato