cleanTime

Description: Adjusts a date and time passed to be within valid range. Adjusts time so that 0 <= minutes < 1440 or 0 <= seconds < 86400.

Declaration:

int cleanTime(int *julianDate, int *itime, int timeGranularitySeconds)

Parameters:

int *julianDate

Julian date, in days since 01Jan1900, with 01Jan1900 being day 1 (31Dec1899 is day 0) This is the standard day count used throughout DSS and can be negative (or large).

int *itime

The time in timeGranularitySeconds (60 for minutes, 1 for seconds)

int timeGranularitySeconds

The number of seconds a unit in *itime represents, usually MINUTE_GRANULARITY (60) or SECOND_GRANULARITY (1)

Returns:

Zero (false), if date is undefined
One (true) if the date/time is defined

Remarks:

This function allows one to add or subtract from time, then adjust to standard date and time For example, if you added 2880 minutes to the time, it will add 2 days to julianDate, and subtract 2880 minutes from time (assuming time is within range.) Accommodates large times.

compareTimes

Description: Compares two date/times and returns -1 if first date/time is before second, 0 if times are the same, or 1 if first date/time is after second.

Declaration:

int compareTimes (int julianFirst, int timeFirst, int julianBaseFirst,
int timeGranularitySecondsFirst, int julianSecond, int timeSecond,
int julianBaseSecond, int timeGranularitySecondsSecond);

Parameters:

int julianFirst

The Julian date of the first date/time to compare.

int timeFirst

The first time in timeGranularitySeconds (60 for minutes, 1 for seconds) to compare.

int julianBaseFirst

The Julian base date for the first date. Usually 0 (zero), unless you are comparing large times used in statistical analysis.

int timeGranularitySecondsFirst

The number of seconds a unit in *itime represents, usually MINUTE_GRANULARITY (60) or SECOND_GRANULARITY (1)

int julianSecond

The Julian date of the second date/time to compare against.

int timeSecond

The Second time in timeGranularitySeconds (60 for minutes, 1 for seconds) to compare.

int julianBaseSecond

The Julian base date for the second date. Usually 0 (zero)

int timeGranularitySecondsSecond

The number of seconds a unit in *itime represents, usually MINUTE_GRANULARITY (60) or SECOND_GRANULARITY (1)

Returns:

-1 if first date/time is before second
0 if times are the same
1 if first date/time is after second

dateToJulian

Description: Takes a character date, in a variety of styles, and converts it to Julian. The styles of dates is not exhaustive, but this does include styles that other date parsing functions do not have. It does not matter if the date is in upper or lower case, all numeric, etc.

Declaration:

int dateToJulian(const char *dateString);

Parameters:

const char *dateString

The date to parse. This can be in a variety of formats. See example table below. If no year is given, the current year is assumed. If no day is given, the first of the month is assumed.

Returns:

Julian date
UNDEFINED_TIME (-2147483647): Invalid date

Remarks:

See dateToYearMonthDay() for more info.

Example dates:

All of the dates from yearMonthDayToDate()
Alpha numeric dates: June 2, 1985; JUNE 2, 85; 2 June 1985; 02Jun85; Jun 85
Numeric dates: 6/2/85; 6-2-1985; 1985-06-02

dateToYearMonthDay

Description: Takes a character date, in a variety of styles, and converts it into integer year, month, day. The styles of dates is not exhaustive, but this does include styles that other date parsing functions do not have. It does not matter if the date is in upper or lower case, all numeric, etc.

Declaration:

int dateToYearMonthDay(const char *dateString, int *year, int *month, int *day);

Parameters:

const char *dateString

The date to parse. This can be in a variety of formats. See example table below.

int *year (output)

The year of the date. This will be a four digit year (e.g., 1982 instead of 82). If no year is given, zero(0) is returned.

int *month (output)

The month of the Julian date, where 1 is January, 12 is December. The month (in dateString) is the only parameter that has to be included.

int * day (output)

The day of the Julian date, where 1 is the first day of the month. If no day is given, zero(0) is returned.

Returns:

STATUS_OKAY: Successful
STATUS_NOT_OKAY: Invalid date

Remarks:

A rather complex routine that tries a variety of parsing. Based on julymd() from original heclib.

Examples:

All of the dates from yearMonthDayToDate()
Alpha numeric dates: June 2, 1985; JUNE 2, 85; 2 June 1985; 02Jun85; Jun 85
Numeric dates: 6/2/85; 6-2-1985; 1985-06-02

dayOfWeek

