1/*
2 * Copyright 2011 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Adrien Destugues, pulkomandy@pulkomandy.ath.cx
7 *		John Scipione, jscipione@gmail.com
8 *		Oliver Tappe, zooey@hirschkaefer.de
9 *
10 * Corresponds to:
11 *		headers/os/locale/TimeZone.h	 rev 42274
12 *		src/kits/locale/TimeZone.cpp	 rev 42274
13 */
14
15
16/*!
17	\file TimeZone.h
18	\ingroup locale
19	\ingroup libbe
20	\brief Provides the BTimeZone class.
21*/
22
23
24/*!
25	\class BTimeZone
26	\ingroup locale
27	\ingroup libbe
28	\brief Defines the time zone API which specifies a time zone, allows you to
29	       display it to the user, and converts between GMT and local time.
30
31	When displaying the name of a time zone to the user, use the display name,
32	not the time zone ID. The display name can be retrieved by the
33	BTimeZone::Name(), BTimeZone::DaylightSavingName(), BTimeZone::ShortName(),
34	and BTimeZone::ShortDaylightSavingName() methods.
35
36	- The standard name looks like "Pacific Standard Time".
37	- The daylight savings time name looks like "Pacific Daylight Time".
38	- The short name looks like either "PST" or "PDT" depending on whether the
39	  standard or daylight savings time name is requested.
40
41	\sa BTimeZone::ID()
42	\sa BTimeZone::Name()
43	\sa BTimeZone::DaylightSavingName()
44	\sa BTimeZone::ShortName()
45	\sa BTimeZone::ShortDaylightSavingName()
46
47	\since Haiku R1
48*/
49
50
51/*!
52	\fn BTimeZone::BTimeZone(const char* zoneID, const BLanguage* language)
53	\brief Construct a timezone from its \a zoneID and \a language.
54
55	The constructor only allows you to construct a timezone if you already
56	know its code. If you don't know the code, you can instead go through the
57	BCountry class which can enumerate all timezones in a country, or use the
58	BLocaleRoster, which knows the timezone selected by the user.
59
60	\param zoneID A time zone ID, for example, "America/Los_Angeles".
61	       This ID is used to call up a specific real-world time zone.
62	\param language The \a language to use when displaying the time zone.
63
64	\since Haiku R1
65*/
66
67
68/*!
69	\fn BTimeZone::BTimeZone(const BTimeZone& other)
70	\brief Copy constructor.
71
72	\param other The BTimeZone object to copy from.
73
74	\since Haiku R1
75*/
76
77
78/*!
79	\fn BTimeZone& BTimeZone::operator=(const BTimeZone& source)
80	\brief Assignment operator.
81
82	\param source The BTimeZone object to copy from.
83
84	\since Haiku R1
85*/
86
87
88/*!
89	\fn const BString& BTimeZone::ID() const
90	\brief Returns the ID of the time zone as a BString, for example,
91	       "America/Los_Angeles".
92
93	When displaying the name of a time zone to the user, use the display name,
94	not the time zone ID.
95
96	\since Haiku R1
97*/
98
99
100/*!
101	\fn const BString& BTimeZone::Name() const
102	\brief Returns the localized name of the time zone, for example
103	       "Pacific Standard Time".
104
105	Use this method to display the time zone's name to the user.
106
107	\since Haiku R1
108*/
109
110
111/*!
112	\fn const BString& BTimeZone::DaylightSavingName() const
113	\brief Returns the localized daylight savings name of the time zone,
114	       for example "Pacific Daylight Time".
115
116	\since Haiku R1
117*/
118
119
120/*!
121	\fn const BString& BTimeZone::ShortName() const
122	\brief Returns the short name of the timezone, in the user's locale,
123	       for example "PST".
124
125	\since Haiku R1
126*/
127
128
129/*!
130	\fn const BString& BTimeZone::ShortDaylightSavingName() const
131	\brief Returns the localized daylight savings name of the time zone,
132	       for example "PDT".
133
134	\since Haiku R1
135*/
136
137
138/*!
139	\fn int BTimeZone::OffsetFromGMT() const
140	\brief Returns the offset, in milliseconds, between the standard time
141	       of a time zone and GMT.
142
143	Positive raw offsets are east of Greenwich, negative offsets are west of
144	Greenwich.
145
146	\return The offset as a number of milliseconds from GMT, positive
147	        or negative.
148
149	\since Haiku R1
150*/
151
152
153/*!
154	\fn bool BTimeZone::SupportsDaylightSaving() const
155	\brief Returns whether or not if the time zone support daylight saving time.
156
157	\return \c true if the time zone supports daylight savings time,
158	        \c false otherwise.
159
160	\since Haiku R1
161*/
162
163
164/*!
165	\fn status_t BTimeZone::InitCheck() const
166	\brief Returns whether or not the constructor initialized the time zone.
167
168	\return \c true if BTimeZone object was initialized successfully, \c false
169	        if there was an error initializing the BTimeZone, for instance if the
170	        constructor or SetTo() was called with an invalid timezone ID.
171
172	\since Haiku R1
173*/
174
175
176/*!
177	\fn status_t BTimeZone::SetTo(const char* zoneCode,
178		const BLanguage* language)
179	\brief Set the BTimeZone object to use a different time zone.
180
181	\param zoneCode The time zone ID to use, for example "America/Los_Angeles".
182	\param language The \a language to use when displaying the time zone.
183
184	\return \c true if time zone was set successfully, \c false if there was an
185	        error setting the time zone, for instance if this method was called
186	        using an invalid \a zoneCode.
187
188	\since Haiku R1
189*/
190