.qdate - Date Parsing

Basic Usage

Parsing Dates

To convert a date string into a timestamp, use .qdate.resolve with the date format string.

.qdate.resolve["%A %B %d, %Y"; "Friday October 12, 2018"];

/=> 2018.10.12D00:00:00.000000000

To convert a date string to a specific type, use .qdate.resolveAs with an additional desired type.

.qdate.resolveAs[`date; "%A %B %d, %Y"; "Friday October 12, 2018"];
/=> 2018.10.12

Printing Dates

Printing a date formats any temporal type into the provided date format.

.qdate.print["%A %B %d, %Y"; 2018.10.12];
/=> "Friday October 12, 2018"

.qdate.print["%A %B %d, %Y at %I:%M %p"; 2018.10.12D13:02:03.456];
/=> "Friday October 12, 2018 at 01:02 PM"

Overview

.qdate parses strings into q temporal data using formatters to decompose the components. This library is based off the GNU strptime parsing functionality. .qdate can convert to and from temporal types and string using these date formatter strings.

Formatters

Specifier	Replaced By	Example
%a	Abbreviated weekday name	Sun
%A	Full weekday name	Sunday
%b	Abbreviated month name	Mar
%B	Full month name	March
%c	Synonym for %x %X	08/19/12 17:55:06
%C	Synonym for %A, %B %e, %Y	Sunday, March
%d	Day of the month (01-31)*	19
%D	Synonym for %m/%d/%y	08/19/12
%e	Day of the month**	19
%F	Synonym for %Y-%m-%d	2012-08-19
%g	Year without century (00-99)* Epoch at 1900	12
%h	Synonym for %b	Mar
%H	Hour in 24h format (00-23)*	14
%i	Milliseconds (000-999)*	214
%I	Hour in 12h format (01-12)*	05
%j	Day of the year (001-366)*	102
%k	Hour 24h format (0-23)**	14
%l	Hour in 12h format (1-12)**	5
%m	Month as a decimal number (01-12)*	08
%M	Minute (00-59)*	55
%n	Newline	\n
%N	Nanoseconds (000000000-999999999)*	123456789
%p	AM or PM designation	PM
%P	Synonym for %Y.%m.%dD%H:%M:%S.%N (Timestamp)	2012.01.04D14:38:16.214000234
%r	Synonym for %I:%M:%S %p	05:55:06 PM
%R	Synonym for %H:%M	17:55
%s	Number of seconds since the unix epoch	1465237003
%S	Second (00-59)*	02
%t	Tab	\t
%T	Synonym for %H:%M:%S	17:55:06
%u	Microseconds (000000-999999)	123456
%w	Weekday number starting on Sunday (0-6)*	4
%x	Synonym for %D	08/19/12
%X	Synonym for %T	17:55:06
%y	Year without century (00-99)* Epoch at 2000	12
%Y	Year with century	2012
%Z	Timezone name or abbreviation	EST
%z	Timezone numerical offset (-1200-1200)*	-0500
%%	A % sign	%
	* Indicates zero padded
	** Indicates blank padded

Padding

Note all %'s can have a numerical value representing their padding. If a value is zero padded then the number immediately following the % should be a 0. If it is blank padded then the number after the % should be an _.

dates: .qdate.print["%10_a %15_B %d, %Y"] 100?.z.d
/=> "    Thurs   October 21, 2010"
/=> "      Mon  February 17, 2014"
/=> "      Sat  February 24, 2007"
/=> "      Fri  December 19, 2014"
/=> "     Tues     March 11, 2003"
/=> ...

Parsing Dates

.qdate can parse dates that can be described using the above formatters. First, the formatter string is compiled into a specifier sequence and then applied to all dates that need to be resolved. As a shorthand .qdate.resolve performs this high-level operation on an array of strings. The following is an example of converting from raw strings to kdb+ timestamps using a formatter string.

dates: .qdate.print["%a %B %d, %Y"] 100?.z.d

/=> "Sat October 28, 2006"
/=> "Fri March 29, 2013"
/=> "Thurs July 05, 2007"
/=> "Fri August 29, 2003"
/=> "Sun March 21, 2004"
/=> "Mon January 07, 2013"
/=> "Sun February 11, 2001"
/=> ..

.qdate.resolve["%a %B %d, %Y"] dates;

/=> 2006.10.28D00:00:00.000000000
/=> 2013.04.04D00:00:00.000000000
/=> 2007.07.10D00:00:00.000000000
/=> 2003.09.04D00:00:00.000000000
/=> 2004.03.21D00:00:00.000000000
/=> 2013.01.09D00:00:00.000000000
/=> 2001.02.12D00:00:00.000000000
/=> ..

.qdate.resolveAs[`date; "%a %B %d, %Y"] dates;

/=> 2006.10.28
/=> 2013.04.04
/=> 2007.07.10
/=> 2003.09.04
/=> 2004.03.21
/=> 2013.01.09
/=> 2001.02.12
/=> ..

Parsing Dates with Leading Whitespace

