Calendar2

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.cohort.util
Class Calendar2

java.lang.Object
  com.cohort.util.Calendar2

public class Calendar2
extends java.lang.Object
extends java.lang.Object

This class has static methods for dealing with dates and times.

newGCalendar only accounts for daylight savings if your computer is correctly set up. E.g., in Windows, make sure "Start : Control Panel : Date and Time : Time Zone : Automatically adjust clock for daylight savings changes" is checked. Otherwise, the TimeZone used by GregorianCalendar will be for standard time (not including daylight savings time, if any).

Comments about working with Java's GregorianCalendar class:

GregorianCalendar holds millis since Jan 1, 1970 and a timeZone which influences the values that get/set deal with.
Using a simpleDateFormat to parse a string to a Gregorian Calendar: the simpleDateFormat has a timeZone which specified where the the strings value is from (e.g., 2005-10-31T15:12:10 in PST). When parsed, it is then interpreted by the GregorianCalendar's timeZone (e.g., it was 3pm PST but now I'll treat it as 6pm EST).
Similarly, using a simpleDateFormat to format a Gregorian Calendar to a String: the simpleDateFormat has a timeZone which specified where the the strings value will be for (e.g., 6pm EST will be formatted as 5pm Central).

But this class seeks to simplify things to the more common cases of parsing and formatting using the same time zone as the GregorianCalendar class, and offering GregorianCalendar constructors for Local (with daylight savings if that is what your area does) and Zulu (aka GMT and UTC, which doesn't ever use daylight savings).

A summary of ISO 8601 Date Time formats is at http://www.cl.cam.ac.uk/~mgk25/iso-time.html and http://www.iso.org/iso/date_and_time_format and years B.C at http://www.tondering.dk/claus/cal/node4.html#SECTION00450000000000000000

Calendar2 does not use ERA designations. It uses negative year values for B.C years (calendar2Year = 1 - BCYear). Note that BCYears are 1..., so 1 BC is calendar2Year 0 (or 0000), and 2 BC is calendar2Year -1 (or -0001).

Field Summary
`static int`	`AM_PM`
`static int`	`BC`
`static int`	`DATE`
`static int`	`DAY_OF_YEAR`
`static int`	`DST_OFFSET`
`static int`	`ERA`
`static int`	`HOUR`
`static int`	`HOUR_OF_DAY`
`static java.lang.String[]`	`IDEAL_N_OPTIONS` The IDEAL values are used for makeIdealGC.
`static int[]`	`IDEAL_UNITS_FIELD`
`static java.lang.String[]`	`IDEAL_UNITS_OPTIONS`
`static double[]`	`IDEAL_UNITS_SECONDS`
`static long`	`MILLIS_PER_DAY`
`static long`	`MILLIS_PER_HOUR`
`static long`	`MILLIS_PER_MINUTE`
`static int`	`MILLISECOND`
`static int`	`MINUTE`
`static int`	`MONTH`
`static boolean`	`reallyVerbose` Set this to true (by calling reallyVerbose=true in your program, not but changing the code here) if you want lots of diagnostic messages sent to String2.log.
`static int`	`SECOND`
`static int`	`SECONDS_PER_DAY`
`static int`	`SECONDS_PER_HOUR`
`static int`	`SECONDS_PER_MINUTE`
`static java.lang.String`	`SECONDS_SINCE_1970`
`static boolean`	`verbose` Set this to true (by calling verbose=true in your program, not but changing the code here) if you want lots of diagnostic messages sent to String2.log.
`static int`	`YEAR`
`static int`	`ZONE_OFFSET`
`static java.util.TimeZone`	`zuluTimeZone`

Constructor Summary
`Calendar2()`

Method Summary
`static double`	`backNDays(int nDays, double max)` This returns the start of a day, n days back from max (or from now if max=NaN).
`static int`	`binaryFindClosest(java.lang.String[] isoDates, java.lang.String timeValue)` Find the closest match for timeValue in isoDates which must be sorted in ascending order.
`static int`	`binaryFindFirstGE(java.lang.String[] isoDates, java.lang.String timeValue)` Find the first element which is >= timeValue in isoDates (sorted ascending.
`static int`	`binaryFindLastLE(java.lang.String[] isoDates, java.lang.String timeValue)` Find the last element which is <= timeValue in isoDates (sorted ascending).
`static java.util.GregorianCalendar`	`centerOfMonth(java.util.GregorianCalendar gc)` This converts the date, hour, minute, second so gc is at the exact center of its current month.
`static java.util.GregorianCalendar`	`clearSmallerFields(java.util.GregorianCalendar gc, int field)` This clears the fields smaller than 'field' (e.g., HOUR_OF_DAY clears MINUTE, SECOND, and MILLISECOND, but not HOUR_OF_DAY, MONTH, or YEAR).
`static java.lang.String`	`elapsedTimeString(double millis)` This converts a millis elapsed time value (139872234 ms or 783 ms) to a nice string (e.g., "7h 4m 5s", "5.783 s", or "783 ms").
`static java.lang.String`	`epochHoursToIsoString(int hours)` This converts hours since 1970-01-01T00:00:00Z to an ISO Zulu dateTime String 'T'.
`static java.util.GregorianCalendar`	`epochSecondsToGc(double seconds)` This converts seconds since 1970-01-01T00:00:00Z to a GregorianCalendar.
`static java.lang.String`	`epochSecondsToIsoStringSpace(double seconds)` This converts seconds since 1970-01-01T00:00:00Z to an ISO Zulu dateTime String with space.
`static java.lang.String`	`epochSecondsToIsoStringT(double seconds)` This converts seconds since 1970-01-01T00:00:00Z to an ISO Zulu dateTime String with 'T'.
`static double`	`epochSecondsToUnitsSince(double baseSeconds, double factorToGetSeconds, double epochSeconds)` This converts an epochSeconds value into a unitsSince value.
`static double`	`factorToGetSeconds(java.lang.String units)` This returns the factor to multiply by 'units' data to get seconds data (e.g., "minutes" returns 60).
`static java.lang.String`	`fieldName(int field)` For diagnostic purposes, this returns the name of one of the fields defined above (or "unknown_field").
`static java.lang.String`	`formatAsCompactDateTime(java.util.GregorianCalendar gc)` This returns a compact formatted [-]YYYYMMDDHHMMSS string e.g., "20040102030405" using its current get() values (not influenced by the format's timeZone).
`static java.lang.String`	`formatAsDDMonYYYY(java.util.GregorianCalendar gc)` This returns a DD-Mon-[-]YYYY string e.g., "31-Jul-2004 00:00:00" using its current get() values (not influenced by the format's timeZone).
`static java.lang.String`	`formatAsISODate(java.util.GregorianCalendar gc)` This returns a ISO-style formatted date string e.g., "2004-01-02" using its current get() values (not influenced by the format's timeZone).
`static java.lang.String`	`formatAsIsoDateHM(java.util.GregorianCalendar gc)` This returns a partial ISO-style formatted [-]YYYY-MM-DD HH:MM string e.g., "2004-01-02 03:04" using its current get() values (not influenced by the format's timeZone).
`static java.lang.String`	`formatAsISODateTimeSpace(java.util.GregorianCalendar gc)` This converts a GregorianCalendar object into an ISO-format dateTime string (with space separator: [-]YYYY-MM-DD HH:MM:SS) using its current get() values (not influenced by the format's timeZone).
`static java.lang.String`	`formatAsISODateTimeT(java.util.GregorianCalendar gc)` This converts a GregorianCalendar object into an ISO-format dateTime string (with 'T' separator: [-]YYYY-MM-DDTHH:MM:SS) using its current get() values (not influenced by the format's timeZone).
`static java.lang.String`	`formatAsISOYear(java.util.GregorianCalendar gc)` This returns the year as YYYY.
`static java.lang.String`	`formatAsRFC822GMT(java.util.GregorianCalendar gc)` This returns an RFC 822 format date time string ("Sun, 06 Nov 1994 08:49:37 GMT").
`static java.lang.String`	`formatAsUSSlash24(java.util.GregorianCalendar gc)` This returns a US-style slash format date 24-hour time string ("1/20/2006 21:00:00") (commonly used by Microsoft Access).
`static java.lang.String`	`formatAsUSSlashAmPm(java.util.GregorianCalendar gc)` This returns a US-style slash format date time string ("1/20/2006 9:00:00 pm").
`static java.lang.String`	`formatAsYYYYDDD(java.util.GregorianCalendar gc)` This returns a [-]YYYYDDD string e.g., "2004001" using its current get() values (not influenced by the format's timeZone).
`static java.lang.String`	`formatAsYYYYMM(java.util.GregorianCalendar gc)` This returns a [-]YYYYMM string e.g., "200401" using its current get() values (not influenced by the format's timeZone).
`static double`	`gcToEpochSeconds(java.util.GregorianCalendar gc)` This converts a GregorianCalendar to seconds since 1970-01-01T00:00:00Z.
`static java.lang.String`	`getCurrentISODateStringLocal()` This returns the current local date in ISO format.
`static java.lang.String`	`getCurrentISODateStringZulu()` This returns the current Zulu date in ISO format.
`static java.lang.String`	`getCurrentISODateTimeStringLocal()` This returns the current local dateTime in ISO T format.
`static java.lang.String`	`getCurrentISODateTimeStringZulu()` This returns the current Zulu dateTime in ISO T format.
`static java.lang.String`	`getCurrentRFC822Zulu()` This returns the current Zulu date in RFC 822 format.
`static java.lang.String`	`getMonthName(int month)` This returns the full month name (e.g., "January").
`static java.lang.String`	`getMonthName3(int month)` This returns a 3 character month name (eg.
`static double[]`	`getNEvenlySpaced(double start, double stop, int maxNValues)` This returns a double[] of maxNValues (or fewer) evenly spaced, between start and stop.
`static java.lang.String`	`getParseErrorString(java.lang.String s, java.lang.Exception e)` This returns an error message indicating that the specified isoDateString couldn't be parsed.
`static double[]`	`getTimeBaseAndFactor(java.lang.String tsUnits)` This converts a string "[units] since [isoDate]" (e.g., "minutes since 1985-01-01") into a baseSeconds (seconds since 1970-01-01) and a factor ("minutes" returns 60).
`static int`	`getYear(java.util.GregorianCalendar gc)` This returns the year.
`static boolean`	`isIsoDate(java.lang.String s)` This returns true if the string appears to be an ISO date/time (matching YYYY-MM...).
`static java.util.GregorianCalendar`	`isoDateTimeAdd(java.lang.String isoDate, int n, int field)` This adds the specified n field's to the isoDate, and returns the resulting GregorianCalendar object.
`static int`	`isoStringToEpochHours(java.lang.String isoZuluString)` This converts an ISO Zulu dateTime String to hours since 1970-01-01T00:00:00Z, rounded to the nearest hour.
`static double`	`isoStringToEpochSeconds(java.lang.String isoZuluString)` This converts an ISO Zulu dateTime String to seconds since 1970-01-01T00:00:00Z, rounded to the nearest milli, then remove millis.
`static long`	`isoZuluStringToMillis(java.lang.String s)` This converts an ISO Zulu DateTime string to millis since 1970-01-01T00:00:00Z.
`static java.lang.String`	`millisToIsoZuluString(long millis)` This converts millis since 1970-01-01T00:00:00Z to an ISO Zulu DateTime string.
`static java.util.GregorianCalendar`	`newGCalendarLocal()` This returns a gregorianCalendar object which has the correct current time (e.g., wall clock time, for the local time zone, which includes daylight savings, if applicable) and the local time zone.
`static java.util.GregorianCalendar`	`newGCalendarLocal(int year, int dayOfYear)` Get a GregorianCalendar object (local time zone) for the specified time.
`static java.util.GregorianCalendar`	`newGCalendarLocal(int year, int month, int dayOfMonth)` Get a GregorianCalendar object (local time zone) for the specified.
`static java.util.GregorianCalendar`	`newGCalendarLocal(int year, int month, int dayOfMonth, int hour, int minute, int second, int millis)` Get a GregorianCalendar object (local time zone) for the specified time.
`static java.util.GregorianCalendar`	`newGCalendarZulu()` Get a GregorianCalendar object with the current UTC (A.K.A., GMT or Zulu) time and a UTC time zone.
`static java.util.GregorianCalendar`	`newGCalendarZulu(int year, int dayOfYear)` Get a GregorianCalendar object (Zulu time zone) for the specified time.
`static java.util.GregorianCalendar`	`newGCalendarZulu(int year, int month, int dayOfMonth)` Get a GregorianCalendar object (Zulu time zone) for the specified time.
`static java.util.GregorianCalendar`	`newGCalendarZulu(int year, int month, int dayOfMonth, int hour, int minute, int second, int millis)` Get a GregorianCalendar object (Zulu time zone) for the specified time.
`static java.util.GregorianCalendar`	`newGCalendarZulu(long millis)` Get a GregorianCalendar object with the specified millis time (UTC) and a UTC time zone.
`static int`	`nextNice(double d, int[] nice)` This returns the value in nice which is >= d, or a multiple of the last value which is higher than d.
`static java.util.GregorianCalendar`	`parseCompactDateTime(java.util.GregorianCalendar gc, java.lang.String s)` This converts compact string (must be [-]YYYYMMDD, [-]YYYYMMDDhh, [-]YYYYMMDDhhmm, or [-]YYYYMMDDhhmmss) into a GregorianCalendar object.
`static java.util.GregorianCalendar`	`parseCompactDateTimeZulu(java.lang.String s)` This is like parseCompactDateTime, but assumes the time zone is Zulu.
`static java.util.GregorianCalendar`	`parseDDMonYYYY(java.util.GregorianCalendar gc, java.lang.String s)` This converts a DD-Mon-[-]YYYY string e.g., "31-Jul-2004 00:00:00" into a GregorianCalendar object.
`static java.util.GregorianCalendar`	`parseDDMonYYYYZulu(java.lang.String s)` This is like parseDDMonYYYY, but assumes the time zone is Zulu.
`static java.util.GregorianCalendar`	`parseISODateTime(java.util.GregorianCalendar gc, java.lang.String s)` This converts an ISO date time string ([-]YYYY-MM-DDTHH:MM:SS.SS�ZZ:ZZ) into a GregorianCalendar object.
`static java.util.GregorianCalendar`	`parseISODateTimeZulu(java.lang.String s)` This converts an ISO ZULU date time string ([-]YYYY-MM-DDTHH:MM:SS�ZZ:ZZ) into a GregorianCalendar object.
`static java.util.GregorianCalendar`	`parseUSSlash24(java.util.GregorianCalendar gc, java.lang.String s)` This converts a US slash 24 hour string ("1/20/2006" or "1/20/2006 14:23:59") (commonly used by Microsoft Access) into a GregorianCalendar object.
`static java.util.GregorianCalendar`	`parseUSSlash24Zulu(java.lang.String s)` This is like parseUSSlash24, but assumes the time zone is Zulu.
`static java.util.GregorianCalendar`	`parseYYYYDDD(java.util.GregorianCalendar gc, java.lang.String s)` This converts a [-]YYYYDDD string into a GregorianCalendar object.
`static java.util.GregorianCalendar`	`parseYYYYDDDZulu(java.lang.String s)` This is like parseYYYYDDD, but assumes the time zone is Zulu.
`static java.lang.String`	`removeSpacesDashesColons(java.lang.String s)` Remove any spaces, dashes (except optional initial dash), colons, and T's from s.
`static java.util.GregorianCalendar`	`roundToIdealGC(double epochSeconds, int idealN, int idealUnits)` This rounds to the nearest idealN, idealUnits (e.g., 2 months) (starting at Jan 1, 0000).
`static java.lang.String`	`safeEpochSecondsToIsoStringT(double seconds, java.lang.String NaNString)` This is like epochSecondsToIsoStringT, but returns NaNString if seconds is NaN.
`static java.lang.String`	`safeEpochSecondsToIsoStringTZ(double seconds, java.lang.String NaNString)` This is like epochSecondsToIsoStringT, but add "Z" at end of time, and returns NaNString if seconds is NaN..
`static double`	`safeIsoStringToEpochSeconds(java.lang.String isoZuluString)` This is like isoStringToEpochSeconds, but returns NaN if trouble.
`static double`	`unitsSinceToEpochSeconds(double baseSeconds, double factorToGetSeconds, double unitsSince)` This converts a unitsSince value into epochSeconds.
`static java.lang.String`	`yyyydddToIsoDate(java.lang.String s)` Convert a String with [-]yyyyddd to a String with YYYY-mm-dd.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

ERA

public static final int ERA

See Also:: Constant Field Values

BC

public static final int BC

See Also:: Constant Field Values

YEAR

public static final int YEAR

See Also:: Constant Field Values

MONTH

public static final int MONTH

See Also:: Constant Field Values

DATE

public static final int DATE

See Also:: Constant Field Values

DAY_OF_YEAR

public static final int DAY_OF_YEAR

See Also:: Constant Field Values

HOUR

public static final int HOUR

See Also:: Constant Field Values

HOUR_OF_DAY

public static final int HOUR_OF_DAY

See Also:: Constant Field Values

MINUTE

public static final int MINUTE

See Also:: Constant Field Values

SECOND

public static final int SECOND

See Also:: Constant Field Values

MILLISECOND

public static final int MILLISECOND

See Also:: Constant Field Values

AM_PM

public static final int AM_PM

See Also:: Constant Field Values

ZONE_OFFSET

public static final int ZONE_OFFSET

See Also:: Constant Field Values

DST_OFFSET

public static final int DST_OFFSET

See Also:: Constant Field Values

SECONDS_PER_MINUTE

public static final int SECONDS_PER_MINUTE

See Also:: Constant Field Values

SECONDS_PER_HOUR

public static final int SECONDS_PER_HOUR

See Also:: Constant Field Values

SECONDS_PER_DAY

public static final int SECONDS_PER_DAY

See Also:: Constant Field Values

MILLIS_PER_MINUTE

public static final long MILLIS_PER_MINUTE

See Also:: Constant Field Values

MILLIS_PER_HOUR

public static final long MILLIS_PER_HOUR

See Also:: Constant Field Values

MILLIS_PER_DAY

public static final long MILLIS_PER_DAY

See Also:: Constant Field Values

SECONDS_SINCE_1970

public static final java.lang.String SECONDS_SINCE_1970

See Also:: Constant Field Values

zuluTimeZone

public static final java.util.TimeZone zuluTimeZone

IDEAL_N_OPTIONS

public static java.lang.String[] IDEAL_N_OPTIONS

The IDEAL values are used for makeIdealGC.

IDEAL_UNITS_OPTIONS

public static java.lang.String[] IDEAL_UNITS_OPTIONS

IDEAL_UNITS_SECONDS

public static double[] IDEAL_UNITS_SECONDS

IDEAL_UNITS_FIELD

public static int[] IDEAL_UNITS_FIELD

verbose

public static boolean verbose

Set this to true (by calling verbose=true in your program, not but changing the code here) if you want lots of diagnostic messages sent to String2.log.

reallyVerbose

public static boolean reallyVerbose

Set this to true (by calling reallyVerbose=true in your program, not but changing the code here) if you want lots of diagnostic messages sent to String2.log.

Constructor Detail

Calendar2

public Calendar2()

Method Detail

fieldName

public static java.lang.String fieldName(int field)

For diagnostic purposes, this returns the name of one of the fields defined above (or "unknown_field").

Parameters:: field -
Returns:: the name of the field

getTimeBaseAndFactor

public static double[] getTimeBaseAndFactor(java.lang.String tsUnits)
                                     throws java.lang.Exception

This converts a string "[units] since [isoDate]" (e.g., "minutes since 1985-01-01") into a baseSeconds (seconds since 1970-01-01) and a factor ("minutes" returns 60).
So simplistically, epochSeconds = storedTime * factor + baseSeconds.
Or simplistically, storedTime = (epochSeconds - baseSeconds) / factor.

WARNING: don't use the equations above. Use unitsSinceToEpochSeconds or epochSecondsToUnitsSince which correctly handle special cases.

Parameters:: tsUnits - e.g., "minutes since 1985-01-01"
Returns:: double[]{baseSeconds, factorToGetSeconds}
Throws:: java.lang.Exception - if trouble (tsUnits is null or invalid)

unitsSinceToEpochSeconds

public static double unitsSinceToEpochSeconds(double baseSeconds,
                                              double factorToGetSeconds,
                                              double unitsSince)

This converts a unitsSince value into epochSeconds. This properly handles 'special' factorToGetSeconds values (for month and year).

Parameters:: baseSeconds -; factorToGetSeconds -; unitsSince -
Returns:: seconds since 1970-01-01 (or NaN if unitsSince is NaN)

epochSecondsToUnitsSince

public static double epochSecondsToUnitsSince(double baseSeconds,
                                              double factorToGetSeconds,
                                              double epochSeconds)

This converts an epochSeconds value into a unitsSince value. This properly handles 'special' factorToGetSeconds values (for month and year).

Parameters:: baseSeconds -; factorToGetSeconds -; epochSeconds -
Returns:: seconds since 1970-01-01 (or NaN if epochSeconds is NaN)

factorToGetSeconds

public static double factorToGetSeconds(java.lang.String units)
                                 throws java.lang.Exception

This returns the factor to multiply by 'units' data to get seconds data (e.g., "minutes" returns 60). This is used for part of dealing with udunits-style "minutes since 1970-01-01"-style strings.

Parameters:: units -
Returns:: the factor to multiply by 'units' data to get seconds data. Since there is no exact value for months or years, this returns special values of 30*SECONDS_PER_DAY and 360*SECONDS_PER_DAY, respectively.
Throws:: java.lang.Exception - if trouble (e.g., units is null or not an expected value)

isoStringToEpochSeconds

public static double isoStringToEpochSeconds(java.lang.String isoZuluString)

This converts an ISO Zulu dateTime String to seconds since 1970-01-01T00:00:00Z, rounded to the nearest milli, then remove millis. In many ways trunc would be better, but doubles are often bruised. round works symmetrically with + and - numbers. If any of the end of the dateTime is missing, a trailing portion of "1970-01-01T00:00:00" is added. The 'T' connector can be any non-digit. If there is extra info at the end (e.g., "Z") it is ignored. FUTURE: would be nice if it supported time zone info like "Z" and "+08:00".

Parameters:: isoZuluString -
Returns:: seconds
Throws:: exception - if trouble (e.g., input is null or invalid format)

safeIsoStringToEpochSeconds

public static double safeIsoStringToEpochSeconds(java.lang.String isoZuluString)

This is like isoStringToEpochSeconds, but returns NaN if trouble.

isIsoDate

public static boolean isIsoDate(java.lang.String s)

This returns true if the string appears to be an ISO date/time (matching YYYY-MM...).

Parameters:: s -
Returns:: true if the string appears to be an ISO date/time (matching YYYY-MM...).

gcToEpochSeconds

public static double gcToEpochSeconds(java.util.GregorianCalendar gc)

This converts a GregorianCalendar to seconds since 1970-01-01T00:00:00Z. Note that System.currentTimeMillis/1000 = epochSeconds(zulu).

Parameters:: gc -
Returns:: seconds, including fractional seconds (Double.NaN if trouble)
Throws:: exception - if trouble (e.g., gc is null)

epochSecondsToGc

public static java.util.GregorianCalendar epochSecondsToGc(double seconds)

This converts seconds since 1970-01-01T00:00:00Z to a GregorianCalendar.

Parameters:: seconds - (including fractional seconds)
Returns:: an iso zulu time-zone GregorianCalendar (rounded to nearest ms)
Throws:: exception - if trouble (e.g., seconds is NaN)

isoStringToEpochHours

public static int isoStringToEpochHours(java.lang.String isoZuluString)

This converts an ISO Zulu dateTime String to hours since 1970-01-01T00:00:00Z, rounded to the nearest hour. In many ways trunc would be better, but doubles are often bruised. round works symmetrically with + and - numbers. If any of the end of the dateTime is missing, a trailing portion of "1970-01-01T00:00:00" is added. The 'T' connector can be any non-digit. If there is extra info at the end (e.g., "Z") it is ignored.

Parameters:: isoZuluString -
Returns:: seconds
Throws:: java.lang.Exception - if trouble (e.g., input is null or invalid format)

epochSecondsToIsoStringT

public static java.lang.String epochSecondsToIsoStringT(double seconds)

This converts seconds since 1970-01-01T00:00:00Z to an ISO Zulu dateTime String with 'T'. The doubles are rounded to the nearest second. In many ways trunc would be better, but doubles are often bruised. round works symmetrically with + and - numbers.

Parameters:: seconds - with optional fractional part
Returns:: isoZuluString with 'T'.
Throws:: java.lang.Exception - if trouble (e.g., seconds is NaN)

safeEpochSecondsToIsoStringT

public static java.lang.String safeEpochSecondsToIsoStringT(double seconds,
                                                            java.lang.String NaNString)

This is like epochSecondsToIsoStringT, but returns NaNString if seconds is NaN.

safeEpochSecondsToIsoStringTZ

public static java.lang.String safeEpochSecondsToIsoStringTZ(double seconds,
                                                             java.lang.String NaNString)

This is like epochSecondsToIsoStringT, but add "Z" at end of time, and returns NaNString if seconds is NaN..

epochSecondsToIsoStringSpace

public static java.lang.String epochSecondsToIsoStringSpace(double seconds)

This converts seconds since 1970-01-01T00:00:00Z to an ISO Zulu dateTime String with space. The doubles are rounded to the nearest milli, then millis removed. In many ways trunc would be better, but doubles are often bruised. round works symmetrically with + and - numbers.

Parameters:: seconds - with optional fractional part
Returns:: isoZuluString with space.
Throws:: java.lang.Exception - if trouble (e.g., seconds is NaN)

epochHoursToIsoString

public static java.lang.String epochHoursToIsoString(int hours)

This converts hours since 1970-01-01T00:00:00Z to an ISO Zulu dateTime String 'T'. If your hours are doubles, use Math2.roundToInt first. In many ways trunc would be better, but doubles are often bruised. round works symmetrically with + and - numbers.

Parameters:: hours -
Returns:: isoZuluString 'T'. If hours==Integer.MAX_VALUE, this returns null.
Throws:: java.lang.Exception - if trouble (e.g., hours is Integer.MAX_VALUE)

getMonthName3

public static java.lang.String getMonthName3(int month)

This returns a 3 character month name (eg. "Jan").

Parameters:: month - 1..12
Throws:: java.lang.Exception - if month is out of range

getMonthName

public static java.lang.String getMonthName(int month)

This returns the full month name (e.g., "January").

Parameters:: month - 1..12
Throws:: java.lang.Exception - if month is out of range

newGCalendarLocal

public static java.util.GregorianCalendar newGCalendarLocal()

This returns a gregorianCalendar object which has the correct current time (e.g., wall clock time, for the local time zone, which includes daylight savings, if applicable) and the local time zone.

Returns:: a new GregorianCalendar object (local time zone)

newGCalendarZulu

public static java.util.GregorianCalendar newGCalendarZulu()

Get a GregorianCalendar object with the current UTC (A.K.A., GMT or Zulu) time and a UTC time zone. You can find the current Zulu/GMT time at: http://www.xav.com/time.cgi Info about UTC vs GMT vs TAI... see http://www.leapsecond.com/java/gpsclock.htm. And there was another good site... can't find it.

Returns:: the GregorianCalendar object for right now (Zulu time zone)

newGCalendarZulu

public static java.util.GregorianCalendar newGCalendarZulu(long millis)

Get a GregorianCalendar object with the specified millis time (UTC) and a UTC time zone.

Returns:: the GregorianCalendar object.
Throws:: java.lang.Exception - if trouble (e.g., millis == Long.MAX_VALUE)

newGCalendarLocal

public static java.util.GregorianCalendar newGCalendarLocal(int year,
                                                            int month,
                                                            int dayOfMonth)

Get a GregorianCalendar object (local time zone) for the specified. [Currently, it is lenient -- e.g., Dec 32 -> Jan 1 of the next year.] Information can be retrieved via calendar.get(Calendar.XXXX), where XXXX is one of the Calendar constants, like DAY_OF_YEAR.

Parameters:: year - (e.g., 2005); month - (1..12) (this is consciously different than Java's standard); dayOfMonth - (1..31)
Returns:: the corresponding GregorianCalendar object (local time zone)
Throws:: java.lang.Exception - if trouble (e.g., year is Integer.MAX_VALUE)

newGCalendarZulu

public static java.util.GregorianCalendar newGCalendarZulu(int year,
                                                           int month,
                                                           int dayOfMonth)

Get a GregorianCalendar object (Zulu time zone) for the specified time. [Currently, it is lenient -- e.g., Dec 32 -> Jan 1 of the next year.] Information can be retrieved via calendar.get(Calendar.XXXX), where XXXX is one of the Calendar constants, like DAY_OF_YEAR.

Parameters:: year - (e.g., 2005); month - (1..12) (this is consciously different than Java's standard); dayOfMonth - (1..31)
Returns:: the corresponding GregorianCalendar object (Zulu time zone)
Throws:: java.lang.Exception - if trouble (e.g., year is Integer.MAX_VALUE)

newGCalendarLocal

public static java.util.GregorianCalendar newGCalendarLocal(int year,
                                                            int month,
                                                            int dayOfMonth,
                                                            int hour,
                                                            int minute,
                                                            int second,
                                                            int millis)

Get a GregorianCalendar object (local time zone) for the specified time. [Currently, it is lenient -- e.g., Dec 32 -> Jan 1 of the next year.] Information can be retrieved via calendar.get(Calendar.XXXX), where XXXX is one of the Calendar constants, like DAY_OF_YEAR.

Parameters:: year - (e.g., 2005); month - (1..12) (this is consciously different than Java's standard); dayOfMonth - (1..31); hour - (0..23); minute - (0..59); second - (0..59); millis - (0..999)
Returns:: the corresponding GregorianCalendar object (local time zone)
Throws:: java.lang.Exception - if trouble (e.g., year is Integer.MAX_VALUE)

newGCalendarZulu

public static java.util.GregorianCalendar newGCalendarZulu(int year,
                                                           int month,
                                                           int dayOfMonth,
                                                           int hour,
                                                           int minute,
                                                           int second,
                                                           int millis)

Parameters:: year - (e.g., 2005); month - (1..12) (this is consciously different than Java's standard); dayOfMonth - (1..31); hour - (0..23); minute - (0..59); second - (0..59); millis - (0..999)
Returns:: the corresponding GregorianCalendar object (Zulu time zone)
Throws:: java.lang.Exception - if trouble (e.g., year is Integer.MAX_VALUE)

newGCalendarLocal

public static java.util.GregorianCalendar newGCalendarLocal(int year,
                                                            int dayOfYear)

Get a GregorianCalendar object (local time zone) for the specified time. [Currently, it is lenient -- e.g., day 366 -> Jan 1 of the next year.] Information can be retrieved via calendar.get(Calendar.XXXX), where XXXX is one of the Calendar constants, like DAY_OF_YEAR.

Parameters:: year - (e.g., 2005); dayOfYear - (usually 1..365, but 1..366 in leap years)
Returns:: the corresponding GregorianCalendar object (local time zone)
Throws:: java.lang.Exception - if trouble (e.g., year is Integer.MAX_VALUE)

newGCalendarZulu

public static java.util.GregorianCalendar newGCalendarZulu(int year,
                                                           int dayOfYear)

Get a GregorianCalendar object (Zulu time zone) for the specified time. [Currently, it is lenient -- e.g., day 366 -> Jan 1 of the next year.] Information can be retrieved via calendar.get(Calendar.XXXX), where XXXX is one of the Calendar constants, like DAY_OF_YEAR.

Parameters:: year - (e.g., 2005); dayOfYear - (usually 1..365, but 1..366 in leap years)
Returns:: the corresponding GregorianCalendar object (Zulu time zone)
Throws:: java.lang.Exception - if trouble (e.g., year is Integer.MAX_VALUE)

getYear

public static int getYear(java.util.GregorianCalendar gc)

This returns the year. For years B.C., this returns Calendar2Year = 1 - BCYear. Note that BCYears are 1..., so 1 BC is calendar2Year 0, and 2 BC is calendar2Year -1.

Parameters:: gc -
Returns:: the year (negative for BC).

formatAsISOYear

public static java.lang.String formatAsISOYear(java.util.GregorianCalendar gc)

This returns the year as YYYY. For years B.C., this returns Calendar2Year = 1 - BCYear. Note that BCYears are 1..., so 1 BC is calendar2Year 0000, and 2 BC is calendar2Year -0001.

Parameters:: gc -
Returns:: the year as YYYY (or -YYYY for BC).

formatAsISODate

public static java.lang.String formatAsISODate(java.util.GregorianCalendar gc)

This returns a ISO-style formatted date string e.g., "2004-01-02" using its current get() values (not influenced by the format's timeZone).

Parameters:: gc - a GregorianCalendar object
Returns:: the date in gc, formatted as (for example) "2004-01-02"
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsISODateTimeT

public static java.lang.String formatAsISODateTimeT(java.util.GregorianCalendar gc)

This converts a GregorianCalendar object into an ISO-format dateTime string (with 'T' separator: [-]YYYY-MM-DDTHH:MM:SS) using its current get() values (not influenced by the format's timeZone). [was calendarToString]

Parameters:: gc -
Returns:: the corresponding dateTime String.
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsISODateTimeSpace

public static java.lang.String formatAsISODateTimeSpace(java.util.GregorianCalendar gc)

This converts a GregorianCalendar object into an ISO-format dateTime string (with space separator: [-]YYYY-MM-DD HH:MM:SS) using its current get() values (not influenced by the format's timeZone). [was calendarToString]

Parameters:: gc -
Returns:: the corresponding dateTime String.
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsIsoDateHM

public static java.lang.String formatAsIsoDateHM(java.util.GregorianCalendar gc)

This returns a partial ISO-style formatted [-]YYYY-MM-DD HH:MM string e.g., "2004-01-02 03:04" using its current get() values (not influenced by the format's timeZone).

Parameters:: gc - a GregorianCalendar object
Returns:: the date in gc, formatted as (for example) "2004-01-02 03:04".
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsCompactDateTime

public static java.lang.String formatAsCompactDateTime(java.util.GregorianCalendar gc)

This returns a compact formatted [-]YYYYMMDDHHMMSS string e.g., "20040102030405" using its current get() values (not influenced by the format's timeZone).

Parameters:: gc - a GregorianCalendar object
Returns:: the date in gc, formatted as (for example) "20040102030405".
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsYYYYDDD

public static java.lang.String formatAsYYYYDDD(java.util.GregorianCalendar gc)

This returns a [-]YYYYDDD string e.g., "2004001" using its current get() values (not influenced by the format's timeZone).

Parameters:: gc - a GregorianCalendar object
Returns:: the date in gc, formatted as (for example) "2004001".
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsYYYYMM

public static java.lang.String formatAsYYYYMM(java.util.GregorianCalendar gc)

This returns a [-]YYYYMM string e.g., "200401" using its current get() values (not influenced by the format's timeZone).

Parameters:: gc - a GregorianCalendar object
Returns:: the date in gc, formatted as (for example) "200401".
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsDDMonYYYY

public static java.lang.String formatAsDDMonYYYY(java.util.GregorianCalendar gc)

This returns a DD-Mon-[-]YYYY string e.g., "31-Jul-2004 00:00:00" using its current get() values (not influenced by the format's timeZone). Ferret often uses this format.

Parameters:: gc - a GregorianCalendar object
Returns:: the date in gc, formatted as (for example) "31-Jul-2004 00:00:00".
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsUSSlashAmPm

public static java.lang.String formatAsUSSlashAmPm(java.util.GregorianCalendar gc)

This returns a US-style slash format date time string ("1/20/2006 9:00:00 pm").

Parameters:: gc - a GregorianCalendar object. The dateTime will be interpreted as being in gc's time zone.
Returns:: gc in the US slash format ("1/20/2006 9:00:00 pm").
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsRFC822GMT

public static java.lang.String formatAsRFC822GMT(java.util.GregorianCalendar gc)

This returns an RFC 822 format date time string ("Sun, 06 Nov 1994 08:49:37 GMT").

Parameters:: gc - a GregorianCalendar object. The dateTime will be interpreted as being in the gc's time zone (which should always be GMT because "GMT" is put at the end).
Returns:: gc in the RFC 822 format ("Sun, 06 Nov 1994 08:49:37 GMT").
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

formatAsUSSlash24

public static java.lang.String formatAsUSSlash24(java.util.GregorianCalendar gc)

This returns a US-style slash format date 24-hour time string ("1/20/2006 21:00:00") (commonly used by Microsoft Access).

Parameters:: gc - a GregorianCalendar object. The dateTime will be interpreted as being in gc's time zone.
Returns:: gc in the US slash date 24 hour format ("1/20/2006 21:00:00").
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

parseISODateTime

public static java.util.GregorianCalendar parseISODateTime(java.util.GregorianCalendar gc,
                                                           java.lang.String s)

This converts an ISO date time string ([-]YYYY-MM-DDTHH:MM:SS.SS�ZZ:ZZ) into a GregorianCalendar object.
It is lenient; so Jan 32 is converted to Feb 1;
The 'T' may be any non-digit.
This tries hard to be tolerant of non-valid formats (e.g., "1971-1-2", "1971-01")
As of 11/9/2006, NO LONGER TRUE: If year is 0..49, it is assumed to be 2000..2049.
As of 11/9/2006, NO LONGER TRUE: If year is 50..99, it is assumed to be 1950..1999.
If the string is too short, the end of "1970-01-01T00:00:00" will be added (effectively).
If the string is too long, the excess will be ignored.
If a separator is invalid, no more fields will be read.
Otherwise, if the date is improperly formatted, it returns null.
Timezone "Z" or "" is treated as "-00:00" (UTC/Zulu time)
Timezones: 2007-01-02T03:04:05-01:00 is same as 2007-01-02T04:04:05

Parameters:: gc - a GregorianCalendar object. The dateTime will be interpreted as being in gc's time zone. Timezone info is relative to the gc's time zone.; s - the dateTimeString in the ISO format (YYYY-MM-DDTHH:MM:SS�ZZ:ZZ or -YYYY-MM-DDTHH:MM:SS�ZZ:ZZ for years B.C.) For years B.C., use calendar2Year = 1 - BCYear. Note that BCYears are 1..., so 1 BC is calendar2Year 0 (or 0000), and 2 BC is calendar2Year -1 (or -0001).
Returns:: the same GregorianCalendar object, but with the date info
Throws:: java.lang.Exception - if trouble (e.g., gc is null or s is null or not at least #)

parseISODateTimeZulu

public static java.util.GregorianCalendar parseISODateTimeZulu(java.lang.String s)

This converts an ISO *ZULU* date time string ([-]YYYY-MM-DDTHH:MM:SS�ZZ:ZZ) into a GregorianCalendar object. See parseISODateTime documentation.

Parameters:: s - the dateTimeString in the ISO format ([-]YYYY-MM-DDTHH:MM:SS)
Returns:: a GregorianCalendar object
Throws:: java.lang.Exception - if trouble (e.g., s is null or not at least #)

parseUSSlash24

public static java.util.GregorianCalendar parseUSSlash24(java.util.GregorianCalendar gc,
                                                         java.lang.String s)

This converts a US slash 24 hour string ("1/20/2006" or "1/20/2006 14:23:59") (commonly used by Microsoft Access) into a GregorianCalendar object.
It is lenient; so Jan 32 is converted to Feb 1.
If year is 0..49, it is assumed to be 2000..2049.
If year is 50..99, it is assumed to be 1950..1999.
The year may be negative (calendar2Year = 1 - BCYear). (But 0 - 24 assumed to be 2000 - 2049!)
There must be at least #/#/#, or this returns null.
The time is optional; if absent, it is assumed to be 00:00:00

Parameters:: gc - a GregorianCalendar object. The dateTime will be interpreted as being in gc's time zone.; s - the dateString in the US slash format ("1/20/2006" or "1/20/2006 14:23:59")
Returns:: the same GregorianCalendar object, but with the date info
Throws:: java.lang.Exception - if trouble (e.g., gc is null or s is null or not at least #/#/#)

parseUSSlash24Zulu

public static java.util.GregorianCalendar parseUSSlash24Zulu(java.lang.String s)

This is like parseUSSlash24, but assumes the time zone is Zulu.

Throws:: java.lang.Exception - if trouble (e.g., s is null or not at least #/#/#)

parseCompactDateTime

public static java.util.GregorianCalendar parseCompactDateTime(java.util.GregorianCalendar gc,
                                                               java.lang.String s)

This converts compact string (must be [-]YYYYMMDD, [-]YYYYMMDDhh, [-]YYYYMMDDhhmm, or [-]YYYYMMDDhhmmss) into a GregorianCalendar object. It is lenient; so Jan 32 is converted to Feb 1. If the date is improperly formatted, it returns null.

Parameters:: gc - a GregorianCalendar object. The dateTime will be interpreted as being in gc's time zone.; s - dateTimeString in compact format (must be [-]YYYYMMDD, [-]YYYYMMDDhh, [-]YYYYMMDDhhmm, or [-]YYYYMMDDhhmmss)
Returns:: the same GregorianCalendar object, but with the date info
Throws:: java.lang.Exception - if trouble (e.g., gc is null or s is null or not at least YYYYMMDD)

parseCompactDateTimeZulu

public static java.util.GregorianCalendar parseCompactDateTimeZulu(java.lang.String s)

This is like parseCompactDateTime, but assumes the time zone is Zulu.

Throws:: java.lang.Exception - if trouble (e.g., s is null or invalid)

parseDDMonYYYY

public static java.util.GregorianCalendar parseDDMonYYYY(java.util.GregorianCalendar gc,
                                                         java.lang.String s)

This converts a DD-Mon-[-]YYYY string e.g., "31-Jul-2004 00:00:00" into a GregorianCalendar object. It is lenient; so day 0 is converted to Dec 31 of previous year. If the date is shortenend, this does the best it can, or returns null. Ferret often uses this format.

Parameters:: gc - a GregorianCalendar object. The dateTime will be interpreted as being in gc's time zone.; s - dateTimeString in YYYYDDD format
Returns:: the same GregorianCalendar object, but with the date info
Throws:: java.lang.Exception - if trouble (e.g., gc is null or s is null or not DDMonYYYY)

parseDDMonYYYYZulu

public static java.util.GregorianCalendar parseDDMonYYYYZulu(java.lang.String s)

This is like parseDDMonYYYY, but assumes the time zone is Zulu.

Throws:: java.lang.Exception - if trouble (e.g., s is null or invalid)

parseYYYYDDD

public static java.util.GregorianCalendar parseYYYYDDD(java.util.GregorianCalendar gc,
                                                       java.lang.String s)

This converts a [-]YYYYDDD string into a GregorianCalendar object. It is lenient; so day 0 is converted to Dec 31 of previous year. If the date is improperly formatted, this does the best it can, or returns null.

Parameters:: gc - a GregorianCalendar object. The dateTime will be interpreted as being in gc's time zone.; s - dateTimeString in YYYYDDD format
Returns:: the same GregorianCalendar object, but with the date info
Throws:: java.lang.Exception - if trouble (e.g., gc is null or s is null or not YYYYDDDD)

parseYYYYDDDZulu

public static java.util.GregorianCalendar parseYYYYDDDZulu(java.lang.String s)

This is like parseYYYYDDD, but assumes the time zone is Zulu.

Throws:: java.lang.Exception - if trouble (e.g., s is null or not YYYYDDD)

getParseErrorString

public static java.lang.String getParseErrorString(java.lang.String s,
                                                   java.lang.Exception e)

This returns an error message indicating that the specified isoDateString couldn't be parsed.

Parameters:: s - dateTimeString; e - a Exception
Returns:: an error string

yyyydddToIsoDate

public static java.lang.String yyyydddToIsoDate(java.lang.String s)

Convert a String with [-]yyyyddd to a String with YYYY-mm-dd. This works the same for Local or Zulu or other time zones.

Parameters:: s - a String with a date in the form yyyyddd
Returns:: the date formatted as YYYY-mm-dd
Throws:: java.lang.Exception - if trouble (e.g., s is null or not YYYYDDD)

getCurrentISODateTimeStringLocal

public static java.lang.String getCurrentISODateTimeStringLocal()

This returns the current local dateTime in ISO T format.

Returns:: the current local dateTime in ISO T format

getCurrentISODateTimeStringZulu

public static java.lang.String getCurrentISODateTimeStringZulu()

This returns the current Zulu dateTime in ISO T format.

Returns:: the current Zulu dateTime in ISO T format

getCurrentRFC822Zulu

public static java.lang.String getCurrentRFC822Zulu()

This returns the current Zulu date in RFC 822 format.

Returns:: the current Zulu date in RFC 822 format

getCurrentISODateStringZulu

public static java.lang.String getCurrentISODateStringZulu()

This returns the current Zulu date in ISO format.

Returns:: the current Zulu date in ISO format

getCurrentISODateStringLocal

public static java.lang.String getCurrentISODateStringLocal()

This returns the current local date in ISO format.

Returns:: the current local date in ISO format

isoZuluStringToMillis

public static long isoZuluStringToMillis(java.lang.String s)

This converts an ISO Zulu DateTime string to millis since 1970-01-01T00:00:00Z.

Parameters:: s - the ISO Zulu DateTime string
Returns:: the millis since 1970-01-01T00:00:00Z
Throws:: java.lang.Exception - if trouble (e.g., s is null or not at least #)

millisToIsoZuluString

public static java.lang.String millisToIsoZuluString(long millis)

This converts millis since 1970-01-01T00:00:00Z to an ISO Zulu DateTime string.

Parameters:: millis - the millis since 1970-01-01T00:00:00Z
Returns:: the ISO Zulu DateTime string 'T'
Throws:: java.lang.Exception - if trouble (e.g., millis is Long.MAX_VALUE)

removeSpacesDashesColons

public static java.lang.String removeSpacesDashesColons(java.lang.String s)

Remove any spaces, dashes (except optional initial dash), colons, and T's from s.

Parameters:: s - a string
Returns:: s with any spaces, dashes, colons removed (if s == null, this throws Exception)
Throws:: java.lang.Exception - if trouble (e.g., s is null)

binaryFindClosest

public static int binaryFindClosest(java.lang.String[] isoDates,
                                    java.lang.String timeValue)

Find the closest match for timeValue in isoDates which must be sorted in ascending order. This gives precise answer if there is an exact match (and gives closest answer timeValue is imprecise, e.g., if "2006-01-07" is used to represent a precise time of "2006-01-07 12:00:00").

This throws RuntimeException if some years are negative (0000 is ok).

Parameters:: isoDates - is an ascending sorted list of ISO dates [times]. It the array has duplicates and timeValue equals one of them, it isn't specified which duplicate's index will be returned.; timeValue - the ISO timeValue to be matched (with connector "T" or " " matching the isoDates)
Returns:: the index (in isoDates) of the best match for timeValue. If timeValue is null or "", this returns isoDates.length-1.

binaryFindLastLE

public static int binaryFindLastLE(java.lang.String[] isoDates,
                                   java.lang.String timeValue)

Find the last element which is <= timeValue in isoDates (sorted ascending).

If firstGE > lastLE, there are no matching elements (because the requested range is less than or greater than all the values, or between two adjacent values).

This throws RuntimeException if some years are negative (0000 is ok).

Parameters:: isoDates - is an ascending sorted list of ISO dates [times] which may have duplicates; timeValue - an iso formatted date value (with connector "T" or " " matching the isoDates)
Returns:: the index of the last element which is <= timeValue in an ascending sorted array. If timeValue is invalid or timeValue < the smallest element, this returns -1 (no element is appropriate). If timeValue > the largest element, this returns isoDates.length-1.

binaryFindFirstGE

public static int binaryFindFirstGE(java.lang.String[] isoDates,
                                    java.lang.String timeValue)

Find the first element which is >= timeValue in isoDates (sorted ascending.

If firstGE > lastLE, there are no matching elements (because the requested range is less than or greater than all the values, or between two adjacent values).

This throws RuntimeException if some years are negative (0000 is ok).

Parameters:: isoDates - is a sorted list of ISO dates [times] which may have duplicates; timeValue - an iso formatted date value (with connector "T" or " " matching the isoDates)
Returns:: the index of the first element which is >= timeValue in an ascending sorted array.
If timeValue < the smallest element, this returns 0.
If timeValue is invalid or timeValue > the largest element, this returns isoDates.length (no element is appropriate).

isoDateTimeAdd

public static java.util.GregorianCalendar isoDateTimeAdd(java.lang.String isoDate,
                                                         int n,
                                                         int field)
                                                  throws java.lang.Exception

This adds the specified n field's to the isoDate, and returns the resulting GregorianCalendar object.

This correctly handles B.C. dates.

Parameters:: isoDate - an iso formatted date time string in UTC time zone.; n - the number of 'units' to be added; field - one of the Calendar or Calendar2 constants for a field (e.g., Calendar2.YEAR).
Returns:: the GregorianCalendar for isoDate with the specified n field's added
Throws:: java.lang.Exception - if trouble e.g., n is Integer.MAX_VALUE

elapsedTimeString

public static java.lang.String elapsedTimeString(double millis)

This converts a millis elapsed time value (139872234 ms or 783 ms) to a nice string (e.g., "7h 4m 5s", "5.783 s", or "783 ms").
was (e.g., "7:04:05.233" or "783 ms").

Parameters:: millis - may be negative
Returns:: a simplified approximate string representation of elapsed time (or "infinite[!]" if trouble, e.g., millis is Double.NaN).

centerOfMonth

public static java.util.GregorianCalendar centerOfMonth(java.util.GregorianCalendar gc)
                                                 throws java.lang.Exception

This converts the date, hour, minute, second so gc is at the exact center of its current month.

Parameters:: gc -
Returns:: the same gc, but modified, for convenience
Throws:: java.lang.Exception - if trouble (e.g., gc is null)

clearSmallerFields

public static java.util.GregorianCalendar clearSmallerFields(java.util.GregorianCalendar gc,
                                                             int field)
                                                      throws java.lang.Exception

This clears the fields smaller than 'field' (e.g., HOUR_OF_DAY clears MINUTE, SECOND, and MILLISECOND, but not HOUR_OF_DAY, MONTH, or YEAR).

Parameters:: gc -; field - e.g., HOUR_OF_DAY
Returns:: the same gc, but modified, for convenience
Throws:: java.lang.Exception - if trouble (e.g., gc is null or field is not supported)

backNDays

public static double backNDays(int nDays,
                               double max)
                        throws java.lang.Exception

This returns the start of a day, n days back from max (or from now if max=NaN).

Parameters:: nDays -; max - seconds since epoch
Returns:: seconds since epoch for the start of a day, n days back from max (or from now if max=NaN).
Throws:: java.lang.Exception

getNEvenlySpaced

public static double[] getNEvenlySpaced(double start,
                                        double stop,
                                        int maxNValues)

This returns a double[] of maxNValues (or fewer) evenly spaced, between start and stop. The first and last values will be start and stop. The intermediate values will be evenly spaced in a human sense (eg monthly) but the start and stop won't necessarily use the same stride.

Parameters:: start - epoch seconds; stop - epoch seconds; maxNValues - maximum desired nValues
Returns:: a double[] of nValues (or fewer) epoch seconds values, evenly spaced, between start and stop.
If start or stop is not finite, this returns null.
If start=stop, this returns just one value.
If start > stop, they are swapped so the results are always ascending.
If trouble, this returns null.

nextNice

public static int nextNice(double d,
                           int[] nice)

This returns the value in nice which is >= d, or a multiple of the last value which is higher than d. This is used to suggest the division distance along an axis.

Parameters:: d - a value e.g., 2.3 seconds; nice - an ascending list. e.g., for seconds: 1,2,5,10,15,20,30,60
Returns:: the value in nice which is >= d, or a multiple of the last value which is higher than d

roundToIdealGC

public static java.util.GregorianCalendar roundToIdealGC(double epochSeconds,
                                                         int idealN,
                                                         int idealUnits)

This rounds to the nearest idealN, idealUnits (e.g., 2 months) (starting at Jan 1, 0000).

Parameters:: epochSeconds -; idealN - e.g., 1 to 100; idealUnits - an index of one of the IDEAL_UNITS
Returns:: epochSeconds, converted to Zulu GC and rounded to the nearest idealN, idealUnits (e.g., 2 months)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.cohort.util Class Calendar2

ERA

BC

YEAR

MONTH

DATE

DAY_OF_YEAR

HOUR

HOUR_OF_DAY

MINUTE

SECOND

MILLISECOND

AM_PM

ZONE_OFFSET

DST_OFFSET

SECONDS_PER_MINUTE

SECONDS_PER_HOUR

SECONDS_PER_DAY

MILLIS_PER_MINUTE

MILLIS_PER_HOUR

MILLIS_PER_DAY

SECONDS_SINCE_1970

zuluTimeZone

IDEAL_N_OPTIONS

IDEAL_UNITS_OPTIONS

IDEAL_UNITS_SECONDS

IDEAL_UNITS_FIELD

verbose

reallyVerbose

Calendar2

fieldName

getTimeBaseAndFactor

unitsSinceToEpochSeconds

epochSecondsToUnitsSince

factorToGetSeconds

isoStringToEpochSeconds

safeIsoStringToEpochSeconds

isIsoDate

gcToEpochSeconds

epochSecondsToGc

isoStringToEpochHours

epochSecondsToIsoStringT

safeEpochSecondsToIsoStringT

safeEpochSecondsToIsoStringTZ

epochSecondsToIsoStringSpace

epochHoursToIsoString

getMonthName3

getMonthName

newGCalendarLocal

newGCalendarZulu

newGCalendarZulu

newGCalendarLocal

newGCalendarZulu

newGCalendarLocal

newGCalendarZulu

newGCalendarLocal

newGCalendarZulu

getYear

formatAsISOYear

formatAsISODate

formatAsISODateTimeT

formatAsISODateTimeSpace

formatAsIsoDateHM

formatAsCompactDateTime

formatAsYYYYDDD

formatAsYYYYMM

formatAsDDMonYYYY

formatAsUSSlashAmPm

formatAsRFC822GMT

formatAsUSSlash24

parseISODateTime

parseISODateTimeZulu

parseUSSlash24

parseUSSlash24Zulu

parseCompactDateTime

parseCompactDateTimeZulu

parseDDMonYYYY

parseDDMonYYYYZulu

parseYYYYDDD

parseYYYYDDDZulu

com.cohort.util
Class Calendar2