When: A multicultural and multilingualized calendar library


This library is a library for Ruby aiming at expressing a calendar used by every culture and language through all ages and countries, and converting it.

The downloading of Ruby http://www.ruby-lang.org/ja/downloads/
The implementation of the Web server using this library http://hosi.org (Mirror site http://hosi-org.herokuapp.com )
The Japanese Date Query System using this library http://hosi.org/Note
This whole library set to archive http://www.asahi-net.or.jp/~dd6t-sg/date/when_exe_rev.0.4.1beta.zip
The resource dictionaryhttp://www2u.biglobe.ne.jp/~suchowan/ResourceDictionary.html
The API specifications that made in yard http://hosi.org/frames or http://www2u.biglobe.ne.jp/~suchowan/when_exe/frames.html
GitHub https://github.com/suchowan/when_exe
RubyGems http://rubygems.org/gems/when_exe
The recent progress information http://suchowan.at.webry.info/theme/a543700674.html

Purpose, use

I perform a unique name charge account in a calendar day, rule of calendar, time rules, calendar year charges, notice on a calendar used by every culture and language through all ages and countries, and a basic purpose is to provide a frame to treat it integrally.

In addition, does it not come to feature TZInfo and gcalapi and the collaborating point?

As a result, I think that I hit it to a library suitable for the engines of the Web server.

It is far superior in comparison with the classes such as Time, Date, DateTime which originally comes in Ruby, and movement speed is late and is not a thing rearranging these.

The present status

At the time of 2016-01-15, this library is rev.0.4.5 in beta release.

Thawing look at tickets.xls of the <ticket> directory right under archiving it about the future problem. But it depends on a future judgment whether you really take measures against an enumerated matter.

The copyright relations are going to finally make it one that it is near to public domain, but possibility to shake in future such as API still stays and make it one with the strong limitation such as the next clause at present first of all.

Copyright indication

Copyright (C) 2011-2016 Takashi SUGA

You may use and/or modify this library according to the license described in the LICENSE.txt file.

You should use data sets TemporalPositionDataSet and TemporalReferenceSystemDataSet according to CC-BY-ND license.

You should use datasets described in /test/events according to each datasets' {dcq:license} link.


Development of when.exe, which is an MS-DOS command-line type calendar interconversion program, begins in about 1990. However, Microsoft Windows  is changed XP->Vista->7, when.exe’s environment is gradually lost.

Uptake of the international standard

I noticed that various international standards have been developed in last 20 years:

The implementation of this library has overs and shorts about each of the international standard that I referred to.

In addition, (*) the functions which RFC 2445 has and RFC5545 does not have, like EXRULE, are not implemented.

The differences between this library and these standards are described in clause of the figure of class and a succession-related figure.

(*) When I participated in IETF 50th meeting@Minneapolis of 2001 and observed an argument of RFC 2445, there was a topic, "it was too complicated, and there was not proper implementation". 2445 RFC RFC 5545 seems to be the review to a course to rather simplify, and there will not be the thing that the expansion in this library is adopted for a standard.

When.exe Standard Representation (expression of date and time)

                         1  2  3  4   5          6

This is a basic date and time representation in this library. I use it by when? method.

This includes extended expression of ISO8601 and is designed to match the following requirements.


  1. In the case of the Common Era, this becomes usually same as extended expression of ISO8601.
  2. The rule should allow us to express a date and time of calendar that one year does not begin on January 1(example: the fiscal year).
  3. The rule should allow us to express a date and time of calendar that one day does not begin at 0:00 a.m. (example: Islamic calendar).
  4. The rule should allow us to express a date of the Chinese lunisolar calendars.
  5. The rule should allow us to express a date of the Indian lunisolar calendars.
  6. When there is no name of an era, and CCYY is in the range of 0..9999, for the same rule of calendar and time zone, ascending order sort by the character string is equivalent to ascending order sort on a date and time.


PP      - The period name or country name
NN      - The name of an era
nn      - Year by the name of an era concerned
CCYY    - Year in the rule of calendar concerned
MM      - Month
DD      - Day
hh      - Hour
mm      - Minute
ss.s    - Second
Z       - UTC
±ZZ:zz  - Timezone

'nn'-'mm' are non-negative integer (the number of the figures is arbitrary), 'ss.s' is non-negative integer or real numbers.

However, In 'nn', 'DD' and 'CCYY'(when the default date for abbreviated forms is appointed), not only the number but also the designation string which expresses residue class surrounded by "{}" is possible (-> 5.Designation of the objects).





3 *(3)

4 *(3)

























For black half










0x25 *(1)





For intercalary black half




Lack day











For intercalary white half

For intercalary white half

For intercalary white half












In the previous year


For intercalary black half


For intercalary black half





The day before










For black half









The east longitude side


0x2D *(2)


This year


For white half

For white half

For white half

The normal month


Normal day


On that day


Normal time

The west longitude side






For black half














The next year





Intercalary month


Double day


The next day


Intercalary time *(4)


























The month after next month








IRI - Internationalized Resource Identifier (globalization resource identifier)

This library uses IRI. IRI is mainly used in order to distinguish an object for Reference System uniquely.

