The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DateTime-Event-SolarTerm-0.04
++
/ DateTime::Event::SolarTerm

NAME

DateTime::Event::SolarTerm - DateTime Extension to Calculate Solar Terms

SYNOPSIS

  use DateTime::Event::SolarTerm;
  my $major_term = DateTime::Event::SolarTerm->major_term();

  my $dt0  = DateTime->new(...);
  my $next_major_term = $major_term->next($dt0);
  my $prev_major_term = $major_term->previous($dt0);

  my $dt1  = DateTime->new(...);
  my $dt2  = DateTime->new(...);
  my $span = DateTime::Span->new(start => $dt1, end => $dt2);

  my $set  = $major_term->intersection($span);
  my $iter = $set->iterator();

  while (my $dt = $iter->next) {
    print $dt->datetime, "\n";
  }

  my $minor_term = DateTime::Event::SolarTerm->minor_term();

  my $dt0  = DateTime->new(...);
  my $next_minor_term = $minor_term->next($dt0);
  my $prev_minor_term = $minor_term->previous($dt0);

  my $dt1  = DateTime->new(...);
  my $dt2  = DateTime->new(...);
  my $span = DateTime::Span->new(start => $dt1, end => $dt2);

  my $set  = $minor_term->intersection($span);
  my $iter = $set->iterator();

  while (my $dt = $iter->next) {
    print $dt->datetime, "\n";
  }

  # if you just want to calculate a single major/minor term event
  my $dt = DateTime::Event::Lunar->major_term_after(datetime => $dt0);
  my $dt = DateTime::Event::Lunar->major_term_before(datetime => $dt0);
  my $dt = DateTime::Event::Lunar->minor_term_after(datetime => $dt0);
  my $dt = DateTime::Event::Lunar->minor_term_before(datetime => $dt0);

  my $index = DateTime::Event::SolarTerm->last_major_term_index(datetime => $dt);
  my $index = DateTime::Event::SolarTerm->last_minor_term_index(datetime => $dt);
  my $boolean = DateTime::Event::SolarTerm->no_major_term_on(datetime => $dt);

  # to get the next specific solar term
  use DateTime::Event::SolarTerm qw(DONGZHI);
  my $next = DateTime::Event::SolarTerm->next_term_at(
    datetime  => $dt,
    longitude => DONGZHI
  );
    
  my $prev = DateTime::Event::SolarTerm->prev_term_at(
    datetime  => $dt,
    longitude => DONGZHI
  );

DESCRIPTION

A lunar calendar has months based on the lunar cycle, which is approximately 29.5 days. This cycle does not match the cycle of the Sun, which is approximately 365 days.

You can use leap months to better align the cycle as in the Chinese calendar, but that still means that months could be off by possibly one lunar month. This was unacceptable for agricultural purposes which is linked deeply with the season, which in turn is linked with the solar cycle.

This is where solar terms are used. Regardless of what lunar month it is, you can tell the season using the solar terms.

Solar terms are still used in some parts of Asia, especially China, where major holidays must be calculated based on these solar terms.

FUNCTIONS

  *** WARNING WARNING WARNING ****

  The return value of these functions are subject to change!
  They currently return a simple DateTime object, but we may somehow
  come up with a way to return more data with it, such as the solar
  term's name

  *** WARNING WARNING WARNING ***

DateTime::Event::SolarTerm->major_term()

DateTime::Event::SolarTerm->minor_term()

Returns the starting date of the next or previous major/minor solar term. This recurrence set makes no attempt to classify just what solar term is beginning on that date. (This may change in the future)

Because solar terms depend on the location/timezone, you should make sure to pass a DateTime object with locale and/or timezone set to where you are basing your calculations on. If the given time zone does not specify one (i.e. it is a "floating" time zone), then UTC is assumed.

DateTime::Event::SolarTerm->next_term_at(%args)

Returns a DateTime object representing the next solar term date at the specified longitude. For example, to get the next winter solstice, you can say

  use DateTime::Event::SolarTerm qw(WINTER_SOLSTICE);
  my $winter_solstice = DateTime::Event::SolarTerm->next_term_at(
    datetime  => $dt0,
    longitude => WINTER_SOLSTICE
  );

This is the functiont that is internally used by major_term()->next() and minor_term->next()

DateTime::Event::SolarTerm->prev_term_at(%args)

Returns a DateTime object representing the previous solar term date at the specified longitude. For example, to get the previous winter solstice, you can say

  use DateTime::Event::SolarTerm qw(WINTER_SOLSTICE);
  my $winter_solstice = DateTime::Event::SolarTerm->previous_term_at(
    datetime  => $dt0,
    longitude => WINTER_SOLSTICE
  );

This is the functiont that is internally used by major_term()->previous() and minor_term->previous()

DateTime::Event::SolarTerm->last_major_term_index(%args)

Returns the current/previous major term index. Note that even if the date falls on a minor term, returns the closest previous major term from the date given by the datetime argument.

If the major term can't be calculated (e.g. DateTime argument is a DateTime::Infinite object), then returns undef.

(This method has been renamed from current_major_term to better suit the behavior)

DateTime::Event::SolarTerm->last_minor_term_index(%args)

Returns the current/previous minor term index. Note that even if the date falls on a minor term, returns the closest previous minor term from the date given by the datetime argument.

If the major term can't be calculated (e.g. DateTime argument is a DateTime::Infinite object), then returns undef.

(This method has been renamed from current_minor_term to better suit the behavior)

DateTime::Event::SolarTerm->no_major_term_on(%args)

Returns true if there is a major term in the lunar month of the specified date.

AUTHOR

Daisuke Maki <daisuke@cpan.org>

REFERENCES

  [1] Edward M. Reingold, Nachum Dershowitz
      "Calendrical Calculations (Millenium Edition)", 2nd ed.
       Cambridge University Press, Cambridge, UK 2002

SEE ALSO

DateTime DateTime::Set DateTime::Span DateTime::Event::Lunar