JulianDate

JulianDate

new

Constructs a JulianDate instance from a Julian day number, the number of seconds elapsed into that day, and the time standard which the parameters are in. Passing no parameters will construct a JulianDate that represents the current system time. An astronomical Julian date is the number of days since noon on January 1, -4712 (4713 BC). For increased precision, this class stores the whole number part of the date and the seconds part of the date in separate components. In order to be safe for arithmetic and represent leap seconds, the date is always stored in the International Atomic Time standard TimeStandard.TAI.

Parameters:
Name Type Argument Default Description
julianDayNumber Number The Julian Day Number representing the number of whole days. Fractional days will also be handled correctly.
julianSecondsOfDay Number The number of seconds into the current Julian Day Number. Fractional seconds, negative seconds and seconds greater than a day will be handled correctly.
timeStandard TimeStandard <optional>
TimeStandard.UTC The time standard in which the first two parameters are defined.
Throws:
Example
// Example 1. Construct a JulianDate representing the current system time.
var julianDate = new JulianDate();

// Example 2. Construct a JulianDate from a Julian day number and seconds of the day.
var julianDayNumber = 2448257;   // January 1, 1991
var secondsOfDay = 21600;        // 06:00:00
var julianDate = new JulianDate(julianDayNumber, secondsOfDay, TimeStandard.UTC);
See:
Source:

Methods

Returns a new JulianDate representing a time duration days later (or earlier in the case of a negative amount).

Parameters:
Name Type Description
duration Number An integer number of days to add or subtract.
Throws:
DeveloperError : duration is required and must be a number.
Returns:
JulianDate A new JulianDate object
Example
var date = new Date();
date.setUTCFullYear(2011, 6, 4);     // July 4, 2011 @ 12:00 UTC
date.setUTCHours(12, 0, 0, 0);
var start = JulianDate.fromDate(date);
var end = start.addDays(5);         // July 9, 2011 @ 12:00 UTC
See:

Returns a new JulianDate representing a time duration hours later (or earlier in the case of a negative amount).

Parameters:
Name Type Description
duration Number An integer number of hours to add or subtract.
Throws:
DeveloperError : duration is required and must be a number.
Returns:
JulianDate A new JulianDate object
Example
var date = new Date();
date.setUTCFullYear(2011, 6, 4);     // July 4, 2011 @ 12:00 UTC
date.setUTCHours(12, 0, 0, 0);
var start = JulianDate.fromDate(date);
var end = start.addHours(6);         // July 4, 2011 @ 18:00 UTC
See:

Returns a new JulianDate representing a time duration minutes later (or earlier in the case of a negative amount).

Parameters:
Name Type Description
duration Number An integer number of minutes to add or subtract.
Throws:
DeveloperError : duration is required and must be a number.
Returns:
JulianDate A new JulianDate object
Example
var date = new Date();
date.setUTCFullYear(2011, 6, 4);     // July 4, 2011 @ 12:00 UTC
date.setUTCHours(12, 0, 0, 0);
var start = JulianDate.fromDate(date);
var end = start.addMinutes(65);      // July 4, 2011 @ 13:05 UTC
See:

Returns a new JulianDate representing a time duration seconds later (or earlier in the case of a negative amount).

Parameters:
Name Type Argument Description
seconds Number The number of seconds to add or subtract.
result JulianDate <optional>
The JulianDate to store the result into.
Throws:
DeveloperError : seconds is required and must be a number.
Returns:
JulianDate The modified result parameter or a new JulianDate instance if it was not provided.
Example
var date = new Date();
date.setUTCFullYear(2011, 6, 4);     // July 4, 2011 @ 12:00:00 UTC
date.setUTCHours(12, 0, 00, 0);
var start = JulianDate.fromDate(date);
var end = start.addSeconds(95);      // July 4, 2011 @ 12:01:35 UTC
See:

Duplicates this JulianDate.

Parameters:
Name Type Argument Description
result Cartesian3 <optional>
The object onto which to store the JulianDate.
Returns:
Cartesian3 The modified result parameter or a new Cartesian3 instance if one was not provided.

Compares this date to another date.

Parameters:
Name Type Description
other JulianDate The other JulianDate to compare to.
Returns:
Number A negative value if this instance is less than the other, a positive value if this instance is greater than the other, or zero if this instance and the other are equal.

Returns true if this date is equivalent to the specified date.