Description: Returns the day of the week, where Sunday = 1, Saturday = 7 (sabbath, or seventh)

Declaration:

int dayOfWeek(int julian)

Parameters:

int julian
        The Julian date to use

Returns:

The day of the week, with Sunday being 1.

getCurrentDateTime

Description: Returns the current local system time in Julian days, seconds past midnight and mills past second.

Declaration:

void getCurrentDateTime (int *julian, int *secondsPastMidnight, int *millsPastSecond);

Parameters:

int *julian (output)

Current date in days since 01Jan1900, with 01Jan1900 being day 1 (31Dec1899 is day 0). This is the standard day count used throught DSS and can be negative (or large). An undefined day is the number "-2147483647". Note, 0 (zero) is valid day and is frequently used.

int *secondsPastMidnight (output)

The current time of day in seconds past midnight. "1" is one second past midnight. "0" doesn't exist, as midnight belongs to the end of the day (by convention) and midnight is the number "86400". secondsPastMidnight varies from 1 to 86400.

int *millsPastSecond (output)

The current time second fraction in mills past the secondsPastMidnight variable. millsPastSecond varies from 0 to 999.

Remarks:

This is a system dependent function, although all systems have similar functions.

See Also:

getCurrentDateTimeString()

getCurrentTimeMillis

Description: Returns the current local system time in milliseconds since Jan 01, 1970, as a long long.

Declaration:

long long getCurrentTimeMillis();

Returns:

long long time
        The local system clock time, in milliseconds since Jan 01, 1970.

getCurrentDateString

Description: Returns the current military style date in a character string, e.g., "02Jun2020"

Declaration:

void getCurrentDateString (char *dateString, size_t sizeOfDateString);

Parameters:

char *dateString (output)

The character string to return the date in. Must be dimensioned to at least 10.

size_t sizeOfDateString

The length of the string. Must be at least 10.

See Also:

getCurrentDateTimeString()
getCurrentTimeString()

getCurrentDateTimeString

Description: Returns the current local system time as a character date and character time. Local system time means that the time zone is included, but daylight time is not.

Declaration:

void getCurrentDateTimeString (char *dateString, size_t sizeofDateString, int style, char *timeString, size_t sizeofTimeString);

Parameters:

char *dateString (output)

A String to containt the current date. Should be declared large enough to hold style (below). Examples: "05Apr1976" (Style 4), "6/2/1985" (Style -101)

size_t sizeofDateString

The size of dateString. Should include space for null terminator.

int style

The style code of how the data should be returned, as given below in the table. Style "4" is the standard date style used by DSS (e.g., "02Jun1985")

char *timeString (output)

A string to contain the complete current time, including mili-seconds. Should be dimensioned at least to 13. Example time string: "08:23:12.084"

size_t sizeofTimeString

The size of timeString. Should be at least 13.

Returns: None

Date Style Codes:

Numeric Date Style Codes:

Remarks:

Style "14" is the standard date style used by DSS.

getCurrentTimeString

Description: Returns the current day time with milli seconds in a character string, e.g., "08:23:12.084"

Declaration:

void getCurrentTimeString (char *timeString, size_t sizeOfTimeString);

Parameters:

char *timeString (output)

The character string to return the time in. Must be dimensioned to at least 13.

size_t sizeOfTimeString

The length of the string. Must be at least 13.

Note:

For debug preamble.

See Also:

getCurrentDateTime()

getDateAndTime

Description: Returns the date and time from numeric variables (those used in time series structs.)

Declaration:

void getDateAndTime(int time, int timeGranularitySeconds,
int julianBaseDate, char dateString, int sizeOfDateString, char hoursMins,
int sizeofHoursMins);

Parameters:

int timeMinOrSec

The time value to convert to character, given in timeGranularitySeconds since baseDate. "1" is one second past midnight. "0" doesn't exist, as midnight belongs to the end of the day, by convention, and midnight is the number "86400". secondsPastMidnight varies from 1 to 86400.

int timeGranularitySeconds

The number of seconds each unit in time represents, MINUTE_GRANULARITY (60) or SECOND_GRANULARITY (1) or HOUR_GRANULARITY (3600) or DAY_GRANULARITY (86400)

int julianBaseDate

The Julian base date, which when appropriatly aded to the time, give the full correct date and time.

char *dateString (output)

The character string to return the date in. Must be dimensioned to at least 13.

int sizeOfDateString

The length of the string. Must be at least 13.

char *hoursMins (output)

The character string to return the hours and minutes in. Must be dimensioned to at least 9.

