eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Date':
Home

everywhere
www.exept.de
for:
[back]

Class: Date

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--Date
Package:
stx:libbasic
Category:
Magnitude-Time
Version:
rev: 1.135 date: 2010/03/26 14:26:26
user: fm
file: Date.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


Instances of Date represent dates as year, month and day encoded in the 
(private & hidden) instance dateEncoding. The value found there is 
year*100*100 + month*100 + day (which makes magnitude-like comparison of 
dates easy, but is not guaranteed for future versions).
Do not depend on the internal representation.

The old representation used days since 1st Jan. 1901 internally - 
with the new implementation, it is possible to reasonably represent almost 
any Date.  (which insurance companies will like, since they can now 
represent even very old peoples birthday :-)
Notice: no correction for pre-Gregorian dates (< 1583) is done.

The printed representation of dates is controlled by resource definitions -
thus national variants are already supported (see file 'resources/Date.rs').

Compatibility notice:
    due to some historic reasons, there are some methods found twice
    with different names in this class. The old ST/X methods will vanish in
    one of the next releases, and kept for a while to support existing
    applications (the info on how these methods should be named came 
    somewhat late from the testers ..).

    Please do not use methods marked as obsolete in their comment.

Most useful methods:

    Date today
    (Date today) addDays:
    (Date today) subtractDays:

Related information:

    Time
    AbstractTime
    Filename
    OperatingSystem

Class protocol:

Compatibility-Dolphin
o  newDay: day monthIndex: month year: year

Compatibility-ST80
o  newDay: day monthNumber: monthIndex year: year
ST80 compatibility

Compatibility-Squeak
o  current
return the current date

o  fromSeconds: seconds
Answer an instance of me which is 'seconds' seconds after January 1, 1901.

o  readMMDDYYYYFrom: aStringOrStream onError: exceptionBlock
return a new Date, reading a printed representation from aStream.
Notice, that this is not the storeString format and
is different from the format expected by readFrom:

o  readYYYYMMDDFrom: aStringOrStream onError: exceptionBlock
return a new Date, reading a printed representation from aStream.
Notice, that this is not the storeString format and
is different from the format expected by readFrom:

Javascript support
o  js_new: aString
return a parsed dateobejct

o  now
return the current date

change & update
o  update: something with: aParameter from: changedObject

error handling
o  conversionErrorSignal
return the signal used for conversion error handling

general queries
o  abbreviatedNameOfDay: dayIndex
given a day index (1..7), return the abbreviated name
of the day

o  abbreviatedNameOfDay: dayIndex language: lang
given a day index (1..7), return the abbreviated name
of the day.
For nil, Smalltalk language is used,
for unknown languages, english is used.

o  abbreviatedNameOfMonth: monthIndex
given a month index (1..12), return the abbreviated name
of the month

o  abbreviatedNameOfMonth: monthIndex language: lang
given a month index (1..12), return the abbreviated name
of the month.
For nil, Smalltalk language is used,
for unknown languages, english is used.

o  dateAndTimeNow
return an array containing the date and time of now

o  dayOfFirstWeekInYear: aYear
for a given year, return the day corresponding to that years monday of week-01.
The 1st week is the one, in which the first thursday is found;
and the 1st day of that week is the preceeding monday
(that means: that the returned day might be a day of the previous year)

o  dayOfWeek: dayName
given the name of a day (either string or symbol),
return the day-index (1 for monday; 7 for sunday).
Return 0 for invalid day name

o  dayOfWeek: dayName language: lang
given the name of a day (either string or symbol),
return the day-index (1 for monday; 7 for sunday).
Return 0 for invalid day name.
For nil, Smalltalk language is used,
for unknown languages, english is used.

o  daysInMonth: month forYear: yearInteger
given the name of a month and a year, return the number
of days this month has (modified GNU).
return 0 if the month name was invalid.
For your convenience, month maybe an integer or name-string.

