Use Cases

These are the requirements / use cases that rust-datetime should seek to achieve:

Precision

Typical use cases: time-stamp for logging, '36763681916 nanoseconds after 1970-01-01T00:00'
Create an object to represent an Instant
Must be able to create from millisecond timestamp
Must be able to create from nanosecond timestamp
Must not provide access to the date and time fields
Must be able to be compared to another instance - earlier/later/equals
Must be able to be converted to a date and time with time zone instance
Must be independent of all calendar systems
Must serialize using the internal timestamp relative to the epoch
Performance focussed around conversion to year/month/day/hour/minute/second

Typical use cases: date and time train departs, '12th September 2007, 09:15'
Create an object to represent a Date and Time
Must be able to create from year, month, day, hour, minute, second
May be able to create from other field combinations
Must be able to call methods to access the date fields (year, month, day of month, hour, minute, second)
Must support additional date/time fields (day of year, day of week, week of weekyear, weekyear, era, ampm, hour of ampm, second of day ...)
Must support precision to the hour, minute, second level (and nanosecond?)
Must be able to be compared to another instance - earlier/later/equals
Must link the datetime to a time zone, or to no time zone (local)
Must be able to be converted to an instant if a time zone is present
Must be specific to the ISO (proleptic Gregorian) calendar system
Must serialize using the field values

Typical use cases: Birth date, transaction date, '12th September 2007'
Create an object to represent a Date without a Time
Must be able to create from year, month, day
May be able to create from other field combinations
Must be able to call methods to access the date fields (year, month, day of month)
Must support additional date fields (day of year, day of week, week of weekyear, weekyear, era, ...)
Must not provide access to time fields (preferably by not having methods to call, but if they do exist they must throw an exception)
Must be able to be compared to another instance - earlier/later/equals
Must link the date to a time zone, or to no time zone (local)
Must be specific to the ISO (proleptic Gregorian) calendar system
Must serialize using the field values

Typical use cases: office hours, '09:15'
Create an object to represent a Time without a Date
Must be able to create from hour, minute, second
May be able to create from other field combinations
Must be able to call methods to access the time fields (hour, minute, second)
Must support additional fields (meridianAmPm, hour of ampm, nanosecond? ...)
Must not provide access to date fields (preferably by not having methods to call, but if they do exist they must throw an exception)
Must support precision to the hour, minute, second level (and nanosecond?)
Must be able to be compared to another instance - earlier/later/equals
Must link the time to a time zone, or to no time zone (local)
Must be specific to the ISO (proleptic Gregorian) calendar system
Must serialize using the field values

Typical use cases: logging the current instant, checking that a library book is not overdue
Must be able to control the current time for testing
Must support real time
Must allow real time plus offset to be supported
Must allow fixed time to be supported
Must allow real time progressing at a slower rate to be supported
Must be able to get the current instant
Must be able to get the current datetime, which requires a timezone
Must be able to get the current date - today, which requires a timezone
Must be able to get the next date - tomorrow, which requires a timezone
Must be able to get the previous date - yesterday, which requires a timezone
Must be able to get the current year-month, which requires a timezone
Must be able to get the current year, which requires a timezone
Must be able to get the current time, which requires a timezone

Typical use cases: Time a shop is open, '09:00 to 17:00'
Must be able to obtain an instance representing a time interval
Must be able to construct from a start and end time
Must be able to construct from a time and a duration before or after
Must be able to support an interval that goes overnight, such as '22:00 to 08:00' (and any number of days?)
Must be able to convert to a duration
Must be able to compare to another time interval to see if it is before, abuts-before, overlaps, contains, is contained, abuts-after, after, equals
Must be able to compare to a time to see if the datetime is before, contained or after
Must not support Comparable