int sizeofHoursMins

The length of the string. Must be at least 9.

getDateTimeString

Description: Returns a character date and character time from a julian date and time in seconds past midnight.

Declaration:

void getDateTimeString (int julian, char *dateString, size_t sizeofDateString, int dateStyle, int secondsPastMidnight, char *timeString,
size_t sizeofTimeString, int timeStyle);

Parameters:

int Julian

Date in days since 01Jan1900, with 01Jan1900 being day 1 (31Dec1899 is day 0). This is the standard day count used throughout DSS and can be negative (or large). An undefined day is the number "-2147483647". Note, 0 (zero) is valid day and is used.

char *dateString (output)

A String to containt the current date. Should be declared large enough to hold style (below). Examples: "05Apr1976" (Style 4), "6/2/1985" (Style -101)

size_t sizeofDateString

The size of dateString passed in. Should include char for null terminator.

int dateStyle

The style code of how the data should be returned, as given below in the table. dateStyle "4" is the standard date style used by DSS (e.g., "02Jun1985").

int secondsPastMidnight

The current time of day in seconds past midnight. "1" is one second past midnight. "0" doesn't exist, as midnight belongs to the end of the day, by convention, and midnight is the number "86400". secondsPastMidnight varies from 1 to 86400.

char *timeString (output)

A string to contain the complete current time, including mili-seconds. Should be dimensioned at least to 13. Example time string: "08:23:12.084"

size_t sizeofTimeString

The size of timeString. Should be at least 13.

Date Style Codes:

Numeric Date Style Codes:

Remarks:
Style "14" is the standard date style used by DSS.

incrementTime

Description: Increments a Julian date and time (in seconds) by a number of periods for a standard interval.

Declaration:

int incrementTime(int intervalSeconds, int numberPeriods, int julianStart,
int secondsStart, int *julianEnd, int *secondsEnd);

Parameters:

int intervalSeconds

The time interval, in seconds. This must be a standard interval, as shown below.
int numberPeriods The number of periods to increment by. This may be positive, negative or zero.

int julianStart

The julian day to increment from.

int secondsStart

The time, in seconds, of the day to increment from.

int *julianEnd (output)

The resulting julian day after incrementing.

int *secondsEnd (output)

The time, in seconds, of the day after incrementing. Will be 0 < secondsEnd <= 86400

Returns:

STATUS_OKAY: Successful
STATUS_NOT_OKAY: Invalid interval

Remarks:

"Cleans" output time, so that seconds are within 1 day. For monthly, yearly, etc. intervals, the date/time is incremented according to a logical interval. For example, for a monthly interval the date/time is increment by months, not 30 days (e.g., Jan 31 to Feb 28 to Mar 31 to Apr 30).

Accounts for "offsets", for example daily data at 8:00 am, and monthly data occurring on the 5th of the month (e.g., Jan 5 to Feb 5 to Mar 5 to Apr 5). For intervals of tri-month and above, any time near the end of the period is considered "End of Period". So, 29 January is seen as month end of period with no offset.

Standard Intervals:

isLeapYear

Description: Determines if a given year is a leap year or not.

Declaration:

int isLeapYear (int year)

Parameters:

int year
        The four digit year to check (e.g., 1969).

Returns:

0 (zero) Not a leap year.
1 (one) A leap year.

isTimeDefined

Description: A convenience function to check if date / times are set defined.

Declaration:

int isTimeDefined(int julianDate, int timeSeconds);

Parameters:

int julianDate

Julian date, in days since 01Jan1900, with 01Jan1900 being day 1 (31Dec1899 is day 0). This is the standard day count used throughout DSS and can be negative (or large).

int timeSeconds
        The time in minutes or seconds

Returns:

0 (zero) Not defined.
1 (one) Defined.

isTimeInRange

Description: Determine if the time value given is in range of the specified time window.

Declaration:

int isTimeInRange(int timeValue, int *lastValueStatus, int timeGranularitySeconds, int baseDate, ztsTimeWindow *timeWindow);

Parameters:

int timeValue

The time value to compare, in timeGranularitySeconds (minutes or seconds) from baseDate.

int *lastValueStatus (Input and output)

Flag indicating if value is before, in or after time window. Uses as input and returns for this value:

*lastValueStatus < 0: previous time was before time window
*lastValueStatus == 0: previous time was within time window
*lastValueStatus > 0: previous time was after time window

int timeGranularitySeconds

The number of seconds a unit in timeValue represents, usually MINUTE_GRANULARITY (60) or SECOND_GRANULARITY (1)