o  daysInYear: yearInteger
return the number of days in a year

o  daysUntilMonth: month forYear: yearInteger
given the name of a month and a year, return the number
of days from 1st january to last of prev month of that year.
Return 0 if the month name/index is invalid or is january.
For your convenience, month maybe an integer or name-string.

o  defaultFormatString

o  firstDayOfYear: inYear
return the weekDay-index of the 1st-january of the given year.
1->monday, 2->tuesday, ... 7->sunday

o  indexOfMonth: aMonthString
given the name of a month (either string or symbol),
return the month-index (1 for jan; 12 for december).
The given string may be a full or abbreviated name,
case is ignored.
Return 0 for invalid month name.

o  indexOfMonth: aMonthString language: lang
given the name of a month (either string or symbol),
return the month-index (1 for jan; 12 for december).
The given string may be a full or abbreviated name,
case is ignored.
Return 0 for invalid month name.
For nil, Smalltalk language (i.e. the current language setting) is used,
for unknown languages, english is used.

o  leapYear: yearInteger
return true, if yearInteger is a leap year.

o  longFormatString

o  monthAndDayFromDayInYear: aDayInYear forYear: yearInteger
given a day-in-year (1..365) return an Array containing the
month index and the day-in-month. Return nil if the argument is invalid.

o  nameOfDay: dayIndex
given a day index (1..7), return the name of the day

o  nameOfDay: dayIndex language: lang
given a day index (1..7), return the name of the day.
For nil, Smalltalk language is used,
for unknown languages, english is used.

o  nameOfMonth: monthIndex
given a month index (1..12), return the name of the month

o  nameOfMonth: monthIndex language: lang
given a month index (1..12), return the name of the month.
For nil, Smalltalk language is used,
for unknown languages, english is used.

o  shortFormatString

o  weekInYearOf: aDateOrTimestamp
for a given date or timeStamp, return the week-number.
the returned week number starts with 1 for the first week which has a thursday in it.
The above definition can lead to the 1st week starting in the old year!

o  yearAsDays: yearInteger
Returns the number of days since Jan 1, 1901. (GNU)
to the first Jan of the year, yearInteger.
For 1901 this is zero, for 1902 its 365.
Defined for years >= 1901

initialization
o  initDefaultNames
read the language specific names.

o  initNames
read the language specific names.

o  initNamesForLanguage: language
read the language specific names.

o  initialize

instance creation
o  fromDays: dayCount
return a new Date, given the day-number starting with 0 at 1.Jan 1901;
(i.e. 'Date fromDays:0' returns 1st Jan. 1901).
Date asDays is the reverse operation.
Added for GNU/ST-80 compatibility

o  newDay: day month: month year: year
return a new Date, given the day, month and year.
For your convenience, month may be either an integer
or the months name as a string.

WARNING: semantics changed: 0..99 is no longer treated as 1900..1999,
but as 0..99 now.
Any such adjustments must be made by the caller of this method now
(see those, for example readFrom:onError:)

o  newDay: dayInYear year: year
return a new Date, given the year and the day-in-year (starting at 1).
See also: Date today / Time now / Timestamp now.
ST-80 compatibility

o  readFrom: aStringOrStream onError: exceptionBlock
return a new Date, reading a printed representation from aStream.
Notice, that this is not the storeString format and
is different from the format expected by readFrom:.
BUG:
This method handles american format (i.e. month/day/year),
common format with letter month in the middle (10 December 2007)
and ISO format (yyyy-mm-dd) - as long as yyyy is > 12.

It does not handle the german/french and other dd-mm-yyyy.
use readFrom:printFormat:onError: for this.

o  readFrom: aStringOrStream printFormat: aSqueakFormatArrayOrFormatString
return a new Date, reading a printed representation from aStream.
aSqueakFormatArrayOrFormatString may either be a squeak formatArray
1 day position (1, 2 or 3)
2 month position (1..3)
3 year position (1..3)
or a formatString (see printing instance protocol).

