[Python-checkins] python/nondist/sandbox/datetime doc.txt,1.2,1.3

[tim_one@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/sandbox/datetime
In directory sc8-pr-cvs1:/tmp/cvs-serv29188

Modified Files:
	doc.txt 
Log Message:
Started documenting the date class; much more is needed, and I see some
methods in the Python implementation don't yet exist in the C
implementation.


Index: doc.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/datetime/doc.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** doc.txt	4 Dec 2002 04:12:01 -0000	1.2
--- doc.txt	4 Dec 2002 19:49:11 -0000	1.3
***************
*** 33,36 ****
--- 33,47 ----
  
  
+ Module constants
+ ================
+ MINYEAR
+     The smallest year number allowed in a date, datetime, or datetimetz
+     object.
+ 
+ MAXYEAR
+     The largest year number allowed in a date, datetime, or datetimetz
+     object.
+ 
+ 
  class timedelta
  ===============
***************
*** 98,101 ****
--- 109,115 ----
        This is exact, but may overflow.
  
+     - certain additions and subtractions with date, datetime, and datimetz
+       objects (see below)
+ 
      - timedelta // (int or long) -> timedelta
        The floor is computed and the remainder (if any) is thrown away.
***************
*** 111,121 ****
      - pickling
  
- In addition, subtraction of two datetime objects returns a timedelta,
- and addition or subtraction of a datetime and a timedelta returns a
- datetime.
- 
  
  class date
  ==========
  
  
--- 125,198 ----
      - pickling
  
  
  class date
  ==========
+ A date object represents a date (year, month and day) in an idealized
+ calendar, the current Gregorian calendar indefinitely extended in both
+ directions.  January 1 of year 1 is called day number 1, January 2 of year
+ 1 is called day number 2, and so on.  This matches the definition of the
+ "proleptic Gregorian" calendar in Dershowitz and Reingold's book
+ "Calendrical Calculations", where it's the base calendar for all
+ computations.  See the book for algorithms for converting between
+ proleptic Gregorian ordinals and many other calendar systems.
+ 
+ Constructor:
+ 
+     date(year, month, day)
+ 
+     All arguments are required.  Arguments may be ints or longs, in the
+     following ranges:
+ 
+         MINYEAR <= year <= MAXYEAR
+         1 <= month <= 12
+         1 <= day <= number of days in the given month and year
+ 
+     If an argument outside those ranges is given, ValueError is raised.
+ 
+ 
+ Class attributes:
+ 
+     .min
+         The earliest representable date, date(MINYEAR, 1, 1).
+ 
+     .max
+         The latest representable date, date(MAXYEAR, 12, 31).
+ 
+     .resolution
+         The smallest possible difference between non-equal date
+         objects, timedelta(days=1).
+ 
+ Instance attributes (read-only):
+ 
+     .year           between MINYEAR and MAXYEAR inclusive
+     .month          between 1 and 12 inclusive
+     .day            between 1 and the number of days in the given month
+                     of the given year
+ 
+ Supported operations:
+ 
+     - date1 + timedelta -> date2
+       timedelta + date1 -> date2
+       date2 is timedelta.days days removed from the date1, moving forward
+       in time if timedelta.days > 0, and date2 - date1 == timedelta.days
+       after.  timedelta.seconds and timedelta.microseconds are ignored.
+       OverflowError is raised if date2.year would be smaller than MINYEAR
+       or larger than MAXYEAR.
+ 
+     - date1 - timedelta -> date2
+       The same as date1 + (-timedelta).
+ 
+     - date1 - date2 -> timedelta
+       This is exact, and cannot overflow.  timedelta.seconds and
+       timedelta.microseconds are 0, and date2 + timedelta == date1
+       after.
+ 
+     - comparison of date to date, where date1 is considered less than
+       date2 when date1 precedes date2 in time.
+ 
+     - hash, use as dict key
+ 
+     - pickling
+