# parse_date_string

Definition: | include builtins\timedate.e timedate td = parse_date_string(string s, sequence fmts=default_parse_fmts, integer partial=allow_partial)
Description: | Convert the string s into a timedate.
pwa/p2js: | Supported.
Comments: | The fmts and partial parameters can be defaulted using the set_timedate_formats() routine, the former being a list of format strings, each of which is attempted in turn. Note that a fatal error occurs if the fmts parameter is omitted and set_timedate_formats() has not been invoked. The partial flag controls whether to ignore excess text when parsing, and if set, then fmts should be ordered most detailed first - in the example below you would not want it to completely ignore the trailing "EST", but if no timezone is present you would simply assume it is a local time. Another example might be "03/09/15 6pm Customer was not happy", you might want try "DD/MM/YY ham tz" and fail before trying "DD/MM/YY ham" and pass. Note that parsing say "Monday 1/01/2000" returns a DT_DOW element set to 1, even though it was a Saturday, and any non-explicitly mentioned elements get left as zero. It is in fact perfectly legal to invoke parse_date_string("?","?"), which checks the input for that exact literal and returns {0,0,0,0,0,0,0,0,0}, however it is illegal to specify an empty string ("") as a format. The day of year field (td[DT_DOY]) is usually left zero, but can easily be obtained using day_of_year(y,m,d). Also note that routines such as format_timedate() do not generally trust the contents of td[DT_DOY], since it may contain milliseconds. To quietly catch errors from parse_date_string(), store the result in a sequence variable and either use the timedate type function to test it, or check that the length() is not 3, before attempting to use it as a timedate. If an error occurs the result has a length of 3, which consists of a numeric error code, a description of that code, and 0 or an extended description of the actual problem encountered. Said messages are intended for a developer/typecheck, not an end user.
Example: |
    include builtins\timedate.e
    td = parse_date_string("March 7 2009 7:30pm EST",{"Mmmm d yyyy h:mmpm tz","Mmmm d yyyy h:mmpm"})
See Also: | timedate, the timedate type, format strings, set_timedate_formats, format_timedate, day_of_year