o  readFrom: aStringOrStream printFormat: aSqueakFormatArrayOrFormatString language: languageOrNil onError: exceptionBlock
return a new Date, reading a printed representation from aStream.
aSqueakFormatArrayOrFormatString may either be a squeak formatArray
1 day position (1, 2 or 3)
2 month position (1..3)
3 year position (1..3)
or a formatString (see printing instance protocol).
For now %d, %m, %monthName, %shortMonthName and %y are supported in the formatString.
The formatString can have any of these characters '-.:,;/' as separator.
The formatString can also use a space as separator (for ex. '%d %m %y') and any separator will be allowed.
However, when a character separator is defined, only that separator will be expected.
TODO: make this a general feature of all DateAndTime classes.

o  readFrom: aStringOrStream printFormat: aSqueakFormatArrayOrFormatString onError: exceptionBlock
return a new Date, reading a printed representation from aStream.
aSqueakFormatArrayOrFormatString may either be a squeak formatArray
1 day position (1, 2 or 3)
2 month position (1..3)
3 year position (1..3)
or a formatString (see printing instance protocol).
All of the %-formats as in the printString are supported here.
(i.e. %d, %m and %y, %shortMonthName and %monthName)
TODO: make this a general feature of all DateAndTime classes.

o  today
return a date, representing today.
See also: Time now / Timestamp now.

o  tomorrow
return a date, representing tomorrow.
See also: Time now / Timestamp now.

o  yesterday
return a date, representing yesterday.
See also: Time now / Timestamp now.

obsolete
o  day: day month: month year: year
return a new Date, given the day, month and year.
Obsolete:
use newDay:month:year: for ST-80 compatibility

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  day: dayInYear year: year
return a new Date, given the year and the day-in-year (starting at 1).
Obsolete:
use newDay:year: for ST-80 compatibility

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  isLeapYear: yearInteger
Return true, if a year is a leap year.
Obsolete:
Please use the ST-80 compatible #leapYear for new programs,
since this method will vanish.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

private
o  abbreviatedMonthNamesForLanguage: language

o  dayAbbrevsForLanguage: language

o  dayNamesForLanguage: language

o  daysInMonthIndex: monthIndex forYear: yearInteger
return the number of days in month monthIndex of
year yearInteger (modified GNU).
Return 0 for invalid month index.
This is the internal version of daysInMonth:forYear:

o  daysUntilMonthIndex: monthIndex forYear: yearInteger
return the number of days in month monthIndex of
year yearInteger (modified GNU).
Return 0 for invalid month index.
This is the internal version of daysInMonth:forYear:

o  monthAbbrevsForLanguage: language

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  monthNamesForLanguage: language

private-encoding/decoding
o  encodeYear: y month: m day: d
the internal encoding is strictly private,
and should not be used outside.

o  readDatePartFrom: str format: fmt language: languageOrNil
read a single component (such as %shortName) from str

private-instance creation
o  fromOSTime: osTime
return a date, representing the date given by the operatingSystem time.
This somewhat clumsy implementation hides the OS's date representation
(i.e. makes this class independent of what the OS starts its time values with).
Dont use this method, the osTime representation is totally unportable.

Instance protocol:

Compatibility-ANSI
o  dayOfWeek
return the week-day of the receiver - 1 is sunday, 7 for saturday.
WARNING: different from dayInWeek (which returns 1 for monday, ... 7 for sunday).

o  dayOfWeekAbbreviation
return the short week-day of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'mon', 'tue' ...

o  dayOfWeekName
return the week-day of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'monday', 'tuesday' ...

o  dayOfYear
return the day-nr within the year of the receiver - 1..365/366

o  isLeapYear
return true, if the receivers year is a leap year

o  monthAbbreviation
return the month of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'jan', 'feb' ...

