ExampleCode.java

package bigtime.examples;

import static bigtime.when.BigDecimalHelper.*;
import static bigtime.when.Calendar.*;
import static bigtime.when.TimescaleImpl.*;
import static java.math.RoundingMode.*;

import java.math.BigDecimal;
import java.util.Optional;

import bigtime.when.Calendar;
import bigtime.when.Date;
import bigtime.when.DateTime;
import bigtime.when.JulianDate;
import bigtime.when.Time;
import bigtime.when.Timescale;
import bigtime.when.TimescaleImpl;

/** 
 Basic examples of using the library.
 This is not a complete set of examples.
 
 <p>Note the use of {@link BigDecimal} to represent seconds/days.
 The 'big(...)' methods are simple helper methods defined in BigDecimalHelper, 
 for making BigDecimal objects.

 <P>Example output to stdout:
 <pre>
DateTime.toString(): 1987-12-25 GR 12:30:15.123456 TDB
Multiple conversions:
 Start with:   1987-12-25 GR 12:30:15.123456 TDB
 Intermediate: 1987-12-25 GR 12:29:42.939726506771634249600019200 TAI
 Unrounded:    1987-12-25 GR 12:30:15.123455989343589575700000000 TDB
 End with:     1987-12-25 GR 12:30:15.123456 TDB
Done.
 </pre>
*/
@SuppressWarnings("unused")
public class ExampleCode {

  /** Run, examples, run! */
  public static void main(String[] args) {
    buildDates();
    buildTimes();
    buildDatesAndTimes();
    calendarConversion();
    compareDates();
    daysFrom();
    nextPreviousDayEtc();
    dateToJulianDate();
    dateTimeMethods();
    dateTimeString();
    circularConversion();
    stdout("Done.");
  }
  
  private static void buildDates() {
    Date a = Date.from(1987, 12, 25, GREGORIAN);
    Date b = Date.gregorian(1987, 12, 25);
    Date c = Date.julian(1095, 11, 12);
    //the year is a 'long' data type
    Date d = Date.gregorian(3213132131321313131L, 12, 31);
  }
  
  private static void buildTimes() {
    //12:30:15.123_456_789_012
    Time a = Time.from(12, 30, big(15.123_456_789_012), GPS);
    Time b = Time.from(12, 30, big("15.1234567890123456789012345678"), GPS);
    //using fraction of a day
    Time c = Time.from(big(0.123_456_789_012), TAI);
    Time startOfDay = Time.zero(TAI);
  }
  
  private static void buildDatesAndTimes() {
    Date date = Date.gregorian(1987, 12, 25);
    Time time = Time.from(12, 30, big(15.123), UT1);
    DateTime dt = DateTime.from(date, time);
    
    //using a fraction of a day
    dt = DateTime.from(date, big(0.123_465_789_012), TDB);
    
    dt = DateTime.from(1999, 12, 31, 23, 59, big(59.999), GREGORIAN, UTC);
    dt = DateTime.from(1999, 12, 31, 23, 59, big("59.999999999999999999999999999"), GREGORIAN, UTC);
    
    JulianDate jd = JulianDate.from(big(2_545_321.5), TT);
    dt = DateTime.from(jd, GREGORIAN);
    JulianDate jd2 = dt.toJulianDate();
  }
  
  private static void calendarConversion() {
    Date a = Date.gregorian(1400, 12, 1);
    Date b = a.convertTo(JULIAN);
  }
  
  private static void compareDates() {
    Date a = Date.gregorian(1400, 12, 1);
    Date b = Date.julian(1095, 11, 16);
    boolean isAfter = a.gt(b);
    boolean isSame = a.eq(b);
    //and so on...
  }

  private static void daysFrom() {
    Date a = Date.gregorian(1400, 12, 1);
    Date b = Date.julian(1095, 11, 16);
    long days = a.daysFrom(b);
  }
  
  private static void nextPreviousDayEtc() {
    Date a = Date.gregorian(2023, 12, 1);
    Date b = a.next();
    b = a.previous();
    b = a.plusMinusDays(10);
    b = a.plusMinusDays(-10);
  }

  /** 
   You can build a DateTime from a JulianDate, but not a Date.
   A JulianDate object carries fractional day information, but Date does not. 
  */
  private static void dateToJulianDate() {
    Date a = Date.gregorian(2023, 12, 1);
    JulianDate jd = a.jd(TT); //for 0h that day
    DateTime b = DateTime.from(jd, GREGORIAN);
    
    //no restriction to JD >= 0
    Date ancient = Date.gregorian(-15000, 1, 1);
    jd = a.jd(TT); 
  }
  
  private static void dateTimeMethods() {
    Date date = Date.gregorian(1987, 12, 25);
    Time time1 = Time.from(12, 30, big(15.123_456), TDB);
    Time time2 = Time.from(12, 30, big(15.000_002), TDB);
    DateTime a = DateTime.from(date, time1);
    DateTime b = DateTime.from(date, time2);
    
    int comparison = a.compareTo(b);
    BigDecimal days = a.daysFrom(b, 3, HALF_EVEN); //round to three decimals
    BigDecimal seconds = a.secondsFrom(b, 3, HALF_EVEN); //round to three decimals
    BigDecimal frac = a.fractionalDay(); //day and time-of-day as one number
    DateTime c = a.plusMinusDays(big(10), 4, HALF_EVEN);
    DateTime d = a.plusMinusSeconds(big(-62.132), 4, HALF_EVEN);
    DateTime e = a.roundSeconds(3, HALF_EVEN);
    Optional<DateTime> f = e.convertTo(UT1);
    DateTime g = f.get(); //should work, the conversion is supported for this date
    JulianDate jd = a.toJulianDate();
    long year = a.year();
    int month = a.month();
    //and so on...
  }
  
  /** The Calendar and Timescale are explicit in toString(). */
  private static void dateTimeString() {
    Date date = Date.gregorian(1987, 12, 25);
    Time time = Time.from(12, 30, big(15.123_456), TDB);
    DateTime a = DateTime.from(date, time);
    stdout("DateTime.toString(): " + a.toString()); //1987-12-25 GR 12:30:15.123456 TDB
  }
  
  /** 
   Multiple conversions 'a -> b -> c -> ... -> a' get you back to where you started. 
   You need to apply rounding at the end to get an exact match. 
  */
  private static void circularConversion() {
    Date date = Date.gregorian(1987, 12, 25);
    Time time = Time.from(12, 30, big(15.123_456), TDB);
    DateTime a = DateTime.from(date, time);
    stdout("Multiple conversions:"); 
    stdout(" Start with:   " + a.toString()); 
    JulianDate jd = a.toJulianDate();
    DateTime b = DateTime.from(jd, JULIAN); //jd + different calendar
    //given the date range, this conversion will work:
    Optional<DateTime> c = b.convertTo(TAI); //new Timescale
    DateTime d = c.get();
    DateTime e = DateTime.from(d.toJulianDate(), GREGORIAN); //back to Gregorian
    stdout(" Intermediate: " + e.toString());
    Optional<DateTime> f = Timescale.convertTo(TDB, e);
    //given the date range, this conversion will work:
    DateTime g = f.get();
    stdout(" Unrounded:    " + g.toString());
    stdout(" End with:     " + g.roundSeconds(6, HALF_EVEN));
  }
  
  private static void stdout(Object thing) {
    System.out.println(thing.toString());
  }
}