Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ucal.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /*
jpayne@69 4 *******************************************************************************
jpayne@69 5 * Copyright (C) 1996-2015, International Business Machines Corporation and
jpayne@69 6 * others. All Rights Reserved.
jpayne@69 7 *******************************************************************************
jpayne@69 8 */
jpayne@69 9
jpayne@69 10 #ifndef UCAL_H
jpayne@69 11 #define UCAL_H
jpayne@69 12
jpayne@69 13 #include "unicode/utypes.h"
jpayne@69 14 #include "unicode/uenum.h"
jpayne@69 15 #include "unicode/uloc.h"
jpayne@69 16 #include "unicode/localpointer.h"
jpayne@69 17
jpayne@69 18 #if !UCONFIG_NO_FORMATTING
jpayne@69 19
jpayne@69 20 /**
jpayne@69 21 * \file
jpayne@69 22 * \brief C API: Calendar
jpayne@69 23 *
jpayne@69 24 * <h2>Calendar C API</h2>
jpayne@69 25 *
jpayne@69 26 * UCalendar C API is used for converting between a <code>UDate</code> object
jpayne@69 27 * and a set of integer fields such as <code>UCAL_YEAR</code>, <code>UCAL_MONTH</code>,
jpayne@69 28 * <code>UCAL_DAY</code>, <code>UCAL_HOUR</code>, and so on.
jpayne@69 29 * (A <code>UDate</code> object represents a specific instant in
jpayne@69 30 * time with millisecond precision. See UDate
jpayne@69 31 * for information about the <code>UDate</code> .)
jpayne@69 32 *
jpayne@69 33 * <p>
jpayne@69 34 * Types of <code>UCalendar</code> interpret a <code>UDate</code>
jpayne@69 35 * according to the rules of a specific calendar system. The U_STABLE
jpayne@69 36 * provides the enum UCalendarType with UCAL_TRADITIONAL and
jpayne@69 37 * UCAL_GREGORIAN.
jpayne@69 38 * <p>
jpayne@69 39 * Like other locale-sensitive C API, calendar API provides a
jpayne@69 40 * function, <code>ucal_open()</code>, which returns a pointer to
jpayne@69 41 * <code>UCalendar</code> whose time fields have been initialized
jpayne@69 42 * with the current date and time. We need to specify the type of
jpayne@69 43 * calendar to be opened and the timezoneId.
jpayne@69 44 * \htmlonly<blockquote>\endhtmlonly
jpayne@69 45 * <pre>
jpayne@69 46 * \code
jpayne@69 47 * UCalendar *caldef;
jpayne@69 48 * UChar *tzId;
jpayne@69 49 * UErrorCode status;
jpayne@69 50 * tzId=(UChar*)malloc(sizeof(UChar) * (strlen("PST") +1) );
jpayne@69 51 * u_uastrcpy(tzId, "PST");
jpayne@69 52 * caldef=ucal_open(tzID, u_strlen(tzID), NULL, UCAL_TRADITIONAL, &status);
jpayne@69 53 * \endcode
jpayne@69 54 * </pre>
jpayne@69 55 * \htmlonly</blockquote>\endhtmlonly
jpayne@69 56 *
jpayne@69 57 * <p>
jpayne@69 58 * A <code>UCalendar</code> object can produce all the time field values
jpayne@69 59 * needed to implement the date-time formatting for a particular language
jpayne@69 60 * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
jpayne@69 61 *
jpayne@69 62 * <p>
jpayne@69 63 * When computing a <code>UDate</code> from time fields, two special circumstances
jpayne@69 64 * may arise: there may be insufficient information to compute the
jpayne@69 65 * <code>UDate</code> (such as only year and month but no day in the month),
jpayne@69 66 * or there may be inconsistent information (such as "Tuesday, July 15, 1996"
jpayne@69 67 * -- July 15, 1996 is actually a Monday).
jpayne@69 68 *
jpayne@69 69 * <p>
jpayne@69 70 * <strong>Insufficient information.</strong> The calendar will use default
jpayne@69 71 * information to specify the missing fields. This may vary by calendar; for
jpayne@69 72 * the Gregorian calendar, the default for a field is the same as that of the
jpayne@69 73 * start of the epoch: i.e., UCAL_YEAR = 1970, UCAL_MONTH = JANUARY, UCAL_DATE = 1, etc.
jpayne@69 74 *
jpayne@69 75 * <p>
jpayne@69 76 * <strong>Inconsistent information.</strong> If fields conflict, the calendar
jpayne@69 77 * will give preference to fields set more recently. For example, when
jpayne@69 78 * determining the day, the calendar will look for one of the following
jpayne@69 79 * combinations of fields. The most recent combination, as determined by the
jpayne@69 80 * most recently set single field, will be used.
jpayne@69 81 *
jpayne@69 82 * \htmlonly<blockquote>\endhtmlonly
jpayne@69 83 * <pre>
jpayne@69 84 * \code
jpayne@69 85 * UCAL_MONTH + UCAL_DAY_OF_MONTH
jpayne@69 86 * UCAL_MONTH + UCAL_WEEK_OF_MONTH + UCAL_DAY_OF_WEEK
jpayne@69 87 * UCAL_MONTH + UCAL_DAY_OF_WEEK_IN_MONTH + UCAL_DAY_OF_WEEK
jpayne@69 88 * UCAL_DAY_OF_YEAR
jpayne@69 89 * UCAL_DAY_OF_WEEK + UCAL_WEEK_OF_YEAR
jpayne@69 90 * \endcode
jpayne@69 91 * </pre>
jpayne@69 92 * \htmlonly</blockquote>\endhtmlonly
jpayne@69 93 *
jpayne@69 94 * For the time of day:
jpayne@69 95 *
jpayne@69 96 * \htmlonly<blockquote>\endhtmlonly
jpayne@69 97 * <pre>
jpayne@69 98 * \code
jpayne@69 99 * UCAL_HOUR_OF_DAY
jpayne@69 100 * UCAL_AM_PM + UCAL_HOUR
jpayne@69 101 * \endcode
jpayne@69 102 * </pre>
jpayne@69 103 * \htmlonly</blockquote>\endhtmlonly
jpayne@69 104 *
jpayne@69 105 * <p>
jpayne@69 106 * <strong>Note:</strong> for some non-Gregorian calendars, different
jpayne@69 107 * fields may be necessary for complete disambiguation. For example, a full
jpayne@69 108 * specification of the historical Arabic astronomical calendar requires year,
jpayne@69 109 * month, day-of-month <em>and</em> day-of-week in some cases.
jpayne@69 110 *
jpayne@69 111 * <p>
jpayne@69 112 * <strong>Note:</strong> There are certain possible ambiguities in
jpayne@69 113 * interpretation of certain singular times, which are resolved in the
jpayne@69 114 * following ways:
jpayne@69 115 * <ol>
jpayne@69 116 * <li> 24:00:00 "belongs" to the following day. That is,
jpayne@69 117 * 23:59 on Dec 31, 1969 &lt; 24:00 on Jan 1, 1970 &lt; 24:01:00 on Jan 1, 1970
jpayne@69 118 *
jpayne@69 119 * <li> Although historically not precise, midnight also belongs to "am",
jpayne@69 120 * and noon belongs to "pm", so on the same day,
jpayne@69 121 * 12:00 am (midnight) &lt; 12:01 am, and 12:00 pm (noon) &lt; 12:01 pm
jpayne@69 122 * </ol>
jpayne@69 123 *
jpayne@69 124 * <p>
jpayne@69 125 * The date or time format strings are not part of the definition of a
jpayne@69 126 * calendar, as those must be modifiable or overridable by the user at
jpayne@69 127 * runtime. Use {@link icu::DateFormat}
jpayne@69 128 * to format dates.
jpayne@69 129 *
jpayne@69 130 * <p>
jpayne@69 131 * <code>Calendar</code> provides an API for field "rolling", where fields
jpayne@69 132 * can be incremented or decremented, but wrap around. For example, rolling the
jpayne@69 133 * month up in the date <code>December 12, <b>1996</b></code> results in
jpayne@69 134 * <code>January 12, <b>1996</b></code>.
jpayne@69 135 *
jpayne@69 136 * <p>
jpayne@69 137 * <code>Calendar</code> also provides a date arithmetic function for
jpayne@69 138 * adding the specified (signed) amount of time to a particular time field.
jpayne@69 139 * For example, subtracting 5 days from the date <code>September 12, 1996</code>
jpayne@69 140 * results in <code>September 7, 1996</code>.
jpayne@69 141 *
jpayne@69 142 * <p>
jpayne@69 143 * The Japanese calendar uses a combination of era name and year number.
jpayne@69 144 * When an emperor of Japan abdicates and a new emperor ascends the throne,
jpayne@69 145 * a new era is declared and year number is reset to 1. Even if the date of
jpayne@69 146 * abdication is scheduled ahead of time, the new era name might not be
jpayne@69 147 * announced until just before the date. In such case, ICU4C may include
jpayne@69 148 * a start date of future era without actual era name, but not enabled
jpayne@69 149 * by default. ICU4C users who want to test the behavior of the future era
jpayne@69 150 * can enable the tentative era by:
jpayne@69 151 * <ul>
jpayne@69 152 * <li>Environment variable <code>ICU_ENABLE_TENTATIVE_ERA=true</code>.</li>
jpayne@69 153 * </ul>
jpayne@69 154 *
jpayne@69 155 * @stable ICU 2.0
jpayne@69 156 */
jpayne@69 157
jpayne@69 158 /**
jpayne@69 159 * The time zone ID reserved for unknown time zone.
jpayne@69 160 * It behaves like the GMT/UTC time zone but has the special ID "Etc/Unknown".
jpayne@69 161 * @stable ICU 4.8
jpayne@69 162 */
jpayne@69 163 #define UCAL_UNKNOWN_ZONE_ID "Etc/Unknown"
jpayne@69 164
jpayne@69 165 /** A calendar.
jpayne@69 166 * For usage in C programs.
jpayne@69 167 * @stable ICU 2.0
jpayne@69 168 */
jpayne@69 169 typedef void* UCalendar;
jpayne@69 170
jpayne@69 171 /** Possible types of UCalendars
jpayne@69 172 * @stable ICU 2.0
jpayne@69 173 */
jpayne@69 174 enum UCalendarType {
jpayne@69 175 /**
jpayne@69 176 * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar,
jpayne@69 177 * which may be the Gregorian calendar or some other calendar.
jpayne@69 178 * @stable ICU 2.0
jpayne@69 179 */
jpayne@69 180 UCAL_TRADITIONAL,
jpayne@69 181 /**
jpayne@69 182 * A better name for UCAL_TRADITIONAL.
jpayne@69 183 * @stable ICU 4.2
jpayne@69 184 */
jpayne@69 185 UCAL_DEFAULT = UCAL_TRADITIONAL,
jpayne@69 186 /**
jpayne@69 187 * Unambiguously designates the Gregorian calendar for the locale.
jpayne@69 188 * @stable ICU 2.0
jpayne@69 189 */
jpayne@69 190 UCAL_GREGORIAN
jpayne@69 191 };
jpayne@69 192
jpayne@69 193 /** @stable ICU 2.0 */
jpayne@69 194 typedef enum UCalendarType UCalendarType;
jpayne@69 195
jpayne@69 196 /** Possible fields in a UCalendar
jpayne@69 197 * @stable ICU 2.0
jpayne@69 198 */
jpayne@69 199 enum UCalendarDateFields {
jpayne@69 200 /**
jpayne@69 201 * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar.
jpayne@69 202 * This is a calendar-specific value.
jpayne@69 203 * @stable ICU 2.6
jpayne@69 204 */
jpayne@69 205 UCAL_ERA,
jpayne@69 206
jpayne@69 207 /**
jpayne@69 208 * Field number indicating the year. This is a calendar-specific value.
jpayne@69 209 * @stable ICU 2.6
jpayne@69 210 */
jpayne@69 211 UCAL_YEAR,
jpayne@69 212
jpayne@69 213 /**
jpayne@69 214 * Field number indicating the month. This is a calendar-specific value.
jpayne@69 215 * The first month of the year is
jpayne@69 216 * <code>JANUARY</code>; the last depends on the number of months in a year.
jpayne@69 217 * @see #UCAL_JANUARY
jpayne@69 218 * @see #UCAL_FEBRUARY
jpayne@69 219 * @see #UCAL_MARCH
jpayne@69 220 * @see #UCAL_APRIL
jpayne@69 221 * @see #UCAL_MAY
jpayne@69 222 * @see #UCAL_JUNE
jpayne@69 223 * @see #UCAL_JULY
jpayne@69 224 * @see #UCAL_AUGUST
jpayne@69 225 * @see #UCAL_SEPTEMBER
jpayne@69 226 * @see #UCAL_OCTOBER
jpayne@69 227 * @see #UCAL_NOVEMBER
jpayne@69 228 * @see #UCAL_DECEMBER
jpayne@69 229 * @see #UCAL_UNDECIMBER
jpayne@69 230 * @stable ICU 2.6
jpayne@69 231 */
jpayne@69 232 UCAL_MONTH,
jpayne@69 233
jpayne@69 234 /**
jpayne@69 235 * Field number indicating the
jpayne@69 236 * week number within the current year. The first week of the year, as
jpayne@69 237 * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
jpayne@69 238 * attributes, has value 1. Subclasses define
jpayne@69 239 * the value of <code>UCAL_WEEK_OF_YEAR</code> for days before the first week of
jpayne@69 240 * the year.
jpayne@69 241 * @see ucal_getAttribute
jpayne@69 242 * @see ucal_setAttribute
jpayne@69 243 * @stable ICU 2.6
jpayne@69 244 */
jpayne@69 245 UCAL_WEEK_OF_YEAR,
jpayne@69 246
jpayne@69 247 /**
jpayne@69 248 * Field number indicating the
jpayne@69 249 * week number within the current month. The first week of the month, as
jpayne@69 250 * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
jpayne@69 251 * attributes, has value 1. Subclasses define
jpayne@69 252 * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
jpayne@69 253 * the month.
jpayne@69 254 * @see ucal_getAttribute
jpayne@69 255 * @see ucal_setAttribute
jpayne@69 256 * @see #UCAL_FIRST_DAY_OF_WEEK
jpayne@69 257 * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
jpayne@69 258 * @stable ICU 2.6
jpayne@69 259 */
jpayne@69 260 UCAL_WEEK_OF_MONTH,
jpayne@69 261
jpayne@69 262 /**
jpayne@69 263 * Field number indicating the
jpayne@69 264 * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
jpayne@69 265 * The first day of the month has value 1.
jpayne@69 266 * @see #UCAL_DAY_OF_MONTH
jpayne@69 267 * @stable ICU 2.6
jpayne@69 268 */
jpayne@69 269 UCAL_DATE,
jpayne@69 270
jpayne@69 271 /**
jpayne@69 272 * Field number indicating the day
jpayne@69 273 * number within the current year. The first day of the year has value 1.
jpayne@69 274 * @stable ICU 2.6
jpayne@69 275 */
jpayne@69 276 UCAL_DAY_OF_YEAR,
jpayne@69 277
jpayne@69 278 /**
jpayne@69 279 * Field number indicating the day
jpayne@69 280 * of the week. This field takes values <code>SUNDAY</code>,
jpayne@69 281 * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
jpayne@69 282 * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
jpayne@69 283 * @see #UCAL_SUNDAY
jpayne@69 284 * @see #UCAL_MONDAY
jpayne@69 285 * @see #UCAL_TUESDAY
jpayne@69 286 * @see #UCAL_WEDNESDAY
jpayne@69 287 * @see #UCAL_THURSDAY
jpayne@69 288 * @see #UCAL_FRIDAY
jpayne@69 289 * @see #UCAL_SATURDAY
jpayne@69 290 * @stable ICU 2.6
jpayne@69 291 */
jpayne@69 292 UCAL_DAY_OF_WEEK,
jpayne@69 293
jpayne@69 294 /**
jpayne@69 295 * Field number indicating the
jpayne@69 296 * ordinal number of the day of the week within the current month. Together
jpayne@69 297 * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
jpayne@69 298 * within a month. Unlike <code>WEEK_OF_MONTH</code> and
jpayne@69 299 * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
jpayne@69 300 * <code>getFirstDayOfWeek()</code> or
jpayne@69 301 * <code>getMinimalDaysInFirstWeek()</code>. <code>DAY_OF_MONTH 1</code>
jpayne@69 302 * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
jpayne@69 303 * 1</code>; <code>8</code> through <code>15</code> correspond to
jpayne@69 304 * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
jpayne@69 305 * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
jpayne@69 306 * <code>DAY_OF_WEEK_IN_MONTH 1</code>. Negative values count back from the
jpayne@69 307 * end of the month, so the last Sunday of a month is specified as
jpayne@69 308 * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>. Because
jpayne@69 309 * negative values count backward they will usually be aligned differently
jpayne@69 310 * within the month than positive values. For example, if a month has 31
jpayne@69 311 * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
jpayne@69 312 * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
jpayne@69 313 * @see #UCAL_DAY_OF_WEEK
jpayne@69 314 * @see #UCAL_WEEK_OF_MONTH
jpayne@69 315 * @stable ICU 2.6
jpayne@69 316 */
jpayne@69 317 UCAL_DAY_OF_WEEK_IN_MONTH,
jpayne@69 318
jpayne@69 319 /**
jpayne@69 320 * Field number indicating
jpayne@69 321 * whether the <code>HOUR</code> is before or after noon.
jpayne@69 322 * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
jpayne@69 323 * @see #UCAL_AM
jpayne@69 324 * @see #UCAL_PM
jpayne@69 325 * @see #UCAL_HOUR
jpayne@69 326 * @stable ICU 2.6
jpayne@69 327 */
jpayne@69 328 UCAL_AM_PM,
jpayne@69 329
jpayne@69 330 /**
jpayne@69 331 * Field number indicating the
jpayne@69 332 * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour
jpayne@69 333 * clock.
jpayne@69 334 * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
jpayne@69 335 * @see #UCAL_AM_PM
jpayne@69 336 * @see #UCAL_HOUR_OF_DAY
jpayne@69 337 * @stable ICU 2.6
jpayne@69 338 */
jpayne@69 339 UCAL_HOUR,
jpayne@69 340
jpayne@69 341 /**
jpayne@69 342 * Field number indicating the
jpayne@69 343 * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
jpayne@69 344 * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
jpayne@69 345 * @see #UCAL_HOUR
jpayne@69 346 * @stable ICU 2.6
jpayne@69 347 */
jpayne@69 348 UCAL_HOUR_OF_DAY,
jpayne@69 349
jpayne@69 350 /**
jpayne@69 351 * Field number indicating the
jpayne@69 352 * minute within the hour.
jpayne@69 353 * E.g., at 10:04:15.250 PM the <code>UCAL_MINUTE</code> is 4.
jpayne@69 354 * @stable ICU 2.6
jpayne@69 355 */
jpayne@69 356 UCAL_MINUTE,
jpayne@69 357
jpayne@69 358 /**
jpayne@69 359 * Field number indicating the
jpayne@69 360 * second within the minute.
jpayne@69 361 * E.g., at 10:04:15.250 PM the <code>UCAL_SECOND</code> is 15.
jpayne@69 362 * @stable ICU 2.6
jpayne@69 363 */
jpayne@69 364 UCAL_SECOND,
jpayne@69 365
jpayne@69 366 /**
jpayne@69 367 * Field number indicating the
jpayne@69 368 * millisecond within the second.
jpayne@69 369 * E.g., at 10:04:15.250 PM the <code>UCAL_MILLISECOND</code> is 250.
jpayne@69 370 * @stable ICU 2.6
jpayne@69 371 */
jpayne@69 372 UCAL_MILLISECOND,
jpayne@69 373
jpayne@69 374 /**
jpayne@69 375 * Field number indicating the
jpayne@69 376 * raw offset from GMT in milliseconds.
jpayne@69 377 * @stable ICU 2.6
jpayne@69 378 */
jpayne@69 379 UCAL_ZONE_OFFSET,
jpayne@69 380
jpayne@69 381 /**
jpayne@69 382 * Field number indicating the
jpayne@69 383 * daylight savings offset in milliseconds.
jpayne@69 384 * @stable ICU 2.6
jpayne@69 385 */
jpayne@69 386 UCAL_DST_OFFSET,
jpayne@69 387
jpayne@69 388 /**
jpayne@69 389 * Field number
jpayne@69 390 * indicating the extended year corresponding to the
jpayne@69 391 * <code>UCAL_WEEK_OF_YEAR</code> field. This may be one greater or less
jpayne@69 392 * than the value of <code>UCAL_EXTENDED_YEAR</code>.
jpayne@69 393 * @stable ICU 2.6
jpayne@69 394 */
jpayne@69 395 UCAL_YEAR_WOY,
jpayne@69 396
jpayne@69 397 /**
jpayne@69 398 * Field number
jpayne@69 399 * indicating the localized day of week. This will be a value from 1
jpayne@69 400 * to 7 inclusive, with 1 being the localized first day of the week.
jpayne@69 401 * @stable ICU 2.6
jpayne@69 402 */
jpayne@69 403 UCAL_DOW_LOCAL,
jpayne@69 404
jpayne@69 405 /**
jpayne@69 406 * Year of this calendar system, encompassing all supra-year fields. For example,
jpayne@69 407 * in Gregorian/Julian calendars, positive Extended Year values indicate years AD,
jpayne@69 408 * 1 BC = 0 extended, 2 BC = -1 extended, and so on.
jpayne@69 409 * @stable ICU 2.8
jpayne@69 410 */
jpayne@69 411 UCAL_EXTENDED_YEAR,
jpayne@69 412
jpayne@69 413 /**
jpayne@69 414 * Field number
jpayne@69 415 * indicating the modified Julian day number. This is different from
jpayne@69 416 * the conventional Julian day number in two regards. First, it
jpayne@69 417 * demarcates days at local zone midnight, rather than noon GMT.
jpayne@69 418 * Second, it is a local number; that is, it depends on the local time
jpayne@69 419 * zone. It can be thought of as a single number that encompasses all
jpayne@69 420 * the date-related fields.
jpayne@69 421 * @stable ICU 2.8
jpayne@69 422 */
jpayne@69 423 UCAL_JULIAN_DAY,
jpayne@69 424
jpayne@69 425 /**
jpayne@69 426 * Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves <em>exactly</em>
jpayne@69 427 * like a composite of all time-related fields, not including the zone fields. As such,
jpayne@69 428 * it also reflects discontinuities of those fields on DST transition days. On a day
jpayne@69 429 * of DST onset, it will jump forward. On a day of DST cessation, it will jump
jpayne@69 430 * backward. This reflects the fact that it must be combined with the DST_OFFSET field
jpayne@69 431 * to obtain a unique local time value.
jpayne@69 432 * @stable ICU 2.8
jpayne@69 433 */
jpayne@69 434 UCAL_MILLISECONDS_IN_DAY,
jpayne@69 435
jpayne@69 436 /**
jpayne@69 437 * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for
jpayne@69 438 * an example of this.
jpayne@69 439 */
jpayne@69 440 UCAL_IS_LEAP_MONTH,
jpayne@69 441
jpayne@69 442 /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API,
jpayne@69 443 * it is needed for layout of Calendar, DateFormat, and other objects */
jpayne@69 444 #ifndef U_FORCE_HIDE_DEPRECATED_API
jpayne@69 445 /**
jpayne@69 446 * One more than the highest normal UCalendarDateFields value.
jpayne@69 447 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
jpayne@69 448 */
jpayne@69 449 UCAL_FIELD_COUNT,
jpayne@69 450 #endif // U_FORCE_HIDE_DEPRECATED_API
jpayne@69 451
jpayne@69 452 /**
jpayne@69 453 * Field number indicating the
jpayne@69 454 * day of the month. This is a synonym for <code>UCAL_DATE</code>.
jpayne@69 455 * The first day of the month has value 1.
jpayne@69 456 * @see #UCAL_DATE
jpayne@69 457 * Synonym for UCAL_DATE
jpayne@69 458 * @stable ICU 2.8
jpayne@69 459 **/
jpayne@69 460 UCAL_DAY_OF_MONTH=UCAL_DATE
jpayne@69 461 };
jpayne@69 462
jpayne@69 463 /** @stable ICU 2.0 */
jpayne@69 464 typedef enum UCalendarDateFields UCalendarDateFields;
jpayne@69 465 /**
jpayne@69 466 * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
jpayne@69 467 * who create locale resources for the field of first-day-of-week should be aware of
jpayne@69 468 * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
jpayne@69 469 */
jpayne@69 470 /** Possible days of the week in a UCalendar
jpayne@69 471 * @stable ICU 2.0
jpayne@69 472 */
jpayne@69 473 enum UCalendarDaysOfWeek {
jpayne@69 474 /** Sunday */
jpayne@69 475 UCAL_SUNDAY = 1,
jpayne@69 476 /** Monday */
jpayne@69 477 UCAL_MONDAY,
jpayne@69 478 /** Tuesday */
jpayne@69 479 UCAL_TUESDAY,
jpayne@69 480 /** Wednesday */
jpayne@69 481 UCAL_WEDNESDAY,
jpayne@69 482 /** Thursday */
jpayne@69 483 UCAL_THURSDAY,
jpayne@69 484 /** Friday */
jpayne@69 485 UCAL_FRIDAY,
jpayne@69 486 /** Saturday */
jpayne@69 487 UCAL_SATURDAY
jpayne@69 488 };
jpayne@69 489
jpayne@69 490 /** @stable ICU 2.0 */
jpayne@69 491 typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
jpayne@69 492
jpayne@69 493 /** Possible months in a UCalendar. Note: Calendar month is 0-based.
jpayne@69 494 * @stable ICU 2.0
jpayne@69 495 */
jpayne@69 496 enum UCalendarMonths {
jpayne@69 497 /** January */
jpayne@69 498 UCAL_JANUARY,
jpayne@69 499 /** February */
jpayne@69 500 UCAL_FEBRUARY,
jpayne@69 501 /** March */
jpayne@69 502 UCAL_MARCH,
jpayne@69 503 /** April */
jpayne@69 504 UCAL_APRIL,
jpayne@69 505 /** May */
jpayne@69 506 UCAL_MAY,
jpayne@69 507 /** June */
jpayne@69 508 UCAL_JUNE,
jpayne@69 509 /** July */
jpayne@69 510 UCAL_JULY,
jpayne@69 511 /** August */
jpayne@69 512 UCAL_AUGUST,
jpayne@69 513 /** September */
jpayne@69 514 UCAL_SEPTEMBER,
jpayne@69 515 /** October */
jpayne@69 516 UCAL_OCTOBER,
jpayne@69 517 /** November */
jpayne@69 518 UCAL_NOVEMBER,
jpayne@69 519 /** December */
jpayne@69 520 UCAL_DECEMBER,
jpayne@69 521 /** Value of the <code>UCAL_MONTH</code> field indicating the
jpayne@69 522 * thirteenth month of the year. Although the Gregorian calendar
jpayne@69 523 * does not use this value, lunar calendars do.
jpayne@69 524 */
jpayne@69 525 UCAL_UNDECIMBER
jpayne@69 526 };
jpayne@69 527
jpayne@69 528 /** @stable ICU 2.0 */
jpayne@69 529 typedef enum UCalendarMonths UCalendarMonths;
jpayne@69 530
jpayne@69 531 /** Possible AM/PM values in a UCalendar
jpayne@69 532 * @stable ICU 2.0
jpayne@69 533 */
jpayne@69 534 enum UCalendarAMPMs {
jpayne@69 535 /** AM */
jpayne@69 536 UCAL_AM,
jpayne@69 537 /** PM */
jpayne@69 538 UCAL_PM
jpayne@69 539 };
jpayne@69 540
jpayne@69 541 /** @stable ICU 2.0 */
jpayne@69 542 typedef enum UCalendarAMPMs UCalendarAMPMs;
jpayne@69 543
jpayne@69 544 /**
jpayne@69 545 * System time zone type constants used by filtering zones
jpayne@69 546 * in ucal_openTimeZoneIDEnumeration.
jpayne@69 547 * @see ucal_openTimeZoneIDEnumeration
jpayne@69 548 * @stable ICU 4.8
jpayne@69 549 */
jpayne@69 550 enum USystemTimeZoneType {
jpayne@69 551 /**
jpayne@69 552 * Any system zones.
jpayne@69 553 * @stable ICU 4.8
jpayne@69 554 */
jpayne@69 555 UCAL_ZONE_TYPE_ANY,
jpayne@69 556 /**
jpayne@69 557 * Canonical system zones.
jpayne@69 558 * @stable ICU 4.8
jpayne@69 559 */
jpayne@69 560 UCAL_ZONE_TYPE_CANONICAL,
jpayne@69 561 /**
jpayne@69 562 * Canonical system zones associated with actual locations.
jpayne@69 563 * @stable ICU 4.8
jpayne@69 564 */
jpayne@69 565 UCAL_ZONE_TYPE_CANONICAL_LOCATION
jpayne@69 566 };
jpayne@69 567
jpayne@69 568 /** @stable ICU 4.8 */
jpayne@69 569 typedef enum USystemTimeZoneType USystemTimeZoneType;
jpayne@69 570
jpayne@69 571 /**
jpayne@69 572 * Create an enumeration over system time zone IDs with the given
jpayne@69 573 * filter conditions.
jpayne@69 574 * @param zoneType The system time zone type.
jpayne@69 575 * @param region The ISO 3166 two-letter country code or UN M.49
jpayne@69 576 * three-digit area code. When NULL, no filtering
jpayne@69 577 * done by region.
jpayne@69 578 * @param rawOffset An offset from GMT in milliseconds, ignoring the
jpayne@69 579 * effect of daylight savings time, if any. When NULL,
jpayne@69 580 * no filtering done by zone offset.
jpayne@69 581 * @param ec A pointer to an UErrorCode to receive any errors
jpayne@69 582 * @return an enumeration object that the caller must dispose of
jpayne@69 583 * using enum_close(), or NULL upon failure. In case of failure,
jpayne@69 584 * *ec will indicate the error.
jpayne@69 585 * @stable ICU 4.8
jpayne@69 586 */
jpayne@69 587 U_STABLE UEnumeration* U_EXPORT2
jpayne@69 588 ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region,
jpayne@69 589 const int32_t* rawOffset, UErrorCode* ec);
jpayne@69 590
jpayne@69 591 /**
jpayne@69 592 * Create an enumeration over all time zones.
jpayne@69 593 *
jpayne@69 594 * @param ec input/output error code
jpayne@69 595 *
jpayne@69 596 * @return an enumeration object that the caller must dispose of using
jpayne@69 597 * uenum_close(), or NULL upon failure. In case of failure *ec will
jpayne@69 598 * indicate the error.
jpayne@69 599 *
jpayne@69 600 * @stable ICU 2.6
jpayne@69 601 */
jpayne@69 602 U_STABLE UEnumeration* U_EXPORT2
jpayne@69 603 ucal_openTimeZones(UErrorCode* ec);
jpayne@69 604
jpayne@69 605 /**
jpayne@69 606 * Create an enumeration over all time zones associated with the given
jpayne@69 607 * country. Some zones are affiliated with no country (e.g., "UTC");
jpayne@69 608 * these may also be retrieved, as a group.
jpayne@69 609 *
jpayne@69 610 * @param country the ISO 3166 two-letter country code, or NULL to
jpayne@69 611 * retrieve zones not affiliated with any country
jpayne@69 612 *
jpayne@69 613 * @param ec input/output error code
jpayne@69 614 *
jpayne@69 615 * @return an enumeration object that the caller must dispose of using
jpayne@69 616 * uenum_close(), or NULL upon failure. In case of failure *ec will
jpayne@69 617 * indicate the error.
jpayne@69 618 *
jpayne@69 619 * @stable ICU 2.6
jpayne@69 620 */
jpayne@69 621 U_STABLE UEnumeration* U_EXPORT2
jpayne@69 622 ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
jpayne@69 623
jpayne@69 624 /**
jpayne@69 625 * Return the default time zone. The default is determined initially
jpayne@69 626 * by querying the host operating system. If the host system detection
jpayne@69 627 * routines fail, or if they specify a TimeZone or TimeZone offset
jpayne@69 628 * which is not recognized, then the special TimeZone "Etc/Unknown"
jpayne@69 629 * is returned.
jpayne@69 630 *
jpayne@69 631 * The default may be changed with `ucal_setDefaultTimeZone()` or with
jpayne@69 632 * the C++ TimeZone API, `TimeZone::adoptDefault(TimeZone*)`.
jpayne@69 633 *
jpayne@69 634 * @param result A buffer to receive the result, or NULL
jpayne@69 635 *
jpayne@69 636 * @param resultCapacity The capacity of the result buffer
jpayne@69 637 *
jpayne@69 638 * @param ec input/output error code
jpayne@69 639 *
jpayne@69 640 * @return The result string length, not including the terminating
jpayne@69 641 * null
jpayne@69 642 *
jpayne@69 643 * @see #UCAL_UNKNOWN_ZONE_ID
jpayne@69 644 *
jpayne@69 645 * @stable ICU 2.6
jpayne@69 646 */
jpayne@69 647 U_STABLE int32_t U_EXPORT2
jpayne@69 648 ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
jpayne@69 649
jpayne@69 650 /**
jpayne@69 651 * Set the default time zone.
jpayne@69 652 *
jpayne@69 653 * @param zoneID null-terminated time zone ID
jpayne@69 654 *
jpayne@69 655 * @param ec input/output error code
jpayne@69 656 *
jpayne@69 657 * @stable ICU 2.6
jpayne@69 658 */
jpayne@69 659 U_STABLE void U_EXPORT2
jpayne@69 660 ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
jpayne@69 661
jpayne@69 662 #ifndef U_HIDE_DRAFT_API
jpayne@69 663
jpayne@69 664 /**
jpayne@69 665 * Return the current host time zone. The host time zone is detected from
jpayne@69 666 * the current host system configuration by querying the host operating
jpayne@69 667 * system. If the host system detection routines fail, or if they specify
jpayne@69 668 * a TimeZone or TimeZone offset which is not recognized, then the special
jpayne@69 669 * TimeZone "Etc/Unknown" is returned.
jpayne@69 670 *
jpayne@69 671 * Note that host time zone and the ICU default time zone can be different.
jpayne@69 672 *
jpayne@69 673 * The ICU default time zone does not change once initialized unless modified
jpayne@69 674 * by calling `ucal_setDefaultTimeZone()` or with the C++ TimeZone API,
jpayne@69 675 * `TimeZone::adoptDefault(TimeZone*)`.
jpayne@69 676 *
jpayne@69 677 * If the host operating system configuration has changed since ICU has
jpayne@69 678 * initialized then the returned value can be different than the ICU default
jpayne@69 679 * time zone, even if the default has not changed.
jpayne@69 680 *
jpayne@69 681 * <p>This function is not thread safe.</p>
jpayne@69 682 *
jpayne@69 683 * @param result A buffer to receive the result, or NULL
jpayne@69 684 * @param resultCapacity The capacity of the result buffer
jpayne@69 685 * @param ec input/output error code
jpayne@69 686 * @return The result string length, not including the terminating
jpayne@69 687 * null
jpayne@69 688 *
jpayne@69 689 * @see #UCAL_UNKNOWN_ZONE_ID
jpayne@69 690 *
jpayne@69 691 * @draft ICU 65
jpayne@69 692 */
jpayne@69 693 U_DRAFT int32_t U_EXPORT2
jpayne@69 694 ucal_getHostTimeZone(UChar *result, int32_t resultCapacity, UErrorCode *ec);
jpayne@69 695
jpayne@69 696 #endif // U_HIDE_DRAFT_API
jpayne@69 697
jpayne@69 698 /**
jpayne@69 699 * Return the amount of time in milliseconds that the clock is
jpayne@69 700 * advanced during daylight savings time for the given time zone, or
jpayne@69 701 * zero if the time zone does not observe daylight savings time.
jpayne@69 702 *
jpayne@69 703 * @param zoneID null-terminated time zone ID
jpayne@69 704 *
jpayne@69 705 * @param ec input/output error code
jpayne@69 706 *
jpayne@69 707 * @return the number of milliseconds the time is advanced with
jpayne@69 708 * respect to standard time when the daylight savings rules are in
jpayne@69 709 * effect. This is always a non-negative number, most commonly either
jpayne@69 710 * 3,600,000 (one hour) or zero.
jpayne@69 711 *
jpayne@69 712 * @stable ICU 2.6
jpayne@69 713 */
jpayne@69 714 U_STABLE int32_t U_EXPORT2
jpayne@69 715 ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
jpayne@69 716
jpayne@69 717 /**
jpayne@69 718 * Get the current date and time.
jpayne@69 719 * The value returned is represented as milliseconds from the epoch.
jpayne@69 720 * @return The current date and time.
jpayne@69 721 * @stable ICU 2.0
jpayne@69 722 */
jpayne@69 723 U_STABLE UDate U_EXPORT2
jpayne@69 724 ucal_getNow(void);
jpayne@69 725
jpayne@69 726 /**
jpayne@69 727 * Open a UCalendar.
jpayne@69 728 * A UCalendar may be used to convert a millisecond value to a year,
jpayne@69 729 * month, and day.
jpayne@69 730 * <p>
jpayne@69 731 * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown",
jpayne@69 732 * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID
jpayne@69 733 * <code>UCAL_UNKNOWN_ZONE_ID</code> ("Etc/Unknown") without any errors/warnings. If you want
jpayne@69 734 * to check if a TimeZone ID is valid prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>.
jpayne@69 735 *
jpayne@69 736 * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
jpayne@69 737 * @param len The length of zoneID, or -1 if null-terminated.
jpayne@69 738 * @param locale The desired locale
jpayne@69 739 * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
jpayne@69 740 * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
jpayne@69 741 * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
jpayne@69 742 * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
jpayne@69 743 * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
jpayne@69 744 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 745 * @return A pointer to a UCalendar, or 0 if an error occurred.
jpayne@69 746 * @see #UCAL_UNKNOWN_ZONE_ID
jpayne@69 747 * @stable ICU 2.0
jpayne@69 748 */
jpayne@69 749 U_STABLE UCalendar* U_EXPORT2
jpayne@69 750 ucal_open(const UChar* zoneID,
jpayne@69 751 int32_t len,
jpayne@69 752 const char* locale,
jpayne@69 753 UCalendarType type,
jpayne@69 754 UErrorCode* status);
jpayne@69 755
jpayne@69 756 /**
jpayne@69 757 * Close a UCalendar.
jpayne@69 758 * Once closed, a UCalendar may no longer be used.
jpayne@69 759 * @param cal The UCalendar to close.
jpayne@69 760 * @stable ICU 2.0
jpayne@69 761 */
jpayne@69 762 U_STABLE void U_EXPORT2
jpayne@69 763 ucal_close(UCalendar *cal);
jpayne@69 764
jpayne@69 765 #if U_SHOW_CPLUSPLUS_API
jpayne@69 766
jpayne@69 767 U_NAMESPACE_BEGIN
jpayne@69 768
jpayne@69 769 /**
jpayne@69 770 * \class LocalUCalendarPointer
jpayne@69 771 * "Smart pointer" class, closes a UCalendar via ucal_close().
jpayne@69 772 * For most methods see the LocalPointerBase base class.
jpayne@69 773 *
jpayne@69 774 * @see LocalPointerBase
jpayne@69 775 * @see LocalPointer
jpayne@69 776 * @stable ICU 4.4
jpayne@69 777 */
jpayne@69 778 U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
jpayne@69 779
jpayne@69 780 U_NAMESPACE_END
jpayne@69 781
jpayne@69 782 #endif
jpayne@69 783
jpayne@69 784 /**
jpayne@69 785 * Open a copy of a UCalendar.
jpayne@69 786 * This function performs a deep copy.
jpayne@69 787 * @param cal The calendar to copy
jpayne@69 788 * @param status A pointer to an UErrorCode to receive any errors.
jpayne@69 789 * @return A pointer to a UCalendar identical to cal.
jpayne@69 790 * @stable ICU 4.0
jpayne@69 791 */
jpayne@69 792 U_STABLE UCalendar* U_EXPORT2
jpayne@69 793 ucal_clone(const UCalendar* cal,
jpayne@69 794 UErrorCode* status);
jpayne@69 795
jpayne@69 796 /**
jpayne@69 797 * Set the TimeZone used by a UCalendar.
jpayne@69 798 * A UCalendar uses a timezone for converting from Greenwich time to local time.
jpayne@69 799 * @param cal The UCalendar to set.
jpayne@69 800 * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
jpayne@69 801 * @param len The length of zoneID, or -1 if null-terminated.
jpayne@69 802 * @param status A pointer to an UErrorCode to receive any errors.
jpayne@69 803 * @stable ICU 2.0
jpayne@69 804 */
jpayne@69 805 U_STABLE void U_EXPORT2
jpayne@69 806 ucal_setTimeZone(UCalendar* cal,
jpayne@69 807 const UChar* zoneID,
jpayne@69 808 int32_t len,
jpayne@69 809 UErrorCode* status);
jpayne@69 810
jpayne@69 811 /**
jpayne@69 812 * Get the ID of the UCalendar's time zone.
jpayne@69 813 *
jpayne@69 814 * @param cal The UCalendar to query.
jpayne@69 815 * @param result Receives the UCalendar's time zone ID.
jpayne@69 816 * @param resultLength The maximum size of result.
jpayne@69 817 * @param status Receives the status.
jpayne@69 818 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
jpayne@69 819 * @stable ICU 51
jpayne@69 820 */
jpayne@69 821 U_STABLE int32_t U_EXPORT2
jpayne@69 822 ucal_getTimeZoneID(const UCalendar *cal,
jpayne@69 823 UChar *result,
jpayne@69 824 int32_t resultLength,
jpayne@69 825 UErrorCode *status);
jpayne@69 826
jpayne@69 827 /**
jpayne@69 828 * Possible formats for a UCalendar's display name
jpayne@69 829 * @stable ICU 2.0
jpayne@69 830 */
jpayne@69 831 enum UCalendarDisplayNameType {
jpayne@69 832 /** Standard display name */
jpayne@69 833 UCAL_STANDARD,
jpayne@69 834 /** Short standard display name */
jpayne@69 835 UCAL_SHORT_STANDARD,
jpayne@69 836 /** Daylight savings display name */
jpayne@69 837 UCAL_DST,
jpayne@69 838 /** Short daylight savings display name */
jpayne@69 839 UCAL_SHORT_DST
jpayne@69 840 };
jpayne@69 841
jpayne@69 842 /** @stable ICU 2.0 */
jpayne@69 843 typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
jpayne@69 844
jpayne@69 845 /**
jpayne@69 846 * Get the display name for a UCalendar's TimeZone.
jpayne@69 847 * A display name is suitable for presentation to a user.
jpayne@69 848 * @param cal The UCalendar to query.
jpayne@69 849 * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
jpayne@69 850 * UCAL_DST, UCAL_SHORT_DST
jpayne@69 851 * @param locale The desired locale for the display name.
jpayne@69 852 * @param result A pointer to a buffer to receive the formatted number.
jpayne@69 853 * @param resultLength The maximum size of result.
jpayne@69 854 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 855 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
jpayne@69 856 * @stable ICU 2.0
jpayne@69 857 */
jpayne@69 858 U_STABLE int32_t U_EXPORT2
jpayne@69 859 ucal_getTimeZoneDisplayName(const UCalendar* cal,
jpayne@69 860 UCalendarDisplayNameType type,
jpayne@69 861 const char* locale,
jpayne@69 862 UChar* result,
jpayne@69 863 int32_t resultLength,
jpayne@69 864 UErrorCode* status);
jpayne@69 865
jpayne@69 866 /**
jpayne@69 867 * Determine if a UCalendar is currently in daylight savings time.
jpayne@69 868 * Daylight savings time is not used in all parts of the world.
jpayne@69 869 * @param cal The UCalendar to query.
jpayne@69 870 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 871 * @return TRUE if cal is currently in daylight savings time, FALSE otherwise
jpayne@69 872 * @stable ICU 2.0
jpayne@69 873 */
jpayne@69 874 U_STABLE UBool U_EXPORT2
jpayne@69 875 ucal_inDaylightTime(const UCalendar* cal,
jpayne@69 876 UErrorCode* status );
jpayne@69 877
jpayne@69 878 /**
jpayne@69 879 * Sets the GregorianCalendar change date. This is the point when the switch from
jpayne@69 880 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
jpayne@69 881 * 15, 1582. Previous to this time and date will be Julian dates.
jpayne@69 882 *
jpayne@69 883 * This function works only for Gregorian calendars. If the UCalendar is not
jpayne@69 884 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
jpayne@69 885 * error code is set.
jpayne@69 886 *
jpayne@69 887 * @param cal The calendar object.
jpayne@69 888 * @param date The given Gregorian cutover date.
jpayne@69 889 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
jpayne@69 890 * pass the U_SUCCESS() test, or else the function returns
jpayne@69 891 * immediately. Check for U_FAILURE() on output or use with
jpayne@69 892 * function chaining. (See User Guide for details.)
jpayne@69 893 *
jpayne@69 894 * @see GregorianCalendar::setGregorianChange
jpayne@69 895 * @see ucal_getGregorianChange
jpayne@69 896 * @stable ICU 3.6
jpayne@69 897 */
jpayne@69 898 U_STABLE void U_EXPORT2
jpayne@69 899 ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
jpayne@69 900
jpayne@69 901 /**
jpayne@69 902 * Gets the Gregorian Calendar change date. This is the point when the switch from
jpayne@69 903 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
jpayne@69 904 * 15, 1582. Previous to this time and date will be Julian dates.
jpayne@69 905 *
jpayne@69 906 * This function works only for Gregorian calendars. If the UCalendar is not
jpayne@69 907 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
jpayne@69 908 * error code is set.
jpayne@69 909 *
jpayne@69 910 * @param cal The calendar object.
jpayne@69 911 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
jpayne@69 912 * pass the U_SUCCESS() test, or else the function returns
jpayne@69 913 * immediately. Check for U_FAILURE() on output or use with
jpayne@69 914 * function chaining. (See User Guide for details.)
jpayne@69 915 * @return The Gregorian cutover time for this calendar.
jpayne@69 916 *
jpayne@69 917 * @see GregorianCalendar::getGregorianChange
jpayne@69 918 * @see ucal_setGregorianChange
jpayne@69 919 * @stable ICU 3.6
jpayne@69 920 */
jpayne@69 921 U_STABLE UDate U_EXPORT2
jpayne@69 922 ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
jpayne@69 923
jpayne@69 924 /**
jpayne@69 925 * Types of UCalendar attributes
jpayne@69 926 * @stable ICU 2.0
jpayne@69 927 */
jpayne@69 928 enum UCalendarAttribute {
jpayne@69 929 /**
jpayne@69 930 * Lenient parsing
jpayne@69 931 * @stable ICU 2.0
jpayne@69 932 */
jpayne@69 933 UCAL_LENIENT,
jpayne@69 934 /**
jpayne@69 935 * First day of week
jpayne@69 936 * @stable ICU 2.0
jpayne@69 937 */
jpayne@69 938 UCAL_FIRST_DAY_OF_WEEK,
jpayne@69 939 /**
jpayne@69 940 * Minimum number of days in first week
jpayne@69 941 * @stable ICU 2.0
jpayne@69 942 */
jpayne@69 943 UCAL_MINIMAL_DAYS_IN_FIRST_WEEK,
jpayne@69 944 /**
jpayne@69 945 * The behavior for handling wall time repeating multiple times
jpayne@69 946 * at negative time zone offset transitions
jpayne@69 947 * @stable ICU 49
jpayne@69 948 */
jpayne@69 949 UCAL_REPEATED_WALL_TIME,
jpayne@69 950 /**
jpayne@69 951 * The behavior for handling skipped wall time at positive time
jpayne@69 952 * zone offset transitions.
jpayne@69 953 * @stable ICU 49
jpayne@69 954 */
jpayne@69 955 UCAL_SKIPPED_WALL_TIME
jpayne@69 956 };
jpayne@69 957
jpayne@69 958 /** @stable ICU 2.0 */
jpayne@69 959 typedef enum UCalendarAttribute UCalendarAttribute;
jpayne@69 960
jpayne@69 961 /**
jpayne@69 962 * Options for handling ambiguous wall time at time zone
jpayne@69 963 * offset transitions.
jpayne@69 964 * @stable ICU 49
jpayne@69 965 */
jpayne@69 966 enum UCalendarWallTimeOption {
jpayne@69 967 /**
jpayne@69 968 * An ambiguous wall time to be interpreted as the latest.
jpayne@69 969 * This option is valid for UCAL_REPEATED_WALL_TIME and
jpayne@69 970 * UCAL_SKIPPED_WALL_TIME.
jpayne@69 971 * @stable ICU 49
jpayne@69 972 */
jpayne@69 973 UCAL_WALLTIME_LAST,
jpayne@69 974 /**
jpayne@69 975 * An ambiguous wall time to be interpreted as the earliest.
jpayne@69 976 * This option is valid for UCAL_REPEATED_WALL_TIME and
jpayne@69 977 * UCAL_SKIPPED_WALL_TIME.
jpayne@69 978 * @stable ICU 49
jpayne@69 979 */
jpayne@69 980 UCAL_WALLTIME_FIRST,
jpayne@69 981 /**
jpayne@69 982 * An ambiguous wall time to be interpreted as the next valid
jpayne@69 983 * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME.
jpayne@69 984 * @stable ICU 49
jpayne@69 985 */
jpayne@69 986 UCAL_WALLTIME_NEXT_VALID
jpayne@69 987 };
jpayne@69 988 /** @stable ICU 49 */
jpayne@69 989 typedef enum UCalendarWallTimeOption UCalendarWallTimeOption;
jpayne@69 990
jpayne@69 991 /**
jpayne@69 992 * Get a numeric attribute associated with a UCalendar.
jpayne@69 993 * Numeric attributes include the first day of the week, or the minimal numbers
jpayne@69 994 * of days in the first week of the month.
jpayne@69 995 * @param cal The UCalendar to query.
jpayne@69 996 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
jpayne@69 997 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
jpayne@69 998 * @return The value of attr.
jpayne@69 999 * @see ucal_setAttribute
jpayne@69 1000 * @stable ICU 2.0
jpayne@69 1001 */
jpayne@69 1002 U_STABLE int32_t U_EXPORT2
jpayne@69 1003 ucal_getAttribute(const UCalendar* cal,
jpayne@69 1004 UCalendarAttribute attr);
jpayne@69 1005
jpayne@69 1006 /**
jpayne@69 1007 * Set a numeric attribute associated with a UCalendar.
jpayne@69 1008 * Numeric attributes include the first day of the week, or the minimal numbers
jpayne@69 1009 * of days in the first week of the month.
jpayne@69 1010 * @param cal The UCalendar to set.
jpayne@69 1011 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
jpayne@69 1012 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
jpayne@69 1013 * @param newValue The new value of attr.
jpayne@69 1014 * @see ucal_getAttribute
jpayne@69 1015 * @stable ICU 2.0
jpayne@69 1016 */
jpayne@69 1017 U_STABLE void U_EXPORT2
jpayne@69 1018 ucal_setAttribute(UCalendar* cal,
jpayne@69 1019 UCalendarAttribute attr,
jpayne@69 1020 int32_t newValue);
jpayne@69 1021
jpayne@69 1022 /**
jpayne@69 1023 * Get a locale for which calendars are available.
jpayne@69 1024 * A UCalendar in a locale returned by this function will contain the correct
jpayne@69 1025 * day and month names for the locale.
jpayne@69 1026 * @param localeIndex The index of the desired locale.
jpayne@69 1027 * @return A locale for which calendars are available, or 0 if none.
jpayne@69 1028 * @see ucal_countAvailable
jpayne@69 1029 * @stable ICU 2.0
jpayne@69 1030 */
jpayne@69 1031 U_STABLE const char* U_EXPORT2
jpayne@69 1032 ucal_getAvailable(int32_t localeIndex);
jpayne@69 1033
jpayne@69 1034 /**
jpayne@69 1035 * Determine how many locales have calendars available.
jpayne@69 1036 * This function is most useful as determining the loop ending condition for
jpayne@69 1037 * calls to \ref ucal_getAvailable.
jpayne@69 1038 * @return The number of locales for which calendars are available.
jpayne@69 1039 * @see ucal_getAvailable
jpayne@69 1040 * @stable ICU 2.0
jpayne@69 1041 */
jpayne@69 1042 U_STABLE int32_t U_EXPORT2
jpayne@69 1043 ucal_countAvailable(void);
jpayne@69 1044
jpayne@69 1045 /**
jpayne@69 1046 * Get a UCalendar's current time in millis.
jpayne@69 1047 * The time is represented as milliseconds from the epoch.
jpayne@69 1048 * @param cal The UCalendar to query.
jpayne@69 1049 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 1050 * @return The calendar's current time in millis.
jpayne@69 1051 * @see ucal_setMillis
jpayne@69 1052 * @see ucal_setDate
jpayne@69 1053 * @see ucal_setDateTime
jpayne@69 1054 * @stable ICU 2.0
jpayne@69 1055 */
jpayne@69 1056 U_STABLE UDate U_EXPORT2
jpayne@69 1057 ucal_getMillis(const UCalendar* cal,
jpayne@69 1058 UErrorCode* status);
jpayne@69 1059
jpayne@69 1060 /**
jpayne@69 1061 * Set a UCalendar's current time in millis.
jpayne@69 1062 * The time is represented as milliseconds from the epoch.
jpayne@69 1063 * @param cal The UCalendar to set.
jpayne@69 1064 * @param dateTime The desired date and time.
jpayne@69 1065 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 1066 * @see ucal_getMillis
jpayne@69 1067 * @see ucal_setDate
jpayne@69 1068 * @see ucal_setDateTime
jpayne@69 1069 * @stable ICU 2.0
jpayne@69 1070 */
jpayne@69 1071 U_STABLE void U_EXPORT2
jpayne@69 1072 ucal_setMillis(UCalendar* cal,
jpayne@69 1073 UDate dateTime,
jpayne@69 1074 UErrorCode* status );
jpayne@69 1075
jpayne@69 1076 /**
jpayne@69 1077 * Set a UCalendar's current date.
jpayne@69 1078 * The date is represented as a series of 32-bit integers.
jpayne@69 1079 * @param cal The UCalendar to set.
jpayne@69 1080 * @param year The desired year.
jpayne@69 1081 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
jpayne@69 1082 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
jpayne@69 1083 * @param date The desired day of the month.
jpayne@69 1084 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 1085 * @see ucal_getMillis
jpayne@69 1086 * @see ucal_setMillis
jpayne@69 1087 * @see ucal_setDateTime
jpayne@69 1088 * @stable ICU 2.0
jpayne@69 1089 */
jpayne@69 1090 U_STABLE void U_EXPORT2
jpayne@69 1091 ucal_setDate(UCalendar* cal,
jpayne@69 1092 int32_t year,
jpayne@69 1093 int32_t month,
jpayne@69 1094 int32_t date,
jpayne@69 1095 UErrorCode* status);
jpayne@69 1096
jpayne@69 1097 /**
jpayne@69 1098 * Set a UCalendar's current date.
jpayne@69 1099 * The date is represented as a series of 32-bit integers.
jpayne@69 1100 * @param cal The UCalendar to set.
jpayne@69 1101 * @param year The desired year.
jpayne@69 1102 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
jpayne@69 1103 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
jpayne@69 1104 * @param date The desired day of the month.
jpayne@69 1105 * @param hour The desired hour of day.
jpayne@69 1106 * @param minute The desired minute.
jpayne@69 1107 * @param second The desirec second.
jpayne@69 1108 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 1109 * @see ucal_getMillis
jpayne@69 1110 * @see ucal_setMillis
jpayne@69 1111 * @see ucal_setDate
jpayne@69 1112 * @stable ICU 2.0
jpayne@69 1113 */
jpayne@69 1114 U_STABLE void U_EXPORT2
jpayne@69 1115 ucal_setDateTime(UCalendar* cal,
jpayne@69 1116 int32_t year,
jpayne@69 1117 int32_t month,
jpayne@69 1118 int32_t date,
jpayne@69 1119 int32_t hour,
jpayne@69 1120 int32_t minute,
jpayne@69 1121 int32_t second,
jpayne@69 1122 UErrorCode* status);
jpayne@69 1123
jpayne@69 1124 /**
jpayne@69 1125 * Returns TRUE if two UCalendars are equivalent. Equivalent
jpayne@69 1126 * UCalendars will behave identically, but they may be set to
jpayne@69 1127 * different times.
jpayne@69 1128 * @param cal1 The first of the UCalendars to compare.
jpayne@69 1129 * @param cal2 The second of the UCalendars to compare.
jpayne@69 1130 * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise.
jpayne@69 1131 * @stable ICU 2.0
jpayne@69 1132 */
jpayne@69 1133 U_STABLE UBool U_EXPORT2
jpayne@69 1134 ucal_equivalentTo(const UCalendar* cal1,
jpayne@69 1135 const UCalendar* cal2);
jpayne@69 1136
jpayne@69 1137 /**
jpayne@69 1138 * Add a specified signed amount to a particular field in a UCalendar.
jpayne@69 1139 * This can modify more significant fields in the calendar.
jpayne@69 1140 * Adding a positive value always means moving forward in time, so for the Gregorian calendar,
jpayne@69 1141 * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
jpayne@69 1142 * the numeric value of the field itself).
jpayne@69 1143 * @param cal The UCalendar to which to add.
jpayne@69 1144 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
jpayne@69 1145 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
jpayne@69 1146 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
jpayne@69 1147 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
jpayne@69 1148 * @param amount The signed amount to add to field. If the amount causes the value
jpayne@69 1149 * to exceed to maximum or minimum values for that field, other fields are modified
jpayne@69 1150 * to preserve the magnitude of the change.
jpayne@69 1151 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 1152 * @see ucal_roll
jpayne@69 1153 * @stable ICU 2.0
jpayne@69 1154 */
jpayne@69 1155 U_STABLE void U_EXPORT2
jpayne@69 1156 ucal_add(UCalendar* cal,
jpayne@69 1157 UCalendarDateFields field,
jpayne@69 1158 int32_t amount,
jpayne@69 1159 UErrorCode* status);
jpayne@69 1160
jpayne@69 1161 /**
jpayne@69 1162 * Add a specified signed amount to a particular field in a UCalendar.
jpayne@69 1163 * This will not modify more significant fields in the calendar.
jpayne@69 1164 * Rolling by a positive value always means moving forward in time (unless the limit of the
jpayne@69 1165 * field is reached, in which case it may pin or wrap), so for Gregorian calendar,
jpayne@69 1166 * starting with 100 BC and rolling the year by +1 results in 99 BC.
jpayne@69 1167 * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the
jpayne@69 1168 * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around.
jpayne@69 1169 * When eras only have a limit at one end, then attempting to roll the year past that limit will result in
jpayne@69 1170 * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time
jpayne@69 1171 * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for
jpayne@69 1172 * era 0 (that is the only way to represent years before the calendar epoch).
jpayne@69 1173 * @param cal The UCalendar to which to add.
jpayne@69 1174 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
jpayne@69 1175 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
jpayne@69 1176 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
jpayne@69 1177 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
jpayne@69 1178 * @param amount The signed amount to add to field. If the amount causes the value
jpayne@69 1179 * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
jpayne@69 1180 * value.
jpayne@69 1181 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 1182 * @see ucal_add
jpayne@69 1183 * @stable ICU 2.0
jpayne@69 1184 */
jpayne@69 1185 U_STABLE void U_EXPORT2
jpayne@69 1186 ucal_roll(UCalendar* cal,
jpayne@69 1187 UCalendarDateFields field,
jpayne@69 1188 int32_t amount,
jpayne@69 1189 UErrorCode* status);
jpayne@69 1190
jpayne@69 1191 /**
jpayne@69 1192 * Get the current value of a field from a UCalendar.
jpayne@69 1193 * All fields are represented as 32-bit integers.
jpayne@69 1194 * @param cal The UCalendar to query.
jpayne@69 1195 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
jpayne@69 1196 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
jpayne@69 1197 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
jpayne@69 1198 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
jpayne@69 1199 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 1200 * @return The value of the desired field.
jpayne@69 1201 * @see ucal_set
jpayne@69 1202 * @see ucal_isSet
jpayne@69 1203 * @see ucal_clearField
jpayne@69 1204 * @see ucal_clear
jpayne@69 1205 * @stable ICU 2.0
jpayne@69 1206 */
jpayne@69 1207 U_STABLE int32_t U_EXPORT2
jpayne@69 1208 ucal_get(const UCalendar* cal,
jpayne@69 1209 UCalendarDateFields field,
jpayne@69 1210 UErrorCode* status );
jpayne@69 1211
jpayne@69 1212 /**
jpayne@69 1213 * Set the value of a field in a UCalendar.
jpayne@69 1214 * All fields are represented as 32-bit integers.
jpayne@69 1215 * @param cal The UCalendar to set.
jpayne@69 1216 * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
jpayne@69 1217 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
jpayne@69 1218 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
jpayne@69 1219 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
jpayne@69 1220 * @param value The desired value of field.
jpayne@69 1221 * @see ucal_get
jpayne@69 1222 * @see ucal_isSet
jpayne@69 1223 * @see ucal_clearField
jpayne@69 1224 * @see ucal_clear
jpayne@69 1225 * @stable ICU 2.0
jpayne@69 1226 */
jpayne@69 1227 U_STABLE void U_EXPORT2
jpayne@69 1228 ucal_set(UCalendar* cal,
jpayne@69 1229 UCalendarDateFields field,
jpayne@69 1230 int32_t value);
jpayne@69 1231
jpayne@69 1232 /**
jpayne@69 1233 * Determine if a field in a UCalendar is set.
jpayne@69 1234 * All fields are represented as 32-bit integers.
jpayne@69 1235 * @param cal The UCalendar to query.
jpayne@69 1236 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
jpayne@69 1237 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
jpayne@69 1238 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
jpayne@69 1239 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
jpayne@69 1240 * @return TRUE if field is set, FALSE otherwise.
jpayne@69 1241 * @see ucal_get
jpayne@69 1242 * @see ucal_set
jpayne@69 1243 * @see ucal_clearField
jpayne@69 1244 * @see ucal_clear
jpayne@69 1245 * @stable ICU 2.0
jpayne@69 1246 */
jpayne@69 1247 U_STABLE UBool U_EXPORT2
jpayne@69 1248 ucal_isSet(const UCalendar* cal,
jpayne@69 1249 UCalendarDateFields field);
jpayne@69 1250
jpayne@69 1251 /**
jpayne@69 1252 * Clear a field in a UCalendar.
jpayne@69 1253 * All fields are represented as 32-bit integers.
jpayne@69 1254 * @param cal The UCalendar containing the field to clear.
jpayne@69 1255 * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
jpayne@69 1256 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
jpayne@69 1257 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
jpayne@69 1258 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
jpayne@69 1259 * @see ucal_get
jpayne@69 1260 * @see ucal_set
jpayne@69 1261 * @see ucal_isSet
jpayne@69 1262 * @see ucal_clear
jpayne@69 1263 * @stable ICU 2.0
jpayne@69 1264 */
jpayne@69 1265 U_STABLE void U_EXPORT2
jpayne@69 1266 ucal_clearField(UCalendar* cal,
jpayne@69 1267 UCalendarDateFields field);
jpayne@69 1268
jpayne@69 1269 /**
jpayne@69 1270 * Clear all fields in a UCalendar.
jpayne@69 1271 * All fields are represented as 32-bit integers.
jpayne@69 1272 * @param calendar The UCalendar to clear.
jpayne@69 1273 * @see ucal_get
jpayne@69 1274 * @see ucal_set
jpayne@69 1275 * @see ucal_isSet
jpayne@69 1276 * @see ucal_clearField
jpayne@69 1277 * @stable ICU 2.0
jpayne@69 1278 */
jpayne@69 1279 U_STABLE void U_EXPORT2
jpayne@69 1280 ucal_clear(UCalendar* calendar);
jpayne@69 1281
jpayne@69 1282 /**
jpayne@69 1283 * Possible limit values for a UCalendar
jpayne@69 1284 * @stable ICU 2.0
jpayne@69 1285 */
jpayne@69 1286 enum UCalendarLimitType {
jpayne@69 1287 /** Minimum value */
jpayne@69 1288 UCAL_MINIMUM,
jpayne@69 1289 /** Maximum value */
jpayne@69 1290 UCAL_MAXIMUM,
jpayne@69 1291 /** Greatest minimum value */
jpayne@69 1292 UCAL_GREATEST_MINIMUM,
jpayne@69 1293 /** Leaest maximum value */
jpayne@69 1294 UCAL_LEAST_MAXIMUM,
jpayne@69 1295 /** Actual minimum value */
jpayne@69 1296 UCAL_ACTUAL_MINIMUM,
jpayne@69 1297 /** Actual maximum value */
jpayne@69 1298 UCAL_ACTUAL_MAXIMUM
jpayne@69 1299 };
jpayne@69 1300
jpayne@69 1301 /** @stable ICU 2.0 */
jpayne@69 1302 typedef enum UCalendarLimitType UCalendarLimitType;
jpayne@69 1303
jpayne@69 1304 /**
jpayne@69 1305 * Determine a limit for a field in a UCalendar.
jpayne@69 1306 * A limit is a maximum or minimum value for a field.
jpayne@69 1307 * @param cal The UCalendar to query.
jpayne@69 1308 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
jpayne@69 1309 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
jpayne@69 1310 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
jpayne@69 1311 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
jpayne@69 1312 * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM,
jpayne@69 1313 * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
jpayne@69 1314 * @param status A pointer to an UErrorCode to receive any errors.
jpayne@69 1315 * @return The requested value.
jpayne@69 1316 * @stable ICU 2.0
jpayne@69 1317 */
jpayne@69 1318 U_STABLE int32_t U_EXPORT2
jpayne@69 1319 ucal_getLimit(const UCalendar* cal,
jpayne@69 1320 UCalendarDateFields field,
jpayne@69 1321 UCalendarLimitType type,
jpayne@69 1322 UErrorCode* status);
jpayne@69 1323
jpayne@69 1324 /** Get the locale for this calendar object. You can choose between valid and actual locale.
jpayne@69 1325 * @param cal The calendar object
jpayne@69 1326 * @param type type of the locale we're looking for (valid or actual)
jpayne@69 1327 * @param status error code for the operation
jpayne@69 1328 * @return the locale name
jpayne@69 1329 * @stable ICU 2.8
jpayne@69 1330 */
jpayne@69 1331 U_STABLE const char * U_EXPORT2
jpayne@69 1332 ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
jpayne@69 1333
jpayne@69 1334 /**
jpayne@69 1335 * Returns the timezone data version currently used by ICU.
jpayne@69 1336 * @param status error code for the operation
jpayne@69 1337 * @return the version string, such as "2007f"
jpayne@69 1338 * @stable ICU 3.8
jpayne@69 1339 */
jpayne@69 1340 U_STABLE const char * U_EXPORT2
jpayne@69 1341 ucal_getTZDataVersion(UErrorCode* status);
jpayne@69 1342
jpayne@69 1343 /**
jpayne@69 1344 * Returns the canonical system timezone ID or the normalized
jpayne@69 1345 * custom time zone ID for the given time zone ID.
jpayne@69 1346 * @param id The input timezone ID to be canonicalized.
jpayne@69 1347 * @param len The length of id, or -1 if null-terminated.
jpayne@69 1348 * @param result The buffer receives the canonical system timezone ID
jpayne@69 1349 * or the custom timezone ID in normalized format.
jpayne@69 1350 * @param resultCapacity The capacity of the result buffer.
jpayne@69 1351 * @param isSystemID Receives if the given ID is a known system
jpayne@69 1352 * timezone ID.
jpayne@69 1353 * @param status Receives the status. When the given timezone ID
jpayne@69 1354 * is neither a known system time zone ID nor a
jpayne@69 1355 * valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
jpayne@69 1356 * is set.
jpayne@69 1357 * @return The result string length, not including the terminating
jpayne@69 1358 * null.
jpayne@69 1359 * @stable ICU 4.0
jpayne@69 1360 */
jpayne@69 1361 U_STABLE int32_t U_EXPORT2
jpayne@69 1362 ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
jpayne@69 1363 UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
jpayne@69 1364 /**
jpayne@69 1365 * Get the resource keyword value string designating the calendar type for the UCalendar.
jpayne@69 1366 * @param cal The UCalendar to query.
jpayne@69 1367 * @param status The error code for the operation.
jpayne@69 1368 * @return The resource keyword value string.
jpayne@69 1369 * @stable ICU 4.2
jpayne@69 1370 */
jpayne@69 1371 U_STABLE const char * U_EXPORT2
jpayne@69 1372 ucal_getType(const UCalendar *cal, UErrorCode* status);
jpayne@69 1373
jpayne@69 1374 /**
jpayne@69 1375 * Given a key and a locale, returns an array of string values in a preferred
jpayne@69 1376 * order that would make a difference. These are all and only those values where
jpayne@69 1377 * the open (creation) of the service with the locale formed from the input locale
jpayne@69 1378 * plus input keyword and that value has different behavior than creation with the
jpayne@69 1379 * input locale alone.
jpayne@69 1380 * @param key one of the keys supported by this service. For now, only
jpayne@69 1381 * "calendar" is supported.
jpayne@69 1382 * @param locale the locale
jpayne@69 1383 * @param commonlyUsed if set to true it will return only commonly used values
jpayne@69 1384 * with the given locale in preferred order. Otherwise,
jpayne@69 1385 * it will return all the available values for the locale.
jpayne@69 1386 * @param status error status
jpayne@69 1387 * @return a string enumeration over keyword values for the given key and the locale.
jpayne@69 1388 * @stable ICU 4.2
jpayne@69 1389 */
jpayne@69 1390 U_STABLE UEnumeration* U_EXPORT2
jpayne@69 1391 ucal_getKeywordValuesForLocale(const char* key,
jpayne@69 1392 const char* locale,
jpayne@69 1393 UBool commonlyUsed,
jpayne@69 1394 UErrorCode* status);
jpayne@69 1395
jpayne@69 1396
jpayne@69 1397 /** Weekday types, as returned by ucal_getDayOfWeekType().
jpayne@69 1398 * @stable ICU 4.4
jpayne@69 1399 */
jpayne@69 1400 enum UCalendarWeekdayType {
jpayne@69 1401 /**
jpayne@69 1402 * Designates a full weekday (no part of the day is included in the weekend).
jpayne@69 1403 * @stable ICU 4.4
jpayne@69 1404 */
jpayne@69 1405 UCAL_WEEKDAY,
jpayne@69 1406 /**
jpayne@69 1407 * Designates a full weekend day (the entire day is included in the weekend).
jpayne@69 1408 * @stable ICU 4.4
jpayne@69 1409 */
jpayne@69 1410 UCAL_WEEKEND,
jpayne@69 1411 /**
jpayne@69 1412 * Designates a day that starts as a weekday and transitions to the weekend.
jpayne@69 1413 * Call ucal_getWeekendTransition() to get the time of transition.
jpayne@69 1414 * @stable ICU 4.4
jpayne@69 1415 */
jpayne@69 1416 UCAL_WEEKEND_ONSET,
jpayne@69 1417 /**
jpayne@69 1418 * Designates a day that starts as the weekend and transitions to a weekday.
jpayne@69 1419 * Call ucal_getWeekendTransition() to get the time of transition.
jpayne@69 1420 * @stable ICU 4.4
jpayne@69 1421 */
jpayne@69 1422 UCAL_WEEKEND_CEASE
jpayne@69 1423 };
jpayne@69 1424
jpayne@69 1425 /** @stable ICU 4.4 */
jpayne@69 1426 typedef enum UCalendarWeekdayType UCalendarWeekdayType;
jpayne@69 1427
jpayne@69 1428 /**
jpayne@69 1429 * Returns whether the given day of the week is a weekday, a weekend day,
jpayne@69 1430 * or a day that transitions from one to the other, for the locale and
jpayne@69 1431 * calendar system associated with this UCalendar (the locale's region is
jpayne@69 1432 * often the most determinant factor). If a transition occurs at midnight,
jpayne@69 1433 * then the days before and after the transition will have the
jpayne@69 1434 * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time
jpayne@69 1435 * other than midnight, then the day of the transition will have
jpayne@69 1436 * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the
jpayne@69 1437 * function ucal_getWeekendTransition() will return the point of
jpayne@69 1438 * transition.
jpayne@69 1439 * @param cal The UCalendar to query.
jpayne@69 1440 * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY).
jpayne@69 1441 * @param status The error code for the operation.
jpayne@69 1442 * @return The UCalendarWeekdayType for the day of the week.
jpayne@69 1443 * @stable ICU 4.4
jpayne@69 1444 */
jpayne@69 1445 U_STABLE UCalendarWeekdayType U_EXPORT2
jpayne@69 1446 ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status);
jpayne@69 1447
jpayne@69 1448 /**
jpayne@69 1449 * Returns the time during the day at which the weekend begins or ends in
jpayne@69 1450 * this calendar system. If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET
jpayne@69 1451 * for the specified dayOfWeek, return the time at which the weekend begins.
jpayne@69 1452 * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
jpayne@69 1453 * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns
jpayne@69 1454 * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
jpayne@69 1455 * (U_ILLEGAL_ARGUMENT_ERROR).
jpayne@69 1456 * @param cal The UCalendar to query.
jpayne@69 1457 * @param dayOfWeek The day of the week for which the weekend transition time is
jpayne@69 1458 * desired (UCAL_SUNDAY..UCAL_SATURDAY).
jpayne@69 1459 * @param status The error code for the operation.
jpayne@69 1460 * @return The milliseconds after midnight at which the weekend begins or ends.
jpayne@69 1461 * @stable ICU 4.4
jpayne@69 1462 */
jpayne@69 1463 U_STABLE int32_t U_EXPORT2
jpayne@69 1464 ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
jpayne@69 1465
jpayne@69 1466 /**
jpayne@69 1467 * Returns TRUE if the given UDate is in the weekend in
jpayne@69 1468 * this calendar system.
jpayne@69 1469 * @param cal The UCalendar to query.
jpayne@69 1470 * @param date The UDate in question.
jpayne@69 1471 * @param status The error code for the operation.
jpayne@69 1472 * @return TRUE if the given UDate is in the weekend in
jpayne@69 1473 * this calendar system, FALSE otherwise.
jpayne@69 1474 * @stable ICU 4.4
jpayne@69 1475 */
jpayne@69 1476 U_STABLE UBool U_EXPORT2
jpayne@69 1477 ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status);
jpayne@69 1478
jpayne@69 1479 /**
jpayne@69 1480 * Return the difference between the target time and the time this calendar object is currently set to.
jpayne@69 1481 * If the target time is after the current calendar setting, the the returned value will be positive.
jpayne@69 1482 * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH
jpayne@69 1483 * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the
jpayne@69 1484 * current calendar setting.
jpayne@69 1485 *
jpayne@69 1486 * As a side effect of this call, this calendar is advanced toward target by the given amount. That is,
jpayne@69 1487 * calling this function has the side effect of calling ucal_add on this calendar with the specified
jpayne@69 1488 * field and an amount equal to the return value from this function.
jpayne@69 1489 *
jpayne@69 1490 * A typical way of using this function is to call it first with the largest field of interest, then
jpayne@69 1491 * with progressively smaller fields.
jpayne@69 1492 *
jpayne@69 1493 * @param cal The UCalendar to compare and update.
jpayne@69 1494 * @param target The target date to compare to the current calendar setting.
jpayne@69 1495 * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
jpayne@69 1496 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
jpayne@69 1497 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
jpayne@69 1498 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
jpayne@69 1499 * @param status A pointer to an UErrorCode to receive any errors
jpayne@69 1500 * @return The date difference for the specified field.
jpayne@69 1501 * @stable ICU 4.8
jpayne@69 1502 */
jpayne@69 1503 U_STABLE int32_t U_EXPORT2
jpayne@69 1504 ucal_getFieldDifference(UCalendar* cal,
jpayne@69 1505 UDate target,
jpayne@69 1506 UCalendarDateFields field,
jpayne@69 1507 UErrorCode* status);
jpayne@69 1508
jpayne@69 1509 /**
jpayne@69 1510 * Time zone transition types for ucal_getTimeZoneTransitionDate
jpayne@69 1511 * @stable ICU 50
jpayne@69 1512 */
jpayne@69 1513 enum UTimeZoneTransitionType {
jpayne@69 1514 /**
jpayne@69 1515 * Get the next transition after the current date,
jpayne@69 1516 * i.e. excludes the current date
jpayne@69 1517 * @stable ICU 50
jpayne@69 1518 */
jpayne@69 1519 UCAL_TZ_TRANSITION_NEXT,
jpayne@69 1520 /**
jpayne@69 1521 * Get the next transition on or after the current date,
jpayne@69 1522 * i.e. may include the current date
jpayne@69 1523 * @stable ICU 50
jpayne@69 1524 */
jpayne@69 1525 UCAL_TZ_TRANSITION_NEXT_INCLUSIVE,
jpayne@69 1526 /**
jpayne@69 1527 * Get the previous transition before the current date,
jpayne@69 1528 * i.e. excludes the current date
jpayne@69 1529 * @stable ICU 50
jpayne@69 1530 */
jpayne@69 1531 UCAL_TZ_TRANSITION_PREVIOUS,
jpayne@69 1532 /**
jpayne@69 1533 * Get the previous transition on or before the current date,
jpayne@69 1534 * i.e. may include the current date
jpayne@69 1535 * @stable ICU 50
jpayne@69 1536 */
jpayne@69 1537 UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE
jpayne@69 1538 };
jpayne@69 1539
jpayne@69 1540 typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */
jpayne@69 1541
jpayne@69 1542 /**
jpayne@69 1543 * Get the UDate for the next/previous time zone transition relative to
jpayne@69 1544 * the calendar's current date, in the time zone to which the calendar
jpayne@69 1545 * is currently set. If there is no known time zone transition of the
jpayne@69 1546 * requested type relative to the calendar's date, the function returns
jpayne@69 1547 * FALSE.
jpayne@69 1548 * @param cal The UCalendar to query.
jpayne@69 1549 * @param type The type of transition desired.
jpayne@69 1550 * @param transition A pointer to a UDate to be set to the transition time.
jpayne@69 1551 * If the function returns FALSE, the value set is unspecified.
jpayne@69 1552 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 1553 * @return TRUE if a valid transition time is set in *transition, FALSE
jpayne@69 1554 * otherwise.
jpayne@69 1555 * @stable ICU 50
jpayne@69 1556 */
jpayne@69 1557 U_STABLE UBool U_EXPORT2
jpayne@69 1558 ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type,
jpayne@69 1559 UDate* transition, UErrorCode* status);
jpayne@69 1560
jpayne@69 1561 /**
jpayne@69 1562 * Converts a system time zone ID to an equivalent Windows time zone ID. For example,
jpayne@69 1563 * Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles".
jpayne@69 1564 *
jpayne@69 1565 * <p>There are system time zones that cannot be mapped to Windows zones. When the input
jpayne@69 1566 * system time zone ID is unknown or unmappable to a Windows time zone, then this
jpayne@69 1567 * function returns 0 as the result length, but the operation itself remains successful
jpayne@69 1568 * (no error status set on return).
jpayne@69 1569 *
jpayne@69 1570 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
jpayne@69 1571 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
jpayne@69 1572 * please read the ICU user guide section <a href="http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data">
jpayne@69 1573 * Updating the Time Zone Data</a>.
jpayne@69 1574 *
jpayne@69 1575 * @param id A system time zone ID.
jpayne@69 1576 * @param len The length of <code>id</code>, or -1 if null-terminated.
jpayne@69 1577 * @param winid A buffer to receive a Windows time zone ID.
jpayne@69 1578 * @param winidCapacity The capacity of the result buffer <code>winid</code>.
jpayne@69 1579 * @param status Receives the status.
jpayne@69 1580 * @return The result string length, not including the terminating null.
jpayne@69 1581 * @see ucal_getTimeZoneIDForWindowsID
jpayne@69 1582 *
jpayne@69 1583 * @stable ICU 52
jpayne@69 1584 */
jpayne@69 1585 U_STABLE int32_t U_EXPORT2
jpayne@69 1586 ucal_getWindowsTimeZoneID(const UChar* id, int32_t len,
jpayne@69 1587 UChar* winid, int32_t winidCapacity, UErrorCode* status);
jpayne@69 1588
jpayne@69 1589 /**
jpayne@69 1590 * Converts a Windows time zone ID to an equivalent system time zone ID
jpayne@69 1591 * for a region. For example, system time zone ID "America/Los_Angeles" is returned
jpayne@69 1592 * for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>),
jpayne@69 1593 * "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and
jpayne@69 1594 * region "CA".
jpayne@69 1595 *
jpayne@69 1596 * <p>Not all Windows time zones can be mapped to system time zones. When the input
jpayne@69 1597 * Windows time zone ID is unknown or unmappable to a system time zone, then this
jpayne@69 1598 * function returns 0 as the result length, but the operation itself remains successful
jpayne@69 1599 * (no error status set on return).
jpayne@69 1600 *
jpayne@69 1601 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
jpayne@69 1602 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
jpayne@69 1603 * please read the ICU user guide section <a href="http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data">
jpayne@69 1604 * Updating the Time Zone Data</a>.
jpayne@69 1605 *
jpayne@69 1606 * @param winid A Windows time zone ID.
jpayne@69 1607 * @param len The length of <code>winid</code>, or -1 if null-terminated.
jpayne@69 1608 * @param region A null-terminated region code, or <code>NULL</code> if no regional preference.
jpayne@69 1609 * @param id A buffer to receive a system time zone ID.
jpayne@69 1610 * @param idCapacity The capacity of the result buffer <code>id</code>.
jpayne@69 1611 * @param status Receives the status.
jpayne@69 1612 * @return The result string length, not including the terminating null.
jpayne@69 1613 * @see ucal_getWindowsTimeZoneID
jpayne@69 1614 *
jpayne@69 1615 * @stable ICU 52
jpayne@69 1616 */
jpayne@69 1617 U_STABLE int32_t U_EXPORT2
jpayne@69 1618 ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region,
jpayne@69 1619 UChar* id, int32_t idCapacity, UErrorCode* status);
jpayne@69 1620
jpayne@69 1621 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 1622
jpayne@69 1623 #endif