Almost all software I write uses a shared function to figure out what time was meant by the text you entered. Entering a time is such a common task that I wanted to make it as flexible as possible. The following are examples of how you can enter times. The basic idea is that if a human can puzzle out what was meant, the software should be able to do so also. Unless otherwise specified, times are assumed to be UTC.
YOUR INPUT PROGRAM INTERPRETATION ------------------------ ---------------------- 1997-May-6 12:30:23.3348 ( 6 MAY 1997 12:30:23.3348) 19970506 12:30:23.3348 * (same as above) 970506 12:30:23.3348 * (same as above) 6/18/2004 (18 Jun 2004 00:00:00) 6.18.2004 (same as above) 3:14.159 (3:14.159, current day) 13: (13:00, current day) 11/2 (or 11/f or 11 FE) (11 Feb 00:00:00, current year) 11 2 (or 11/2 or 11-2) (same as above) 11.25 2 (Same as above, but 6:00:00) 11 2 -10m (10 Feb 23:50:00, ten minutes prior to above) +6d (six days from now) -13.4h (13.4 hours ago) -14h +36m (36 minutes after 14 hours ago) Ap (April of current year) Fri (Friday closest to current time) Fri+2w (or fr+14d) (Two weeks from the nearest Friday) 7.125 (7th of current month at 3:00) 7 : (7th of current month, leave time unchanged) :43:18 (or :43.3) (43 minutes 18 seconds, hour unchanged) JD 2451545. ( 1 JAN 2000 12:00 ) j2451545 (same as above) 2451545 (same as above) mjd 51000 (MJD 51000 = JD 2451000.5 = 6 Jul 2008 0:00:00) 2008-03-14T15:26:53.5 * (FITS-style time: 2008 Mar 14, 15:26:53.5) 2008/50 (or 50-2008) (50th day of 2008: 2008 Feb 19) 50 2008 3:14:15.9 (same as above, but sets time to 3:14:15.9) 50.75 2008 (50th day of 2008, 18:00) 050.75 (50th day of current year, 18:00) 2008 o (or Octob 2008) ( 1 OCT 2008 00:00:00) y1952.34 (decimal year: about a third of the way through 1952) 1952.34 (same as above) nm+3 (three days after the nearest New Moon) -4.5w 1q (First Quarter nearest the time 4.5 weeks ago) 1997o6 nm +3d (three days after the New Moon nearest 1997 Oct 6) 1997o6 +3d nm (New Moon nearest three days after 1997 Oct 6) now 3:00 PM (3:00 PM today) now 3:00 p.m. (same) now-1h (one hour ago)
Essentially, one can enter calendar-style dates; some special date formats; a day-of-year; and one can add/subtract offsets from the time.
Calendar-style input: (This is all most people will need or want to know!) You can enter a day, month, and year (or just a day and month), optionally followed by a time of day. Year-month-day is the favored order, but even if you enter '5-1997-15', it's clear that 1997 is the year, which means 15 must be the day of the month, so it must be 1997 May 5. But a four-digit year, three-character month name, and day of the month are recommended; that avoids any risk of ambiguity, no matter what order is used.
Months, days, years can be separated by -, /, .,or space. Hours, min, seconds can be separated by : only.
Month names are interpreted "logically". For example, at least in English, 'f' is unambiguously February (no other month starts with F) and will be recognized as such, but 'ju' could be either June or July. In such cases, the program will choose the first possible month, so 'j'=January, 'JU'=June, 'Jul'=July. 'Febru' or 'f' or 'FEB' or 'february' would all be understood to mean February.
If a time (hours:minutes or hours:minutes:seconds) follows a date, it's used; otherwise, 0:00 is assumed. If just a ':' follows a date, the time is left unchanged. The day can include a decimal portion (as some of the above examples do).
Some special ways to input a calendar-style date: You can enter just a month name (as shown above) or just a number. The interpretation of that number will be:
One or two digits: 0:00 of that day of the month
Three digits: Specifies day of year (0-366)
Four or five digits: 1 Jan 0:00 of that year
Six-digit number: YYMMDD. The year is assumed to be less than 60 years
ago and not more than 40 years hence. For example,
'690322' in 2023 would be 1969 March 22. But after
2029 Mar 22, it would be assumed to be 2069 Mar 22.
Seven digits: Julian Day
Eight-digit number: YYYYMMDD
So one can just enter '3', for example, to reset to the third of the current month; or '2005' to get 1 January 2005; or '2451545' to get JD 2451545 = 1.5 January 2000. If a year entered in this manner has a decimal part, you'll get that fractional part of a year added. But if you want to set the year -23300 or 130000, you'll need to use 'y-23300' or 'y130000'; for a JD before 1000000 or after 9999999, you'd need to use 'j' or 'jd' followed by the JD. Decimal parts of a day can be added, so that '030913.75' is equivalent to '030913 18:' is equivalent to '2003 Sep 13 18:00:00'.
To get the output you want, you may need to add leading zeroes. If you wanted the fiftieth day of the current year, for example, you'd use '050', because '50' would get you the fiftieth day of the current month (i.e., most of the way into the next month). '0050' would get you the year 50, '00501007' Oct 7 of that year, and so on.
"Now" and lunar phases: You can enter 'now', optionally followed by a time of day and/or time offsets of the type described below. 'nm', '1q', 'fm', or '3q' will be interpreted as meaning New Moon, First Quarter, Full Moon, or Third Quarter. (Be warned that the phase times are accurate to only about an hour.) As shown above, these can all be combined in fairly logical ways.
Day-of-year input: As shown above, three digits (optionally followed by a decimal portion) will be interpreted as setting that day of the year. Also, if you enter two numbers, both greater than 31, the program assumes they are the year and day of the year (thus the "2008/50" and "50 2008" examples above). The program assumes that the larger number is the year.
Adding/subtracting an offset from the time: A '+' or '-' followed by a number will add/subtract that number of days to the current time. One can add a letter specifying time units: 'd' (day), 'h' (hour), 'm' (minute), 's' (seconds), 'w' (weeks), 'l' (lunations), 'y' (years), 'c' (centuries). Some examples are shown above.
This can be useful in dealing with time zones. For example, if your default time zone is UT, but you want to enter an Eastern US (UT-5) time, you can just add '-5h' to it.
You can add more than one offset; for example, Fri+2w -5h would mean "two weeks from the nearest Friday, midnight Eastern US time."
Some other forms will be interpreted, but if there's ambiguity, you may not get what you wanted.