An example: Time

|timezone|                IRI                             |  object creation & reference        |
| +09:00 | http://hosi.org/When/TM/Clock?label=+09:00 (*) |  Resource('_tm:Clock?label=+09:00') |
| +00:00 | http://hosi.org/When/CalendarTypes/UTC         |  Resource('_c:UTC')                 |

The class expressing time is TM_Clock in ISO19108, which is  When:: TM::Clock class in this library.  IRI http://hosi.org/When/TM/Clock?label=+09:00 means the singleton object of When::TM::Clock class timezone +09:00.

Because Coordinated Universal Time is frequently useed, a class When:: CalendarTypes::UTC  is defined.  IRI of the object of this class is http://hosi.org/When/CalendarTypes/UTC.

The Resource method  is a method to acquire an object equivalent to IRI character string. We can use more simplified character string using prefix.

 _w:   = http://hosi.org/When/
 _p:   = http://hosi.org/When/Parts/
 _b:   = http://hosi.org/When/BasicTypes/
 _m:   = http://hosi.org/When/BasicTypes/M17n/
 _co:  = http://hosi.org/When/Coordinates/
 _l:   = http://hosi.org/When/Coordinates/Spatial?
 _v:   = http://hosi.org/When/V/
 _rs:  = http://hosi.org/When/RS/
 _ex:  = http://hosi.org/When/EX/
 _tm:  = http://hosi.org/When/TM/
 _e:   = http://hosi.org/When/TM/CalendarEra/
 _t:   = http://hosi.org/When/TimeStandard/
 _ep:  = http://hosi.org/When/Ephemeris/
 _c:   = http://hosi.org/When/CalendarTypes/
 _n:   = http://hosi.org/When/CalendarTypes/CalendarNote
 _sc:  = http://hosi.org/When/Ephemeris/V50/

I added '_' to these reserved prefix not to clash with the prefix of the user definition.

(*) application/x-www-form-urlencoded encodes '' in '+', but this does not seem to be specifications of IRI/URI. URI.encode/decode of Ruby does not make this conversion, too.

M17n (Multilingualization) String (multilingual correspondence character string)

The subclass which uses it in this library in place of String When::BasicTypes::M17n  is multilingual correspondence character string. We maintain character string and reference corresponding to various Locale.

An example: March

Resource('_m:CalendarTerms:: Month:: March') is the singleton object of the class When:: BasicTypes:: M17n.

| loc  |         #translate(loc)     |             #reference(loc)             |
| 'ja' |           '3月'             | http://ja.wikipedia.org/wiki/3%E6%9C%88 |
| 'en' |          'March'            | http://en.wikipedia.org/wiki/March      |

An example: Monday

We can define the multilingual correspondence character string in the hierarchies consisting of the objects of various classes.

If, for example, residue class for weekdays is described as the following list in http://example.org/ResidueTerms,

  LOCALE:[=en_ns:, ja=ja_ns:]

    LABEL:[Week, 週]



the objects such as the following list is produced when we read from this URL.

|                         IRI                           |            class           |     label    |
| http://example.org/ResidueTerms                       | When::BasicTypes::M17n     | ResidueTerms |
| http://example.org/ResidueTerms::Week                 | When::Coordinates::Residue |     Week     |
| http://example.org/ResidueTerms::Week::Week           | When::BasicTypes::M17n     |     Week     |
| http://example.org/ResidueTerms::Week::Monday         | When::Coordinates::Residue |    Monday    |
| http://example.org/ResidueTerms::Week::Monday::Monday | When::BasicTypes::M17n     |    Monday    |

Figure of class

I show below a figure of class of this library.

1. Coordinates

説明: 説明: 説明: When-1 Coordinates

2. BasicTypes

説明: 説明: 説明: When-2 BasicTypes

3. CalendarTypes

説明: 説明: 説明: When-3 CalendarTypes

4. Ephemeris

説明: 説明: 説明: When-4 Ephemeris

5. The RFC5545 succession and inclusion

説明: 説明: 説明: The RFC5545 succession and inclusion

6. Structure of the time schema

説明: 説明: 説明: Structure of the ISO19108-1 time schema

7. Time object

説明: 説明: 説明: ISO19108-2 time object

8. Time geometry primitive

説明: 説明: 説明: ISO19108-3 time geometry primitive

9. TM: RelativePosition

説明: 説明: 説明: ISO19108-4 TM: RelativePosition

10. TM: Duration

説明: 説明: 説明: ISO19108-5 TM: Duration

11. Phase of the time

説明: 説明: 説明: Phase of the ISO19108-6 time

12. Time reference system

説明: 説明: 説明: ISO19108-7 time reference system

13. A calendar and clock

説明: 説明: 説明: ISO19108-8 calendar and clock

14. Time coordinate system

説明: 説明: 説明: ISO19108-9 time coordinate system

15. Ordinal time reference system

説明: 説明: 説明: ISO19108-10 order time reference system

16. Data type for time positions

説明: 説明: 説明: Data type for ISO19108-11 time positions

I use astah community for the making of the figure of these classes. You can download astah community from here.