Parameters:
Name Type Description
other JulianDate The JulianDate to be compared.
Returns:
Boolean true if the two JulianDates are equal; otherwise false.
Example
var original = JulianDate.fromDate(new Date('July 4, 2011 12:00:00'));
var clone = JulianDate.fromDate(new Date('July 4, 2011 12:00:00'));
original.equals(clone);      // true
See:

Returns true if this date is within epsilon seconds of the specified date. That is, in order for the dates to be considered equal (and for this function to return true), the absolute value of the difference between them, in seconds, must be less than epsilon.

Parameters:
Name Type Description
other JulianDate The JulianDate to be compared.
epsilon Number The number of seconds that should separate the two JulianDates
Throws:
DeveloperError : epsilon is required and must be number.
Returns:
Boolean true if the two JulianDates are within epsilon seconds of each other; otherwise false.
Example
var original = JulianDate.fromDate(new Date('July 4, 2011 12:00:00'));
var clone = JulianDate.fromDate(new Date('July 4, 2011 12:00:01'));
original.equalsEpsilon(clone, 2);    // true
See:

Computes the number of days that have elapsed from this JulianDate to the other JulianDate. A day is always exactly 86400.0 seconds.

Parameters:
Name Type Description
other JulianDate The other JulianDate, which is the end of the interval.
Returns:
Number The number of days that have elpased from this JulianDate to the other JulianDate.
Example
var start = JulianDate.fromDate(new Date('July 4, 2011 12:00:00'));
var end = JulianDate.fromDate(new Date('July 5, 2011 14:24:00'));
var difference = start.getDaysDifference(end);    // 1.1 days
See:

Returns the whole number component of the Julian date.

Returns:
Number A whole number representing the Julian day number.
See:

Returns the floating point component of the Julian date representing the time of day.

Returns:
Number The floating point component of the Julian date representing the time of day.
See:

Computes the number of minutes that have elapsed from this JulianDate to the other JulianDate.

Parameters:
Name Type Description
other JulianDate The other JulianDate, which is the end of the interval.
Returns:
Number The number of seconds that have elpased from this JulianDate to the other JulianDate.
Example
var start = JulianDate.fromDate(new Date('July 4, 2011 12:00:00'));
var end = JulianDate.fromDate(new Date('July 5, 2011 12:01:00'));
var difference = start.getMinutesDifference(end);    // 1441.0 minutes
See:

Computes the number of seconds that have elapsed from this JulianDate to the other JulianDate.

Parameters:
Name Type Description
other JulianDate The other JulianDate, which is the end of the interval.
Returns:
Number The number of seconds that have elpased from this JulianDate to the other JulianDate.
Example
var start = JulianDate.fromDate(new Date('July 4, 2011 12:00:00'));
var end = JulianDate.fromDate(new Date('July 5, 2011 12:01:00'));
var difference = start.getSecondsDifference(end);    // 86460.0 seconds
See:

Return the number of seconds elapsed into the current Julian day (starting at noon).

Returns:
Number The number of seconds elapsed into the current day.
See:

Returns the number of seconds this TAI date is ahead of UTC.

Returns:
Number The number of seconds this TAI date is ahead of UTC
Example
var date = new Date('August 1, 2012 12:00:00 UTC');
var julianDate = JulianDate.fromDate(date);
var difference = julianDate.getTaiMinusUtc(); //35
See:

Returns the total number of whole and fractional days represented by this astronomical Julian date.

Returns:
Number The Julian date as single floating point number.
See:

Returns true if other occurs before this JulianDate.

Parameters:
Name Type Description
other JulianDate The JulianDate to be compared.
Returns:
Boolean true if this JulianDate is chronologically later than other; otherwise, false.
Example
var start = JulianDate.fromDate(new Date('July 6, 1991 12:00:00'));
var end = JulianDate.fromDate(new Date('July 6, 2011 12:01:00'));
end.greaterThan(start);      // true
See:

Returns true if other occurs at or before this JulianDate.

Parameters:
Name Type Description
other JulianDate The JulianDate to be compared.
Returns:
Boolean true if this JulianDate is chronologically later than or equal to other; otherwise, false.
Example
var start = JulianDate.fromDate(new Date('July 6, 1991 12:00:00'));
var end = JulianDate.fromDate(new Date('July 6, 2011 12:00:00'));
end.greaterThanOrEquals(start);      // true
See:

Returns true if other occurs after this JulianDate.

