rnbn (version 1.1.2)

datePart: Extract element from a vague date

Description

The NBN Gateway stores dates in three fields: startDate, endDate and dateType. This allows for storage of date with various degrees of uncertainty (referred to as "vague dates"). This function allows the year, month, week or day to be extracted from the vague date whilst properly taking into account the dateType.

Usage

datePart(startDate, endDate, dateType, part = c("year", "month", "week", "day"))

Arguments

startDate

Date returned by NBN Gateway as a string in the format yyyy-mm-dd

endDate

Date returned by NBN Gateway as a string in the format yyyy-mm-dd

dateType

One or two letter code, returned by NBN Gateway, describing the nature of the vague date (see details)

part

The type of information you want to extract. Possibilities are year (default), month, week or day

Value

An integer number. -1 is returned if the requested element is not available or does not make sense for the given dateType (see details)

Details

The start and end dates are returned by the NBN Gateway as strings in the format yyyy-mm-dd. The dateType is a one or two letter code as follows:

• D - normal date - start and end dates are the same
• DD - date range (e.g. the period for which a trap was set). startDate is the first day in the range and endDate the last
• O - month - startDate is the first of the month, endDate is the last day of the month
• OO - month range - startDate is the first day of the starting month of the range, endDate is the last day of the last month in the range
• Y - year - startDate is 01 Jan and endDate 31 Dec of the year
• YY - year range - startDate is 01 Jan of the year at the start of the range and endDate is 31 Dec of the last year of the range
• -Y - to year - represents an uncertain period where only the ending year is known, e.g. the year of publication of a book from which an observation was extracted which gives no indication of when the observation was made - so all we know is that it was made before the book was published. startDate is NULL and endDate is 31 Dec of the year in question.
• Y- - since year - represents an uncertain date where all we know is that it was made after some year. endDate is NULL and startDate is 01 Jan of the year in question. This is deprecated (use a year range closed by the year in which the record was extracted (because we know the observation must have been made before then!), but dates in this format exist on the Gateway.
• U or ND - Unknown - the date was unknown; both start and endDate are NULL
• M - month - represents a month when the year is not known. startDate is the first of the month in the year 9999, enddate is the last day of the month in 9999
• S - season - represents a seaon when the year is not known. Seasons are taken as a month ranges and can be as follows: spring - March-May, summer - June-Aug, autumn - Sep-Nov or winter - Dec-Feb. startDate is the first day of the month at the start of the range in year 9999 and endDate is the last day of the month at the end of the range in 9999
• P publication date - year of publication - equivalent to Y

The value that is returned depends both on the element that is requested and the dateType of the vague date that is passed to the function as follows:

• year - this is normally the year from endDate. It cannot be determined in the case of Y-, U, ND, S or M date types so -1 will be returned in these cases
• month - this is normally the month from endDate. It is only available if the dateType is D, DD (and both dates are in the same month), O or M. Otherwise -1 is returned.
• week - week number within year. This is normally the week number of the end date. It is only available if the dateType is D or DD and both dates are in the same week. Otherwise -1 is returned.
• day - day number within year. This is only available for dateType D. Otherwise -1 is returned.

Examples

datePart("2010-06-15", "2010-06-15", "D", "year") # returns 2010
datePart("2010-06-15", "2010-06-15", "D", "mon") # returns 6