Day home Documentation
Day Specification

Architecture

DAYo object

Calendar dayYear, month and day or year and month or just a year
Not knownWe simply don't know. (Not the same thing as Not valid)
Not validWe've found some logical error. (Not the same thing as Not known)
Beginning of timeWe don't have data going back beyond a certain point
End of timeOngoing. A very common pattern in real-world applications
FloatingA month or a month and a day. Start of tax years for example
IntervalNumeric values of days, months and years used when comparing or shifting days
Not valid intervalSomething went wrong with calculations

DAYo object storage and inter-working with other date and data systems

See the Data representation documentation.

Defining methods

1Difference is not the same thing as duration. if d1 is the same as d2 then the difference is zero days but the duration is one day. This illustrates the richness of what we can do if we think about dates properly but also the pitfalls for the unwary.

System architecture

Definitions

Abstract date
Abstract meaningsThe exact meanings of these values depends on the application. The systems developer has to know what these are.
Beginning of time, End of time or Not known. Day has well defined rules for how to process these in various contexts.
Calendar date This is 'a date that might appear on a calendar'.
  • Just a year
  • Just a year and month
  • A year month and day
Floating date This applies to days with unspecified 'more significant' components. ie.
  • Only month and day components specified. eg. Birthday
  • Only day component specified. eg. Monthly pay day
Fully specified date A calendar date where the three elements, year, month and day are defined and real. If it is 'one square' of the calendar on your wall then it's fully specified.
Interval A DAYo object may be used to explicitly represent a time period expressed as ±,Y,M,D.
  • The sign applies to the whole.
  • Intervals should not be used to represent dates.
Julian date The number of days elapsed since January 1st 4713 BC. For our purposes a serial number for days which always 'counts one' every 24 hours. This only applies to fully specified dates, but where this holds we can do exact date arithmetic.2.
Period
WarningDo not get the terminology of Periods mixed up with Intervals. An Interval is a particular type of Day object. A Period is a lack of Precision.
A date never specifies a moment in time. The least span of time it covers is 24 hours. The Period of a date is the full range of possible dates that it might cover. For example "May 2007" covers a Period from "1st May 2007" to "31st May 2007" inclusive.
Precision Analogous to numerical precision when dates are specified as Y-M-D with Y being the most and D being least significant. Part of the power of Day is being able to deal with imprecise values.
Signature A top-level indicator of the type of value contained in a day encoding.
2WARNING: Some people misuse Julian Date to mean the "ordinal date" which is the number of the day in the year.

See also A programmer's quick reference is available here. We suggest having quick scan to start with.
However it's really important that the concepts associated with abstract values and not-quite straightforward methods are understood, which is the purpose of this document.
Grey area between generic API and Javascript implementation This document is a how things work document which, although it uses the Javascript implementation for illustration simplifies certain details of the Javascript implementation so that the underlying methods are clear.
This is not meant to be a Javascript API reference.

Global Day properties

These are class properties, ie. called directly on the DAY class.

Miscellaneous

versionString telling the build date and time Version numbers are not used.
iNVInteger Occasionally a function that returns an integer will want to return an alarm rather than throw an exception Js value happens to be -9999999

Signatures

Return an integer 0 to 7.
NVI0 Invalid interval
INT1 Interval
NV2 Not a date value
FLO3 Floating date
NK4 Date not known
BoT5 Beginning of time Or such an interpretation as 'before we started counting' or 'some time ago'
Cal6 Calendar day
EoT7 End of time Or such an interpretation as 'not yet'

Unix timestamp representation

UNIX_NVInteger 13 Dec 1901 02:00:00 This value is without a reason code. (Which would be in minutes) -2147551200
UNIX_NKInteger 13 Dec 1901 04:00:00 -2147544000
UNIX_BOTInteger 13 Dec 1901 05:00:00 -2147540400
UNIX_EOTInteger 18 Jan 2038 07:00:00 2147410800

Error handling

We understand two sort of errors that can appear:
  1. A programmer has allowed something incorrect to happen or the system is confused beyond it's ability to handle the strangeness. For example if a function needs an integer and receives a string then that's a programming error. These (mostly) throw exceptions.
  2. Then there's the inevitable issues with unsuitable inputs. For example what should happen if we try to find the latest date of two days where one is NV? These return values which can be interpreted by further processing without triggering a meltdown. Typically when a return value is a Day object it will have the NV signature and a reason code embedded. If an integer is returned then iNV will be returned.
We try to be flexible when it comes to inputs and definite when it comes to illogical combinations of methods and data values.

Environment

Obviously day and month names are different in different languages. So are other conventions and error messages that a user may see also. An appendix will normally be loaded before any DAY operations. This can be used to pre-set system-wide parameters.

Appendix files

The naming and formatting of appendix files is dealt with in more detail here This also describes algorithm configuration settings.

Environment properties

appendixstring The actual file name being used. If no separate appendix found and using internal defaults then this will be en-gb.dax
errorstring Examine this if there's a problem loading an appendix. A null string indicates no problem found
force2or4DigitYearsboolean If true then years must be in the form yy or yyyy @@@ Check actual implementation
i18nstring relative path to directory where the appendices are located. @@@No trailing slash (to be allowed)
intervalRegExstring Regular expression that detects intervals as input Hack this if you don't want to use y, m and d
yearLimitinteger Maximum allowable size of year + or -
To avoid duplication there are some other important properties described in the internationalisation reference above.

Environment methods

Boolean get/set methods only set if the optional argument is actuall boolean true or boolean false.
AllowDayOnlyIntervalsoptional boolean new value Get/Set do we allow INTs to be created with more than 31 days eg +0y 0m 66d If not then the conversion factor 30.4375 (365.25/12) will be used.
AllowExcessDaysInMonthoptional boolean new value Get/Set true if we allow silent coercing of slightly too many days in month to end of month For example is 31st September assumed to be the last day of September? If this is false then an input error will be raised.
BCIndicatorOptional string new value Get/set the string used for BC indication. Do not call with a null string unless you want the BC indicator to be eliminated!
ImpliedYearOptional integer Get/Set numeric value of IMPLIED_YEAR Allowable inputs are 0,-1,-2 or a year > 999
InYearLimits(Integer year to test),
↩ boolean
Check to ensure the year given is within current limits. Only applies to INT and Cal.
Initialise There will always be an Initialise method which will set up the environment according to (a) some file or (b) some text. The JS implementation leaves getting a file to the programmer and takes the text, thus avoiding async issues.
IsDmyOrderBoolean Get/set whether element order is D-M-Y (False if M-D-Y)
Lookup(string Key, integer number)
↩ string
This is a low-level method to access the dictionary
MonthName(integer Number, integer Version)
↩ string
Look up the month name for the given number. Version is 1 to 4 depending on the length required.
SearchMonths(string Input)
↩ integer
Use the string supplied to see if it will match with any month names. If so then retirn 1 for Jnuary and so on. Return 0 for no match. This only matches when there is exactly one match even if that match is partial. For example J would fail as not being specific but Janua would succeed as although it is partial it can only refer to one month.
SearchShortcuts(string Input)
↩string
See if input matches one of the shortcut formats. For example be would match with Beginning-of-time and would return BoT. If there's no match then return a null string.
SetKeyValue(string Key, string Value) This is a low-level method of setting some element of the environment. It is not persistent over sessions.
TwoDigitFixboolean Get/set TWO_DIGIT_FIX Allowed values are 0, 20 and 50

Standalone Day methods. Class methods

I give up... use JS API for now

Operations using more than one Day

Utility methods