int baseDate
        The julian base date (days since Jan 01, 1900) for this time.

ztsTimeWindow *timeWindow
        The time window struct to compare to.

Returns:

0 (zero) Not within rang.
1 (one) Within rang.

Remarks:

This function is a convenience function used to quickly test if a time is within the requested time window, for irregular interval date. timeGranularitySeconds is usually 60 for minutes, but often 1 for seconds, and also can be larger for very long time spans (3600 for hours, etc.)

stuct ztsTimeWindow

typedef struct {

// Private

// An internal struct used for computing the time window and other
// time information. The primary info is passed back to the main
// time series struct.
int structType;

// Standard date and time for first and last value,
// Not necessarily the start / end of the time window.
int startJulian;
int startTimeSeconds;
int endJulian;
int endTimeSeconds;
int intervalSeconds;
int timeOffsetSeconds;
int numberValues;
int blockSize;
int startBlockJulian;
int endBlockJulian;

} ztsTimeWindow;

julianToDate

Description: Takes a Julian day date and converts it to a date character string, such as "23Feb2002".

Declaration:

int julianToDate(int julianDate, int dateStyle, char *dateString,
size_t sizeofDateString);

Parameters:

int julianDate

Julian date to convert, in days since 01Jan1900, with 01Jan1900 being day 1 (31Dec1899 is day 0). This is the standard day count used throughout DSS and can be negative (or large). An undefined day is the number "-2147483647". Note, 0 (zero) is valid day.

int dateStyle

The style code of how the data should be returned, as given below in the table. Style "4" is the standard date style used by DSS (e.g., "02Jun1985")

char *dateString (output)

A String to containt the current date. Should be declared large enough to hold style (below). Examples: "05Apr1976" (Style 4), "6/2/1985" (Style -101)

size_t sizeofDateString

The size of dateString. Should include space for null terminator.

Returns:

STATUS_OKAY: Successful
STATUS_NOT_OKAY: Invalid date (undefined Julian or date sting too short)

Date Style Codes:

Numeric Date Style Codes:

julianToYearMonthDay

Description: Takes a Julian day date and converts it to year, month, and day.

Declaration:

void julianToYearMonthDay (int julian, int *year, int *month, int *day)

Parameters:

int julianDate

Julian date to convert, in days since 01Jan1900, with 01Jan1900 being day 1 (31Dec1899 is day 0). This is the standard day count used throughout DSS and can be negative (or large). An undefined day is the number "-2147483647". Note, 0 (zero) is valid day.

int *year (output)
        The year of the Julian date. 

int *month (output)
        The month of the Julian date, where 1 is January, 12 is December.

int *day (output)
        The day of the Julian date, where 1 is the first day of the month.

Remarks:

Uses standard conventions for month and day; For example 01Jan1980 is day 1, month 1, year 2020.

numberPeriods

Description: Computes the number of periods between two dates/times for a standard interval.

Declaration:

int numberPeriods(int intervalSeconds, int julianStart, int secondsStart,
int julianEnd, int secondsEnd);

Parameters:

int intervalSeconds
        The time interval, in seconds. This must be a standard interval, as shown below.

int julianStart
        The Julian day of the start.
int secondsStart
        The time, in seconds, of the day of the start.

int julianEnd
        The Julian day of the end.

int secondsEnd
        The time, in seconds, of the day of the end.

Returns:

The number of periods between the two dates/times for the given interval

Remarks:

Truncates any remainder.
The number of periods may be positive, negative or zero.
Cleans time before computing, so you can have, for example seconds of 50 days.
Does not check for a standard interval.
An interval < 1 is returned STATUS_NOT_OKAY (which is also a valid number of periods).
For intervals of tri-month and above, any time near the end of the period is considered "End of Period", so, 29 January is seen as month end of period with no offset.

Standard Intervals:

secondsToTimeString

Description: Returns a character time from the time in seconds past midnight, and optionally, mills past second.

Declaration:

void secondsToTimeString(int secondsPastMidnight, int millsPastSecond,
char *timeString, size_t sizeofTimeString, int timeStyle);

Parameters:

int secondsPastMidnight

The time of day in seconds past midnight. "1" is one second past midnight. Midnight is the number "86400". 0 (zero) is allowed for Beginning of Period items. secondsPastMidnight varies from 0 to 86400.

int millsPastSecond

The time second fraction in mills past the secondsPastMidnight variable. millsPastSecond varies from 0 to 999.

int timeStyle

The style code of how the time should be returned, as given below in the table.

