First version of docs.

[SVN r14822]
2026-07-21 13:13:29 +00:00 · 2002-08-13 22:18:14 +00:00
commit f6cb01479f
2 changed files with 290 additions and 0 deletions
@@ -0,0 +1,96 @@
+* text=auto !eol svneol=native#text/plain
+*.gitattributes text svneol=native#text/plain
+
+# Scriptish formats
+*.bat        text svneol=native#text/plain
+*.bsh        text svneol=native#text/x-beanshell
+*.cgi        text svneol=native#text/plain
+*.cmd        text svneol=native#text/plain
+*.js         text svneol=native#text/javascript
+*.php        text svneol=native#text/x-php
+*.pl         text svneol=native#text/x-perl
+*.pm         text svneol=native#text/x-perl
+*.py         text svneol=native#text/x-python
+*.sh         eol=lf svneol=LF#text/x-sh
+configure    eol=lf svneol=LF#text/x-sh
+
+# Image formats
+*.bmp        binary svneol=unset#image/bmp
+*.gif        binary svneol=unset#image/gif
+*.ico        binary svneol=unset#image/ico
+*.jpeg       binary svneol=unset#image/jpeg
+*.jpg        binary svneol=unset#image/jpeg
+*.png        binary svneol=unset#image/png
+*.tif        binary svneol=unset#image/tiff
+*.tiff       binary svneol=unset#image/tiff
+*.svg        text svneol=native#image/svg%2Bxml
+
+# Data formats
+*.pdf        binary svneol=unset#application/pdf
+*.avi        binary svneol=unset#video/avi
+*.doc        binary svneol=unset#application/msword
+*.dsp        text svneol=crlf#text/plain
+*.dsw        text svneol=crlf#text/plain
+*.eps        binary svneol=unset#application/postscript
+*.gz         binary svneol=unset#application/gzip
+*.mov        binary svneol=unset#video/quicktime
+*.mp3        binary svneol=unset#audio/mpeg
+*.ppt        binary svneol=unset#application/vnd.ms-powerpoint
+*.ps         binary svneol=unset#application/postscript
+*.psd        binary svneol=unset#application/photoshop
+*.rdf        binary svneol=unset#text/rdf
+*.rss        text svneol=unset#text/xml
+*.rtf        binary svneol=unset#text/rtf
+*.sln        text svneol=native#text/plain
+*.swf        binary svneol=unset#application/x-shockwave-flash
+*.tgz        binary svneol=unset#application/gzip
+*.vcproj     text svneol=native#text/xml
+*.vcxproj    text svneol=native#text/xml
+*.vsprops    text svneol=native#text/xml
+*.wav        binary svneol=unset#audio/wav
+*.xls        binary svneol=unset#application/vnd.ms-excel
+*.zip        binary svneol=unset#application/zip
+
+# Text formats
+.htaccess    text svneol=native#text/plain
+*.bbk        text svneol=native#text/xml
+*.cmake      text svneol=native#text/plain
+*.css        text svneol=native#text/css
+*.dtd        text svneol=native#text/xml
+*.htm        text svneol=native#text/html
+*.html       text svneol=native#text/html
+*.ini        text svneol=native#text/plain
+*.log        text svneol=native#text/plain
+*.mak        text svneol=native#text/plain
+*.qbk        text svneol=native#text/plain
+*.rst        text svneol=native#text/plain
+*.sql        text svneol=native#text/x-sql
+*.txt        text svneol=native#text/plain
+*.xhtml      text svneol=native#text/xhtml%2Bxml
+*.xml        text svneol=native#text/xml
+*.xsd        text svneol=native#text/xml
+*.xsl        text svneol=native#text/xml
+*.xslt       text svneol=native#text/xml
+*.xul        text svneol=native#text/xul
+*.yml        text svneol=native#text/plain
+boost-no-inspect text svneol=native#text/plain
+CHANGES      text svneol=native#text/plain
+COPYING      text svneol=native#text/plain
+INSTALL      text svneol=native#text/plain
+Jamfile      text svneol=native#text/plain
+Jamroot      text svneol=native#text/plain
+Jamfile.v2   text svneol=native#text/plain
+Jamrules     text svneol=native#text/plain
+Makefile*    text svneol=native#text/plain
+README       text svneol=native#text/plain
+TODO         text svneol=native#text/plain
+
+# Code formats
+*.c          text svneol=native#text/plain
+*.cpp        text svneol=native#text/plain
+*.h          text svneol=native#text/plain
+*.hpp        text svneol=native#text/plain
+*.ipp        text svneol=native#text/plain
+*.tpp        text svneol=native#text/plain
+*.jam        text svneol=native#text/plain
+*.java       text svneol=native#text/plain
@@ -0,0 +1,194 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
+<title>Generic Date-Time Library (GDTL) Documentation</title>
+<link href="doxygen.css" rel="stylesheet" type="text/css">
+</head><body bgcolor="#ffffff">
+<!-- Generated by Doxygen 1.2.10 -->
+
+<body>
+<a href="../../../index.htm">
+<img align="left" src="../../../c++boost.gif" alt="C++ Boost">
+</a>  
+
+<h1>Generic Date-Time Library (GDTL) Documentation</h1>
+<p>
+<h3 align="center">Version 1.00</h3>
+<hr>
+
+<a name="contents"><h2>Contents</h2></a>
+<p>
+<font class="bold">Overview</font><br><br>
+
+<p>
+<a href="index.html#intro">Introduction</a>  -- <a href="index.html#motivation">Motivation</a> -- <a href="index.html#usage">Usage Examples</a>  -- <a href="index.html#domain">Domain Concepts</a> -- <a href="index.html#status">Status and Build</a> -- <a href="index.html#test">Tests</a>  -- <a href="index.html#design">Design and Extensions</a> -- <a href="index.html#more">More Info</a>
+<p>
+<font class="bold">Date Programming</font><br><br>
+<a href="gregorian.html">Gregorian Date System</a><br>
+<ul>
+    <li><a href="class_date.html">Class date</a>
+    <li><a href="class_date_duration.html">Class date_duration</a> 
+    <li><a href="class_date_period.html">Class date_period</a>
+    <li><a href="date_iterators.html">Date Iterators</a> 
+    <li><a href="date_algorithms.html">Date Generators / Algorithms</a> 
+    <li><a href="class_gregorian_calendar.html">Class gregorian_calendar</a>
+    <li><a href="class_date.html#constructfromclock">Class day_clock</a>
+</ul>
+
+<p>
+<font class="bold">Time Programming</font><br><br>
+<a href="posix_time.html">Posix Time System</a><br>
+
+<ul>
+    <li><a href="class_ptime.html">Class ptime</a>
+    <li><a href="class_time_duration.html">Class time_duration</a>
+    <li><a href="class_time_period.html">Class time_period</a>
+    <li><a href="time_iterators.html">Time Iterators</a> 
+    <li><a href="local_time_adjust.html">UTC / Local Time Adjustments</a>
+</ul>
+
+
+
+<a name="intro"><h2>Introduction</h2></a>
+
+<p>
+GDTL is a set of date-time libraries based on generic programming concepts.
+<p>
+<a name="motivation"><h2>Motivation</h2></a>
+
+<p>
+The motivation for this library comes from working with and helping build several date-time libraries on several projects. Date-time libraries provide fundamental infrustructure for most development projects. However, most of them have limitations in their ability to calculate, format, convert, or perform some other functionality. For example, most libraries  do not correctly handle leap seconds, provide concepts such as infinity, or provide the ability to use high resolution or network time sources.  These libraries also tend to be rigid in their representation of dates and times. Thus customized policies for a project or subproject are not possible.
+<p>
+Programming with dates and times should be almost as simple and natural as programming with strings and integers.  Applications with lots of temporal logic can be be radically  simplified by having a robust set of operators and calculation capabilities. Classes should provide the abilty to compare dates and times, add lengths or time durations, retrieve dates and times from  clocks, and work naturally with date and time intervals.
+<p>
+<a name="usage"><h2>Usage Examples</h2></a>
+
+<p>
+The following shows examples of the sorts of code that can be written using the gregorian date system.  See  <a href="gregorian.html">Date Programming</a> for more details.
+<p>
+<div class="fragment"><pre>     <font class="keyword">using</font> <font class="keyword">namespace </font>boost::gregorian; 
+     date weekstart(2002,Feb,1);
+     date weekend  (2002,Feb,7);
+     date_duration fiveDays(5); 
+     date d3 = d1 + fiveDays;
+     date today = day_clock::local_day();
+     <font class="keywordflow">if</font> (d3 &gt;= today) {} <font class="comment">//date comparison operators</font>
+     
+     date_period thisWeek(d1,d2);
+     <font class="keywordflow">if</font> (thisWeek.contains(today)) {}<font class="comment">//do something</font>
+    
+     <font class="comment">//iterate and print the week</font>
+     day_iterator itr(weekstart);
+     <font class="keywordflow">for</font> (; itr &lt;= weekend; ++itr) {
+       std::cout &lt;&lt; to_iso_extended_string(*itr) &lt;&lt; std::endl;
+     }     </pre></div> 
+
+And some time code using the posix_time system. See <a href="posix_time.html">Time Programming</a> for more details.
+
+<div class="fragment"><pre>     <font class="keyword">using</font> <font class="keyword">namespace </font>boost::posix_time; 
+     date d(2002,Feb,1); <font class="comment">//an arbitrary date</font>
+     ptime t1(d, hours(5)+nanosec(100));<font class="comment">//date + time of day offset</font>
+     ptime t2 = t1 - minutes(4)+seconds(2);
+     ptime now = second_clock::local_time(); <font class="comment">//use the clock</font>
+     <font class="comment">//Get the date part out of the time</font>
+     date today = now.date();
+     date tommorrow = today + date_duration(1);
+     ptime tommorrow_start(tommorrow); <font class="comment">//midnight </font>
+
+     <font class="comment">//starting at current time iterator adds by one hour</font>
+     time_iterator titr(now,hours(1)); 
+     <font class="keywordflow">for</font> (; titr &lt; tommorrow_start; ++titr) {
+       std::cout &lt;&lt; to_simple_string(*titr) &lt;&lt; std::endl;
+     }</pre></div>
+<p>
+
+<p>
+<a name="domain"><h2>Domain Concepts</h2></a>
+<p>
+The date time domain is rich in terminology and problems.  The following is a brief introduction to the concepts you will find reflected in GDTL library.
+<p>
+
+GDTL supports 3 basic temporal types:
+<UL>
+<li> <font class="bold">Time Point</font>     -- Specifier for a location in the time continuum.
+<li> <font class="bold">Time Duration</font>  -- A length of time unattached to any point on the time continuum.
+<li> <font class="bold">Time Interval</font>  -- A duration of time attached to a specific point in the time continuum.  Also known as a time period.
+</UL>
+
+Each of these temporal types has a <font class="bold">Resolution</font> which is defined by the smallest representable duration.  A <font class="bold">Time system</font> provides all these categories of temporal types as well as the rules for labeling and calculating with time points.  <font class="bold">Calendar Systems</font> are simply time systems with a maximum resolution of one day.  The <font class="bold">Gregorian</font> system is the most widely used calendar system today (the ISO system is basically a derivative of this).  However, there are many other calendar systems as well.  <font class="bold">UTC (Coordinated Universal Time)</font> is a widely used civil time system.  UTC is adjusted for earth rotation at longitude 0 by the use of leap seconds (This is not predictable, only as necessary).  Most <font class="bold">local time</font> systems are based on UTC but are also adjusted for earth rotation so that daylight hours are similar everywhere.  In addition, some local times include <fond class="bold">daylight savings time (DST)</font> adjustments to provide additional daylight during the summer.
+
+<p>
+A <font class="bold">Clock Device</font> is software component (tied to some hardware) that provides the current date or time with respect to a time system.
+
+<p>
+GDTL provides support for calculating with dates and times.  However, time calculations are not quite the same as calculating with integers.  If you are serious about the accuracy of your time calculations need to read about <a href="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?GDTL/Trade-Offs">Stability, Predictablity, and Aproximations</a>. 
+<p>
+Additional reference materials can be found in the following:
+
+<ul>
+<li><a href="BasicTerms.html">Basic Terminology</a> <li><a href="DateTimeConcepts-Calculations.html">Calculations</a><li><a href="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?GDTL/Trade-Offs">Stability, Predictability, and Approximations</a><li><a href="References.html">References</a>
+</ul>
+
+<p>
+<a name="status"><h2>Status and Build</h2></a>
+
+<p>
+This release represents the first release being prepared for submission into Boost. It contains generic components and a gregorian date system. Time representations are being polished for release in the near future.
+<p>
+Please see the Wiki pages for the most recent information:<ul>
+<li><a href="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?GDTL/Build-Test-Compiler_Info">Latest Build Information</a><li><a href="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?GDTL/Current_Limitations">Current Limitations</a></ul>
+<a name="test"><h2>Tests</h2></a>
+
+<p>
+GDTL provides a large number of tests in the 
+<pre>
+   libs/gdtl/test 
+   libs/gdtl/test/gregorian
+   libs/gdtl/test/posix_time
+</pre> 
+<p>
+directories.  Building and executing these tests  assures that the installation is correct and that the library is functioning correctly. In addition, these tests facilitate the porting to new compilers. Finally, the tests provide examples of many functions not explicitly described in the usage examples.
+<p>
+
+<a name="design"><h2>Design and Extensions</h2></a>
+<p>
+A large part of the genesis of this library has been the observation that
+few date-time libraries are built in a fashion that allows customization
+and extension.  A typical example, the calendar logic is built directly
+into the date class.  Or the clock retrieval functions are built directly
+into the time class.  These design decisions usually make it impossible to
+extend or change the library behavior.  At a more fundamental level, 
+there are usually assumptions about the resolution of time representation 
+or the gregorian calendar.  
+<p>
+Often times, the result is that a project must settle for a less
+than complete library because of a requirement for high resolution
+time representation or other assumptions that do not match the
+implementation of the library.  This is extremely unfortunate because
+development of a library of this sort is far from a trivial task.
+<p>
+While the GDTL design is far from perfect the current design is far
+more flexible than any date-time library the author is aware of.  It
+is expected that the various aspects of extensibility will be better
+documented in future versions.  Information about the design goals 
+of the library are <a href="DesignGoals.html">summarized here.</a>
+<p>
+
+<a name="more"><h2>More Info</h2></a>
+
+<p>
+The design of GDTL is currently being evolved using Wiki and email  discussions. You can find more information at:
+<p>
+<ul>
+<li><a href="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?GDTL">Boost Wiki GDTL Start Page</a>
+<li><a href="http://www.crystalclearsoftware.com/libraries/gdtl/gdtl_ref_guide/index.html">Full Doxygen Reference Manual</a></ul>
+
+<hr>
+<address><small>
+<!-- hhmts start -->
+Last modified: Tue Aug 13 15:15:50 MST 2002
+<!-- hhmts end -->
+ by Jeff Garland &copy 2000-2002
+</small></address>
+</body>
+</html>
+