Compatibility-ST80
o  firstDayInMonth
Return the first day in the month of the receiver

o  lastDayInMonth
Return the last day in the month in which the receiver is.

o  next: dayName
Return the next date whose weekday name is dayName.
Caveat; dayName is expected to be in the current language

o  nextDayWithIndex: dayIndex
Return the next date whose weekday name is dayName.
dayIndex is Monday=1, ... , Sunday=7

o  previous: dayName
Return the previous date whose weekday name is dayName.
Caveat; dayName is expected to be in the current language

o  previousDayWithIndex: dayIndex
Return the previous date whose weekday name is dayIndex.
dayIndex is Monday=1, ... , Sunday=7

o  printFormat: aFormatArray
Obsolete, backward ST-80 compatible formatted printing - see printStringFormat:
Return a string containing a printed representation of the receiver.
The formatArray argument consists of 6 or 7 integers which control
the resulting string. The entries are:
1 day position (1, 2 or 3)
2 month position (1..3)
3 year position (1..3)
4 asciiValue of separator character or separator character
or collection of 2 separator characters
5 month format (1: numeric; 2: abbreviated name; 3: fullname
4: abbreviated uppercase 5: full uppercase)
6 year format (1 include century; 2 exclude century)
7 (optional) true/false.
if true, print numbers in 2-digit format
(i.e. with leading zeros);
Taken as false, if ommited

Day and monthnames are in the currently active language.

This method supports more options than the ST-80 version; month formats
4 and 5, non-numeric separators and the optional 7th parameter are not
supported by ST-80. Be aware of this for compatibility reasons.

Notice that not all formats can be scanned (correctly) by #readFrom:
This is an ST-80 compatibility method - I would have choosen another
(less cryptic) formatString ...

o  printFormat: aFormatArray forLanguage: languageOrNil
Obsolete, backward ST-80 compatible formatted printing - see printStringFormat:
Return a string containing a printed representation of the receiver.
The formatArray argument consists of 6 or 7 integers which control
the resulting string. The entries are:
1 day position (1, 2 or 3)
2 month position (1..3)
3 year position (1..3)
4 asciiValue of separator character or separator character
or collection of 2 separator characters
5 month format (1: numeric; 2: abbreviated name; 3: fullname
4: abbreviated uppercase 5: full uppercase)
6 year format (1 include century; 2 exclude century)
7 (optional) true/false.
if true, print numbers in 2-digit format
(i.e. with leading zeros);
Taken as false, if ommited

Day and monthnames are in the currently active language.

This method supports more options than the ST-80 version; month formats
4 and 5, non-numeric separators and the optional 7th parameter are not
supported by ST-80. Be aware of this for compatibility reasons.

Notice that not all formats can be scanned (correctly) by #readFrom:
This is an ST-80 compatibility method - I would have choosen another
(less cryptic) formatString ...

o  printFormat: aFormatArray forLanguage: languageOrNil on: aStream
Obsolete, backward ST-80 compatible formatted printing - see comment
in printFormat:.
Append a printed representation of the receiver to aStream.
The argument, aFormatString controls the format, as described
in the #printFormat: method.
Notice that not all formats can be scanned (correctly) by #readFrom:

o  printFormat: aFormatArray on: aStream
Obsolete, backward ST-80 compatible formatted printing - see comment
in printFormat:.
Append a printed representation of the receiver to aStream.
The argument, aFormatString controls the format, as described
in the #printFormat: method.
Notice that not all formats can be scanned (correctly) by #readFrom:

o  shortPrintString
dummy - for now

o  weekdayIndex
Return the day index; Monday=1, ... , Sunday=7

Compatibility-Squeak
o  mmddyyyy
return a printed representation of the receiver in the
form mmddyyyy.
The receiver can be reconstructed with:
Date readMMDDYYYYFrom:aStringOrStream onError:[...]

accessing
o  abbreviatedDayName
return the short week-day of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'mon', 'tue' ...

