GNUstep Time Zone Reference A person who has very little spare time, and spends it on stuff like GNUstep, anime fanfics, and games. The goddess of the future, who will watch and guide me in my hunt for bugs. May all bow before her divinity. 0.1 6 June, 1997 This documents the interface to the time zone classes in the GNUstep Base Library. Preface

This documents the interface to the time zone classes. These classes are needed for proper adjustment of the local time in each geographical region.

This is also an example, as well as a test case, of the new GNUstep Documentation Markup Language (GDML).

The Time Zone Management Classes

The classes NSTimeZone and NSTimeZoneDetail are used to manage time zones. They are declared in Foundation/NSDate.h.

NSTimeZone is used to specify the time zone region, while NSTimeZoneDetail is used to actually obtain the difference in seconds from UTCUniversal Coordinated Time. that a time zone has for a certain date.

The world is divided into separate time zones because the sun rises at different times. We really should all move underground and match our clocks. However, since this is currently not the case, our computers need a way to find the offset from a single agreed upon time and use that in local time calculations.

To make things even worse, there is this evil thing called daylight saving time, which is usually used for the purpose of utilizing as much of the sun as possible while it is still up. (Really, everyone should stay in their rooms and play with their computers, but for some reason they don't &dots;)

Therefore we need an object that knows about a time zone so that the appropriate object that knows all about offsets from UTC and whether it's daylight saving time for a certain date can be obtained. NSTimeZone is a class that can create such objects.

defaultTimeZone Returns the time zone detail (see ) for the current time. localTimeZone Returns the time zone for the local region. The local region is either specified with the TZ environment variable, or is specified at compile time, with the former taking precedence. timeZoneForSecondsFromGMT: seconds Returns a time zone which is always seconds seconds off from UTC. (In OpenStep the offset is from GMTGreenwich Mean Time., but using UTC makes more sense.) timeZoneWithAbbreviation: abbreviation Returns a time zone detail for which the time zone abbreviation is abbreviation. Note that there can be many time zone details for a single abbreviation. timeZoneWithName: aTimeZoneName Returns a time zone for the geographical region specified by aTimeZoneName. timeZoneDetailForDate: date Returns the appropriate time zone detail for the time zone and the given date date. setDefaultTimeZone: aTimeZone Set the default time zone used for time calculation to the time zone specified by the string aTimeZone. abbreviationDictionary Returns a dictionary that maps a time zone abbreviation to a single arbitrary time zone name. abbreviationMap

Returns a dictionary that maps a time zone abbreviation to an array that holds all the time zone names that use the abbreviation.

This is a GNU extension, and is not defined by OpenStep.

timeZoneName Returns the name for the time zone. timeZoneArray

Returns an array containing 24 arrays that in turn contain the time zone names that are grouped according to the offset from UTC. For example, a time zone that has an offset of 5 hours (or -19 hours) goes into the fifth array in the array.

Note that OpenStep groups them by latitudinal region, and the exact details of the grouping is not specified.

timeZoneDetailArray This returns an array containing all the possible time zone details for the time zone.

A time zone doesn't know the actual offset from UTC that a certain region has, since the offset is not always the same because of changes in time rules and such. Since the details are different for different dates, NSTimeZone must return an object that details the time zone for a specific date. NSTimeZoneDetail is the class for such objects.

It is from NSTimeZoneDetail that we obtain the actual offsets from UTC. In addition, we can obtain the time zone abbreviation (which is also dependent on the date) and whether the time zone uses daylight saving time for the date on which the time zone detail was created.

isDaylightSavingTimeZone If the time zone detail describes a time zone for which the date the detail was created for is daylight saving time, return YES, else return NO. timeZoneAbbreviation Returns the abbreviation for the time zone detail. timeZoneSecondsFromGMT

Returns the offset from UTC for local time in seconds.

Note that OpenStep specifies an offset from GMT to be returned, but using UTC makes more sense.

Afterword

Hopefully, this document shows that GDML is indeed useful for writing documentation for GNUstep.

Even if it is not, it should still be useful since it documents the interface to the time zone classes, and should easily be converted to other text markup formats.

Please send any questions about the DTD or this document to .

And by the way, I've tried out the time zone implementation in the GNUstep Base Library and it seems to work for the following time zone regions:

Asia/Seoul US/Eastern America/Los_Angeles

And here's a small incomplete class definition with somewhat longer method names.

NSObject NSCoding NSCopying A superclass of all classes. perform: aSelector withObject: object1 withObject: object2 This should really go into a protocol definition, but I wanted to show a class definition with protocols. stringWithFormat: format This is not in NSObject, but I wanted to show the use of a variable argument list.

And here's an example:

int function (void *ptr) { return realloc(ptr, 100); }

And here is a macro definition:

a b Return the larger between a and b. Start an exception handling domain.

And here is a type definition:

double Used to save intervals between certain times in seconds.

And here is a function definition:

zone size Allocate size bytes from the dynamic memory allocation zone zone.