char *timeString (output)

A string to contain the complete time. Must be dimensioned to hold string with null char. Example time string: "08:23:12".

size_t sizeofTimeString

The size of timeString. Should be at least the size shown in the table following.

Remarks:

Does not "clean time", assumes that you are passing in valid times. Invalid styles, times, or lengths returns a null in the first char. If first character is "0", that is always returned (no option to remove.)

Time Style Codes:

See Also: timeStringToSeconds()

spatialDateTime

Description: Takes a date / time string in the form 01DEC2016:0000 and returns the Julian date and time in seconds. Note "0000" is returned as zero and "2400" as 86400

Declaration:

int spatialDateTime(char *dateTimeString, int *julian, int *seconds);

Parameters:

char *dateTimeString

A character string containing the spatial style date and time to parse
(e.g., "01DEC2016:0000") Must have a colon between the date and time.

int *Julian (output)

Returns the Julian date from the string, or UNDEFINED_TIME if cannot be determined

int *seconds (output)

Returns the time portion in seconds, or < 0 if cannot be determined. The time will range from 0 to 86400, inclusive.

Returns:

STATUS_OKAY if correctly parsed
STATUS_NOT_OKAY if invalid spatial date time string.

Remarks:

Don't use this function to determine if it is a correct string Check your string length before calling, as an empty string is valid for spatial data.

timeStringToSeconds

Description: Converts a character time to seconds past midnight.

Declaration:

int timeStringToSeconds(const char *timeString);

Parameters:

const char *timeString

The time string to parse. Examples of what can be parsed are provided in the table below

Returns:

secondsPastMidnight, which varies from 0 to 86400. A time of zero is valid

Remarks:

Does not parse or look for mills.

See Also:

timeStringToSecondsMills()

Time Style Examples:

timeStringToSecondsMills

Description: Converts a character time to seconds and fractions of a second, in milliseconds, past midnight.

Declaration:

float timeStringToSecondsMills(const char *timeString);

Parameters:

const char *timeString

The time string to parse. Examples of what can be parsed are provided in the table below

Returns:

secondsPastMidnight as a float, with the fractional portion being milliseconds. secondsPastMidnight varies from 0.000 to 86400.000. A time of zero is valid.
If the string was not able to be parsed, -1.0 is returned.

Remarks:

Valid times range from "00:00:00.000" to "24:00:00.000". Outside of this range, -1 will be returned.
No style is needed as this will attempt to parse, regardless of style.
Not intended to identify a string as a time; a valid time is assumed.

See Also:

timeStringToSeconds()

Time Style Examples:

yearMonthDayToDate

Description: Takes an integer year, month, day date and converts it to a date character string, such as "23Feb2002".

Declaration:

int yearMonthDayToDate(int year, int month, int day, int dateStyle,
char *dateString, size_t lenDateString);

Parameters:

int year
        The year of the date.

int month

The integer month of the date. 1 corresponds to January, 2 to February, etc. This must be a number between 1 and 12.

int day

The integer day of the date. This must be a number between 1 and 31.

int dateStyle

The style code of how the data should be returned, as given below in the table.
Style "4" is the standard date style used by DSS (e.g., "02Jun1985")

char *dateString (output)

A String to containt the current date. Should be declared large enough to hold style (below). Examples: "05Apr1976" (Style 4), "6/2/1985" (Style -101)

size_t sizeofDateString

The size of dateString. Should include space for null terminator.

Returns:

Length of the date.
STATUS_NOT_OKAY: Fail (invalid date or date sting too short)

Date Style Codes:

Numeric Date Style Codes:

yearMonthDayToJulian

Description: Takes an integer year, month, day date and converts it to a Julian day.

Declaration:

int yearMonthDayToJulian (int year, int month, int day);

Parameters:

int year
        The year of the date.

int month

The integer month of the date. 1 corresponds to January, 2 to February, etc. A number between 1 and 12, however this function will adjust the Julian date according to the number of months (clean it up).

int day

The integer day of the date. A number between 1 and 31, although this function will correctly adjust the date if other.

Returns:

Julian day, in days since 01Jan1900, with 01Jan1900 being day 1 (31Dec1899 is day 0). This is the standard day count used throughout DSS and can be negative (or large).
UNDEFINED_TIME "-2147483647" if error. Note, 0 (zero) is valid day.

Remarks:

This function is used to add months / days and clean up the date. For example, if you wanted to add 500 months to the date, just add 500 to the month. Does negative also.

See Also:

yearMonthDayToDate()
dateToJulian()