o  abbreviatedMonthName
return the month of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'jan', 'feb' ...

o  abbreviatedMonthNameForLanguage: lang
return the month of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'jan', 'feb' ...

o  asDays
return the number of days elapsed since 01-Jan-1901
and the receiver's day; starts with 0 for 1-1-1901.
Date>>fromDays: is the reverse operation.
For ST-80 compatibility.

o  asSeconds
return the seconds between 1.jan.1901 and the same time in the receivers
day. (i.e. midnight to midnight).
This does not include any leapSeconds ... strictly speaking, this is incorrect.
ST-80 compatibility.

o  day
return the day (1..31) of the receiver

o  dayInWeek
return the week-day of the receiver - 1 for monday, 7 for sunday.
WARNING: different from ANSIs dayOfWeek (which returns 1 for sunday, ... 7 for saturday).
WARNING: does not care for pre-gregorian dates
(i.e. do not use this for dates before 1583)

o  dayInYear
return the day-nr within the year of the receiver - 1 .. 365/366

o  dayOfMonth
Answer the day of the month represented by me.
Same as day; for ST-80 compatibility.

o  daysInMonth
return the number of days in the month of the receiver

o  daysInYear
return the number of days in the year of the receiver

o  daysLeftInMonth
return the number of days left in the month of the receiver

o  daysLeftInYear
return the number of days left in the year of the receiver.
Today is excluded from the count (i.e. in a non-leap-year,
the first january will return 364)

o  leap
return true, if the receivers year is a leap year

o  month
return the month (1..12) of the receiver

o  monthIndex
return the index of the month (e.g. Feb.=2).
Same as month; for ST-80 compatibility.

o  monthName
return the month of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'january', 'february' ...

o  monthNameForLanguage: languageOrNil
return the month of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'january', 'february' ...

o  weekInYear
return the week number of the receiver - 1 for Jan, 1st.
each week is Mon .. Sun (i.e. Sunday belongs to the previous week)

o  weekday
return the week-day of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'monday', 'tuesday' ...
For ST-80 compatibility

o  year
return the year (1..12) of the receiver

o  year: year month: month day: day

arithmetic
o  + days
return a new date representing 'days' after the receiver.
The argument should be some kind of integer.
This is the same as #addDays.

o  - aDateOrNumberOfDays
return the delta in days (anInteger) between 2 dates or
subtract a number of days from a date returning a Date

o  addDays: days
return a new date representing 'days' after the receiver.
The argument should be some kind of integer.
For ST-80 compatibility.

o  daysSince: aDate
return the number of days between the receiver and the argument,
aDate, which should be some kind of date

o  daysUntil: aDate
return the number of days between the receiver and the argument,
aDate, which should be some kind of date

o  firstDayInPreviousMonth: nMonths
Return the first day of a previous month (0=this month, 1=prev. month, etc.)

o  firstDayOfPreviousMonth: nMonths
Return the first day of a previous month (0=this month)

o  subtractDate: aDate
return the number of days between the receiver and aDate

o  subtractDays: days
return a new date representing 'days' before the receiver.
The argument should be some kind of integer.
For ST-80 compatibility

comparing
o  < aDate
return true, if the date represented by the receiver
is before the argument, aDate

o  = aDate
return true, if the date represented by the receiver
is the same as the one represented by argument, aDate

o  > aDate
return true, if the date represented by the receiver
is after the argument, aDate

o  hash
return an integer useful for hashing on dates

converting
o  asDate
return the receiver

o  asTimeStamp
Answer the receiver as a TimeStamp at midnight.

o  asTimestamp
return an TimeStamp instance, representing midnight of last night