Some dates are not padded with zeros when values are less than 10. For example, the date 2016/1/2 does not provide padding for the month and day values. Assuming the date is in the format yyyy/dd/mm, we can parse it with qdate using a whitespace token modifier for the month and day values.

// Without the whitespace modifier, this date will evaluate to null 
// because the input does not match the pattern
.qdate.resolveAs[`date; "%Y/%d/%m"] "2016/1/2";
/=> 0Nd

// Using the whitespace modifier _ accepts the given input
.qdate.resolveAs[`date; "%Y/%_d/%_m"] "2016/1/2";
/=> 2016.02.01

Parsing Dates with Timezones

Dates with timezones can be parsed to be GMT time by providing either a %z or %Z token depending on the format of the timezone.

.qdate.resolveAs[`time; "%H:%M %z"] "09:10 -0400"
/=> 13:10:00.000

Formatting Dates

.qdate can format a date into an arbitrary formatter sequence with any valid specifier string. This string must be passed to .qdate.print along with the dates to be formatted. The following is an example of formatting a set of random dates.

dates: .qdate.print["%a %B %d, %Y"] 100?.z.d

/=> "Sat October 28, 2006"
/=> "Fri March 29, 2013"
/=> "Thurs July 05, 2007"
/=> "Fri August 29, 2003"
/=> "Sun March 21, 2004"
/=> "Mon January 07, 2013"
/=> "Sun February 11, 2001"
/=> ..

.qdate.print

Prints a set of dates using the given formatter string. This converts a temporal type into strings using the given pattern to represent the data.

Parameters:

Name	Type	Description
fmt	string	Format string describing the organization of the pattern to print. This format string should combine identifier tokens to describe the format of an output date string.
dates	.qdate.temporal | .qdate.temporal []	Collection of temporal data to represent using the provided pattern

Returns:

Type	Description
string[]	Pretty formatted date strings

Example: Printing a date as yyyy-mm-dd

 // %Y - Yeah with century
 // %m - Month as a number (01-12)
 // %d - Day of the month (01-31)
 .qdate.print["%Y-%m-%d"] 2015.06.07
 /=> "2015-06-07"

Example: Printing multiple dates

 dates: "d"$til 10;
 /=> 2000.01.01 2000.01.02 2000.01.03 2000.01.04 ..

 // %Y - Yeah with century
 // %m - Month as a number (01-12)
 // %d - Day of the month (01-31)
 .qdate.print["%Y/%m/%d"] dates
 /=> "2000/01/01"
 /=> "2000/01/02"
 /=> "2000/01/03"
 /=> "2000/01/04"
 /=> ..

Example: Printing a time

 // %I - Hour in 12 hour format
 // %M - Minute
 // %p - AM or PM designation
 .qdate.print["%I:%M %p"] 14:12:34.123
 /=> "02:12 PM"

Example: Printing a date and time

 // %D - Synonym for %m/%d/%y
 // %r - Synonym for %I:%M:%S %p
 .qdate.print["%D %r"] 2012.03.17D14:23:35.341
 /=> "03/17/12 02:23:35 PM"

Example: Printing using weekday and month names

 // %A - Full weekday name
 // %B - Full month name
 // %e - Day of the month without zero padding (1-31)
 // %Y - Yeah with century
 .qdate.print["%A %B %e, %Y"] 2010.07.02
 /=> "Friday July 2, 2010"

.qdate.resolve

Parses a string into a timestamp using the given pattern.

Parameters:

Name	Type	Description
fmt	string	Format string describing the organization of the input pattern. This format string should combine identifier tokens to describe the format of an   input date string.
dates	string | string[]	String dates to convert to q date types

Returns:

Type	Description
timestamp | timestamp[]

Example: Parsing dates

 dates: 2 _/: ssr[;".";"/"] each string 1000?.z.d
 /=> "06/10/18"
 /=> "17/11/07"
 /=> "03/12/26"
 /=> ..

 .qdate.resolve["%y/%m/%d"] dates
 /=> 2006.10.18D00:00:00.000000000 
 /=> 2017.11.07D00:00:00.000000000
 /=> 2003.12.26D00:00:00.000000000
 /=> ..

Example: Parsing times

 times: string "t"$1000?.z.p
 /=> "19:49:48.080"
 /=> "01:56:58.202"
 /=> "19:40:23.195"
 /=> ..

 .qdate.resolve["%H:%M:%S.%i"] times
 /=> 0D19:49:48.080000000
 /=> 0D01:56:58.202000000
 /=> 0D19:40:23.195000000
 /=> ..

.qdate.resolveAs

Parses string formatted dates using a pattern identifier string. The output is then converted to a provided temporal type.

Parameters:

Name	Type	Description
dt	symbol	Temporal data type to output, one of: `timestamp`month`date`datetime`timespan`minute`second`time
fmt	string	Format string describing the organization of the input pattern. This format string should combine identifier tokens to describe the format of an   input date string.
dates	string | string[]	String dates to convert to q date types

Returns:

Type	Description
.qdate.temporal | .qdate.temporal []

See Also: .qdate.resolve