view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME

    Date::Japanese::Era - Conversion between Japanese Era / Gregorian
    calendar

SYNOPSIS

      use utf8;
      use Date::Japanese::Era;
    
      # from Gregorian (month + day required)
      $era = Date::Japanese::Era->new(1970, 1, 1);
    
      # from Japanese Era
      $era = Date::Japanese::Era->new("昭和", 52); # SHOWA
    
      $name      = $era->name;         # 昭和 (in Unicode)
      $gengou    = $era->gengou;       # Ditto
    
      $year      = $era->year;         # 52
      $gregorian = $era->gregorian_year;       # 1977
    
      # use JIS X0301 table for conversion
      use Date::Japanese::Era 'JIS_X0301';
    
      # more DWIMmy
      $era = Date::Japanese::Era->new("昭和五十二年");
      $era = Date::Japanese::Era->new("昭和52年");

DESCRIPTION

    Date::Japanese::Era handles conversion between Japanese Era and
    Gregorian calendar.

METHODS

    new

        $era = Date::Japanese::Era->new($year, $month, $day);
        $era = Date::Japanese::Era->new($era_name, $year);
        $era = Date::Japanese::Era->new($era_year_string);

      Constructs new Date::Japanese::Era instance. When constructed from
      Gregorian date, month and day is required. You need Date::Calc to
      construct from Gregorian.

      Name of era can be either of Japanese / ASCII. If you pass Japanese
      text, they should be in Unicode.

      Errors will be thrown if you pass byte strings such as UTF-8 or
      EUC-JP, since Perl doesn't understand what encoding they're in. Use
      the utf8 pragma if you want to write them in literals.

      Exceptions are thrown when inputs are invalid, such as non-existent
      era name and year combination, unknwon era-name, etc.

    name

        $name = $era->name;

      returns era name in Japanese in Unicode.

    gengou

      alias for name().

    name_ascii

        $name_ascii = $era->name_ascii;

      returns era name in US-ASCII.

    year

        $year = $era->year;

      returns year as Japanese era.

    gregorian_year

        $year = $era->gregorian_year;

      returns year as Gregorian.

EXAMPLES

      use utf8;
      use Date::Japanese::Era;
    
      # 2001 is H-13
      my $era = Date::Japanese::Era->new(2001, 8, 31);
      printf "%s-%s", uc(substr($era->name_ascii, 0, 1)), $era->year;
    
      # to Gregorian
      my $era = Date::Japanese::Era->new("平成", 13); # HEISEI 13
      print $era->gregorian_year;   # 2001

 ERA NAME VALIDATION AND CONVERSION

    When you construct a new object from Japanese Era and year, this module
    does not handle if the year does not exist for the given era, such as
    平成32, since the era ended in 31. This might be problematic if you want
    to allow the year number to exceed its end and automatically convert to
    the correct era i.e. 令和2.

    To do this, you can use an offset-based calculation first to get the
    Gregorian year, and then construct a Date::Japanese::Era object from
    Gregorian year, month and day, such as:

      my %offset = (
          "昭和" => 1925,
          "平成" => 1988,
          "令和" => 2018,
      );
    
      my $name  = "平成";
      my $year  = 33;
      my $month = 4;
      my $day   = 1;
    
      my $gregorian_year = $offset{$name} + $year;
      my $era = Date::Japanese::Era->new( $gregorian_year, $month, $day );
    
      # $era is now Reiwa 3, since Heisei 33 doesn't exist.

    Similarly, to validate if the given Japanese era is valid for the given
    date, you can compare the era after round-tripping with Gregorian year:

      sub is_valid_era {
          my( $name, $year, $month, $day ) = @_;
    
          my $ok;
          eval {
              my $era1 = Date::Japanese::Era->new($name, $year);
              my $era2 = Date::Japanese::Era->new($era1->gregorian_year, $month, $day);
              $ok = $era1->name eq $era2->name;
          };
    
          return $ok;
      }

CAVEATS

      * Currently supported era is up to 'meiji'. And before Meiji
      05.12.02, gregorius calendar was not used there, but lunar calendar
      was. This module does not support lunar calendar, but gives warnings
      in such cases ("In %d they didn't use gregorius calendar").

      To use calendar ealier than that, see
      DateTime::Calendar::Japanese::Era, which is based on DateTime
      framework and is more comprehensive.

      * There should be discussion how we handle the exact day the era has
      changed (former one or latter one?). This module default handles the
      day as newer one, but you can change so that it sticks to JIS table
      (older one) by saying:

        use Date::Japanese::Era 'JIS_X0301';

      For example, 1912-07-30 is handled as:

        default       Taishou 1 07-30
        JIS_X0301     Meiji 45 07-30

      * If someday current era (reiwa) is changed,
      Date::Japanese::Era::Table should be upgraded.

AUTHOR

    Tatsuhiko Miyagawa <miyagawa@bulknews.net>

COPYRIGHT

    Tatsuhiko Miyagawa, 2001-

LICENSE

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

SEE ALSO

    DateTime::Calendar::Japanese::Era, Date::Calc, Encode