obsolete
o  asAbsoluteTime
deprecated, use #asTimestamp

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  dayCount
return the number of days since 1st. Jan. 1901;
starting with 0 for this date.
Date>>fromDays: is the reverse operation.
Obsolete:
please use asDays for ST-80 compatibility

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  dayName
return the week-day of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'monday', 'tuesday' ...
Obsolete:
use #weekday for ST-80 compatibility

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  minusDays: days
return a new date representing 'days' before the receiver.
The argument should be some kind of integer.
Obsolete:
Please dont use this method since it will vanish.
Use #subtractDays: instead for ST-80 compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  plusDays: days
return a new date representing 'days' after the receiver.
The argument should be some kind of integer.
Obsolete:
Please dont use this method since it will vanish.
Use #addDays: instead for ST-80 compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

printing & storing
o  addPrintBindingsTo: aDictionary

o  addPrintBindingsTo: aDictionary language: languageOrNil
private print support: add bindings for printing to aDictionary.
languageOrNil can only be #en or nil for the current language.
valid format items are:
%d - day, 01..31 0-padded to length 2
%m - month, 01..12 0-padded to length 2
%w - week in year, 00..53 0-padded to length 2
%y - year, full i.e. 1999, 2004

special:
%D - day - unpadded
%M - month - unpadded
%W - week in year - unpadded
%Y - year, last 2 digits only i.e. 99, 04 (danger: year 2k bug)

%weekDay - day in week (1->monday, 2->tuesday, ... ,7->sunday)

%dayName - full day name
%DayName - full day name, first character uppercase
%DAYNAME - full day name, all uppercase

%monthName - full month name
%MonthName - full month name, first character uppercase
%MONTHNAME - full month name, all uppercase

%shortDayName - short (abbreviated) day name
%ShortDayName - short (abbreviated) day name, first character uppercase
%SHORTDAYNAME - short (abbreviated) day name, all uppercase

%shortMonthName - short (abbreviated) month name
%ShortMonthName - short (abbreviated) month name, first character uppercase
%SHORTMONTHNAME - short (abbreviated) month name, all uppercase

%nth - counting day-in-month (1->'st'; 2->'nd'; 3->'rd'; 4...->'th')
%weekDayNth - counting day-in-week (1->'st'; 2->'nd'; 3->'rd'; 4...->'th')
%weekNth - counting week-in-year (1->'st'; 2->'nd'; 3->'rd'; 4...->'th')

o  printOn: aStream
append a printed representation of the receiver to aStream

o  printOn: aStream format: aFormatStringOrSqueakFormatArray
print using a format string;
see #addPrintBindingsTo: for a list of valid format strings

o  printOn: aStream format: aFormatStringOrSqueakFormatArray language: languageOrNil
print using a format string;
languageOrNil can only be #en or nil for the current language.
see #addPrintBindingsTo: for a list of valid format strings

o  printOn: aStream language: languageOrNil
append a printed representation of the receiver to aStream.
The argument languageOrNil can only be #en or nil for the current language.

o  printStringFormat: aFormatStringOrArray
print using a format string;
see #addPrintBindingsTo: for a list of valid format strings

o  printStringFormat: aFormatStringOrArray language: languageOrNil
print using a format string;
languageOrNil can only be #en or nil for the current language.
see #addPrintBindingsTo: for a list of valid format strings

o  storeOn: aStream
append a representation to aStream, from which the receiver
can be reconstructed

o  yyyymmdd
no delimiters

private-accessing
o  dateEncoding
the internal encoding is stricktly private,
and should not be used outside.

o  dateEncoding: anInteger
the internal encoding is stricktly private,
and should not be used outside.

o  fromOSTime: osTime
set my dateEncoding from an OS time.
This somewhat clumsy implementation hides the OS's date representation
(i.e. makes this class independent of what the OS starts its time values with).
Don't use this method, the osTime representation is totally unportable.

o  getMilliseconds
compatibility with Timestamp for comparing

visiting
o  acceptVisitor: aVisitor with: aParameter


ST/X 6.1.1; WebServer 1.620 at exept:8081; Wed, 23 May 2012 08:47:20 GMT