> The restructuring of the comment on the mechanisms for specifying the
> local timezone looks like an improvement to me.
Thank you.
> The comments on the filesystem layout look reasonable but ...
> 1. I think filesystem documentation should reside in *one* place, and
> the comments in this file should just direct you to it.
Perhaps. I agree that there needs to be a single reference point for file
system documentation so that you know where to look.
However, at the moment assumptions about the file system are scattered
throughout the code. {NSBundle, NSUser, GSLocale, NSTimeZone, NSFileHandle,
NSTask, NSUserDefaults, NSMessagePort... }
There isn't any one place for this to go. Yet.
Also, in order to understand what the NSTimeZone code does you need to know
about the file system assumptions and decisions. It makes sense to me to
document that in the code where it's used so that you can work on just this
module. I think it makes it easier to assess the design and impact of
changes. It's of more interest to the developer than anyone else.
My feeling is that detailed techinical 'File System Information' should be put
into those modules which make decisions or assumptions. We can then create an
overview document which contains references to these details.
Perhaps we could even extend autogsdoc to create it all automatically as part
of base developer documentation?
My idea is that the GFHS states the standard. Intended audience is all users.
The developer overview doc tells you what is what and where. The intended
audience is application developers and power users.
The comments in the modules tell you how and why. The intended audience is
gnustep-core developers and those seeking to extend/over-ride those
libraries.
> 2. I'm not sure about suggesting linking to existing posix files
I'm trying not to "suggest" that this is done but rather noting that it can be
done. If that's not too clear perhaps it needs to be re-phrased.
They are "time zone information files" from the Olson database. Glibc, Solaris
and many others use the same source. There is _no_ difference in the content
of those files or their file names. GNUstep simply adds the GMT-14 to GMT+14
zone files and generates "regions" and "abbreviations".
The current gnustep distribution uses 2002 rev c which has been superseeded.
The files are now outdated for Iran, MST, NZ, Portugal, Canada, Europe/
Berlin, parts of America etc
GNUstep needs to maintain a current distribution of this data. By linking to
information provided by someone else this maintenance burden can be eased.
The GMT zones are geographic regions, unencumbered with politics. They won't
change.
> Perhaps you could re-do this with a patch which maintains the existing
> use of spaces/tabs/indentation?
Here it is:
--- ../core/base/Source/NSTimeZone.m.cvs 2003-11-19 17:39:06.000000000 +0800
+++ ../core/base/Source/NSTimeZone.m.current 2003-12-20 21:21:19.000000000 +0800
@@ -4,7 +4,7 @@
Written by: Yoo C. Chung <[EMAIL PROTECTED]>
Date: June 1997
- Rewritw large chunks by: Richard Frith-Macdonald <[EMAIL PROTECTED]>
+ Rewrite large chunks by: Richard Frith-Macdonald <[EMAIL PROTECTED]>
Date: September 2002
This file is part of the GNUstep Base Library.
@@ -39,13 +39,45 @@
eventually have to change the implementation to prevent the year
2038 problem.)
- The local time zone can be specified with the user defaults
- database, the GNUSTEP_TZ environment variable, the file LOCAL_TIME_FILE,
- the TZ environment variable, or the fallback time zone (which is UTC),
+ The local time zone can be specified with:
+ 1) the user defaults database
+ 2) the GNUSTEP_TZ environment variable
+ 3) the file LOCAL_TIME_FILE in _time_zone_path()
+ 4) the TZ environment variable
+ 5) or the fallback time zone (which is UTC)
with the ones listed first having precedence.
Any time zone must be a file name in ZONES_DIR.
+ Files & File System Heirarchy info:
+ ===================================
+
+ Default place for the NSTimeZone directory is _time_zone_path():
+ {$(GNUSTEP_SYSTEM_ROOT)Libary/Libraries/Resources/TIME_ZONE_DIR}
+
+ LOCAL_TIME_FILE is a text file with the name of the time zone file.
+
+ ZONES_DIR is a sub-directory under TIME_ZONE_DIR
+
+ (dir) ../System/Library/Libraries/Resources/..
+ (dir) NSTimeZone
+ (file) localtime {text; time zone eg Australia/Perth}
+ (dir) zones
+
+ Since NSTimeZone gets the name from LOCAL_TIME_FILE it's sufficient
+ to symlink this to the time zone name used elsewhere. For example:
+ Debian uses "/etc/timezone"
+
+ A number of POSIX systems have the zone files already installed.
+ For these systems it is sufficient to symlink ZONES_DIR to the
+ platform specific location.
+ For (g)libc6 this is /usr/share/zoneinfo
+ For Solaris this is /usr/share/lib/zoneinfo
+
+ Note that full zone info is required, especially the various "GMT"
+ files which are created especially for OPENSTEP compatibility.
+ Zone info comes from the Olson time database.
+
FIXME?: use leap seconds? */
#include "config.h"
@@ -87,7 +119,8 @@
/* Key for local time zone in user defaults. */
#define LOCALDBKEY @"Local Time Zone"
-/* Directory that contains the time zone data. */
+/* Directory that contains the time zone data.
+ Expected in Resources directory for library bundle. */
#define TIME_ZONE_DIR @"NSTimeZones"
/* Location of time zone abbreviation dictionary. It is a text file
@@ -113,7 +146,7 @@
@class GSTimeZoneDetail;
@class GSAbsTimeZoneDetail;
[EMAIL PROTECTED] GSPlaceholderTimeZone;
[EMAIL PROTECTED] GSPlaceholderTimeZone;
/*
* Information for abstract placeholder class.
@@ -127,8 +160,8 @@
*/
struct ttinfo
{
- char offset[4]; // Seconds east of UTC
- unsigned char isdst; // Daylight savings time?
+ char offset[4]; // Seconds east of UTC
+ unsigned char isdst; // Daylight savings time?
unsigned char abbr_idx; // Index into time zone abbreviations string
};
@@ -856,14 +889,23 @@
* wildly between OSes (this could be a big problem when
* archiving is used between different systems).
* </p>
+ * On platforms where the zone info files are already installed
+ * elsewhere it is sufficient to use a symlink provided the GMT+/-
+ * zones are added.
*/
@implementation NSTimeZone
+/**
+ * DEPRICATED.
+ */
+ (NSDictionary*) abbreviationDictionary
{
return fake_abbrev_dict;
}
+/**
+ * Returns an abbreviation to time zone map which is quite large.
+ */
+ (NSDictionary*) abbreviationMap
{
/* Instead of creating the abbreviation dictionary when the class is
@@ -1102,21 +1144,25 @@
*/
systemTimeZone = RETAIN([NSTimeZoneClass timeZoneForSecondsFromGMT: 0]);
+ /*
+ * Try to get timezone from user defaults database
+ */
localZoneString = [[NSUserDefaults standardUserDefaults]
stringForKey: LOCALDBKEY];
+
+ /*
+ * Try to get timezone from GNUSTEP_TZ environment variable.
+ */
if (localZoneString == nil)
{
- /*
- * Try to get timezone from GNUSTEP_TZ environment variable.
- */
localZoneString = [[[NSProcessInfo processInfo]
environment] objectForKey: @"GNUSTEP_TZ"];
}
+ /*
+ * Try to get timezone from LOCAL_TIME_FILE.
+ */
if (localZoneString == nil)
{
- /*
- * Try to get timezone from LOCAL_TIME_FILE.
- */
NSString *f = _time_zone_path(LOCAL_TIME_FILE);
if (f != nil)
{
@@ -1125,21 +1171,21 @@
}
}
#if HAVE_TZSET
+ /*
+ * Try to get timezone from tzset and tzname
+ */
if (localZoneString == nil)
{
- /*
- * Try to get timezone from tzset and tzname
- */
tzset();
if (tzname[0] != NULL && *tzname[0] != '\0')
localZoneString = [NSString stringWithCString: tzname[0]];
}
#else
+ /*
+ * Try to get timezone from standard unix environment variable.
+ */
if (localZoneString == nil)
{
- /*
- * Try to get timezone from standard unix environment variable.
- */
localZoneString = [[[NSProcessInfo processInfo]
environment] objectForKey: @"TZ"];
}
@@ -1177,10 +1223,14 @@
return zone;
}
+/**
+ * Returns an array of all the known regions.<br />
+ * There are 24 elements, of course, one for each time zone.
+ * Each element contains an array of NSStrings which are
+ * the region names.
+ */
+ (NSArray*) timeZoneArray
{
- /* We create the array only when we need it to reduce overhead. */
-
static NSArray *regionsArray = nil;
int index, i;
char name[80];
@@ -1188,6 +1238,7 @@
id temp_array[24];
NSString *fileName;
+ /* We create the array only when we need it to reduce overhead. */
if (regionsArray != nil)
return regionsArray;
@@ -1228,7 +1279,9 @@
}
/**
- * Returns a timezone for the specified abbrevition,
+ * Returns a timezone for the specified abbrevition. The same abbreviations
+ * are used in different regions so this isn't particularly useful.<br />
+ * Calls NSTimeZone-abbreviation dictionary an so uses a lot of memory.
*/
+ (NSTimeZone*) timeZoneWithAbbreviation: (NSString*)abbreviation
{
@@ -1251,13 +1304,14 @@
}
/**
- * Returns a timezone for the specified name, created from the supplied data.
+ * Returns a timezone for aTimeZoneName, created from the supplied
+ * time zone data. Data must be in TZ format as per the Olson database.
*/
-+ (NSTimeZone*) timeZoneWithName: (NSString*)name data: (NSData*)data
++ (NSTimeZone*) timeZoneWithName: (NSString*)aTimeZoneName data: (NSData*)data
{
NSTimeZone *zone;
- zone = [defaultPlaceholderTimeZone initWithName: name data: nil];
+ zone = [defaultPlaceholderTimeZone initWithName: aTimeZoneName data: data];
return AUTORELEASE(zone);
}
@@ -1285,6 +1339,9 @@
return abbr;
}
+/**
+ * Returns the Class for this object
+ */
- (Class) classForCoder
{
return NSTimeZoneClass;
@@ -1303,6 +1360,9 @@
return nil;
}
+/**
+ * Returns the name of this object.
+ */
- (NSString*) description
{
return [self name];
@@ -1381,6 +1441,9 @@
return [self isEqualToTimeZone: other];
}
+/*
+ * Returns TRUE if the time zones have the same name.
+ */
- (BOOL) isEqualToTimeZone: (NSTimeZone*)aTimeZone
{
if (aTimeZone == self)
@@ -1434,16 +1497,25 @@
return offset;
}
+/**
+ * DEPRICATED: see NSTimeZoneDetail
+ */
- (NSArray*) timeZoneDetailArray
{
return [self subclassResponsibility: _cmd];
}
+/**
+ * DEPRICATED: see NSTimeZoneDetail
+ */
- (NSTimeZoneDetail*) timeZoneDetailForDate: (NSDate*)date
{
return [self subclassResponsibility: _cmd];
}
+/**
+ * Returns the name of this timezone.
+ */
- (NSString*) timeZoneName
{
return [self name];
2003-12-13 Sheldon Gill <[EMAIL PROTECTED]>
* Source/NSTimeZone.m: Added documentation and clean up.
[NSTimeZone initTimeZoneWithName:data:] now uses data.
_______________________________________________
Bug-gnustep mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/bug-gnustep