Parameters:
Name Type Description
other JulianDate The JulianDate to be compared.
Returns:
Boolean true if this JulianDate is chronologically earlier than other; otherwise, false.
Example
var start = JulianDate.fromDate(new Date('July 6, 1991 12:00:00'));
var end = JulianDate.fromDate(new Date('July 6, 2011 12:01:00'));
start.lessThan(end);     // true
See:

Returns true if other occurs at or after this JulianDate.

Parameters:
Name Type Description
other JulianDate The JulianDate to be compared.
Returns:
Boolean true if this JulianDate is chronologically less than or equal toother; otherwise, false.
Example
var start = JulianDate.fromDate(new Date('July 6, 1991 12:00:00'));
var end = JulianDate.fromDate(new Date('July 6, 2011 12:00:00'));
start.lessThanOrEquals(end);     // true
See:

Creates a JavaScript Date representation of this date in UTC. Javascript dates are only accurate to the nearest millisecond.

Returns:
Date A new JavaScript Date equivalent to this JulianDate.

Creates a GregorianDate representation of this date in UTC.

Returns:
GregorianDate A gregorian date.

Creates an ISO8601 string represenation of this JulianDate in UTC.

Parameters:
Name Type Argument Description
precision Number <optional>
The number of fractional digits used to represent the seconds component. By default, the most precise representation is used.
Returns:
String An ISO8601 string represenation of this JulianDate.

<static>

Duplicates a JulianDate instance.

Parameters:
Name Type Argument Description
date Cartesian3 The JulianDate to duplicate.
result Cartesian3 <optional>
The object onto which to store the JulianDate.
Returns:
Cartesian3 The modified result parameter or a new Cartesian3 instance if one was not provided. (Returns undefined if date is undefined)

<static>

Compares two JulianDate instances.

Parameters:
Name Type Description
a JulianDate The first instance.
b JulianDate The second instance.
Returns:
Number A negative value if a is less than b, a positive value if a is greater than b, or zero if a and b are equal.

<static>

Returns true if the first JulianDate equals the second JulianDate.

Parameters:
Name Type Description
left JulianDate The first JulianDate to compare for equality.
right JulianDate The second JulianDate to compare for equality.
Returns:
Boolean true if the JulianDates are equal; otherwise, false.

<static>

Creates a JulianDate instance from a JavaScript Date object. While the JavaScript Date object defaults to the system's local time zone, the JulianDate is computed using the UTC values.

Parameters:
Name Type Argument Default Description
date Date The JavaScript Date object representing the time to be converted to a JulianDate.
timeStandard TimeStandard <optional>
TimeStandard.UTC Indicates the time standard in which this JulianDate is represented.
Throws:
DeveloperError : date must be a valid JavaScript Date.
Returns:
JulianDate The new JulianDate instance.
Example
// Construct a JulianDate specifying the UTC time standard
var date = new Date('January 1, 2011 12:00:00 EST');
var julianDate = JulianDate.fromDate(date, TimeStandard.UTC);
See:

<static>

Creates a JulianDate instance from an ISO 8601 date string. Unlike Date.parse, this method properly accounts for all valid formats defined by the ISO 8601 specification. It also properly handles leap seconds and sub-millisecond times.

Parameters:
Name Type Description
iso8601String String The ISO 8601 date string representing the time to be converted to a JulianDate.
Throws:
DeveloperError : Valid ISO 8601 date string required.
Returns:
JulianDate The new JulianDate instance.
Example
// Example 1. Construct a JulianDate in UTC at April 24th, 2012 6:08PM UTC
var julianDate = JulianDate.fromIso8601('2012-04-24T18:08Z');
// Example 2. Construct a JulianDate in local time April 24th, 2012 12:00 AM
var localDay = JulianDate.fromIso8601('2012-04-24');
// Example 3. Construct a JulianDate 5 hours behind UTC April 24th, 2012 5:00 pm UTC
var localDay = JulianDate.fromIso8601('2012-04-24T12:00-05:00');
See:

<static>

Creates a JulianDate instance from a single number representing the Julian day and fractional day.

Parameters:
Name Type Argument Default Description
totalDays Number The combined Julian Day Number and fractional day.
timeStandard TimeStandard <optional>
TimeStandard.UTC Indicates the time standard in which the first parameter is defined.
Throws:
DeveloperError : totalDays is required.
Returns:
JulianDate The new JulianDate instance.
Example
// Construct a date which corresponds to January 1, 1991 06:00:00 UTC.
var julianDate = JulianDate.fromTotalDays(2448257.75, TimeStandard.UTC);
See: