CFDateFormatter.h

   1 /*
   2  * Copyright (c) 2009 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*      CFDateFormatter.h
  25         Copyright (c) 2003-2009, Apple Inc. All rights reserved.
  26 */
  27
  28 #if !defined(__COREFOUNDATION_CFDATEFORMATTER__)
  29 #define __COREFOUNDATION_CFDATEFORMATTER__ 1
  30
  31 #include <CoreFoundation/CFBase.h>
  32 #include <CoreFoundation/CFDate.h>
  33 #include <CoreFoundation/CFLocale.h>
  34
  35 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
  36
  37 CF_EXTERN_C_BEGIN
  38
  39 typedef struct __CFDateFormatter *CFDateFormatterRef;
  40
  41 // CFDateFormatters are not thread-safe.  Do not use one from multiple threads!
  42
  43 CF_EXPORT
  44 CFStringRef CFDateFormatterCreateDateFormatFromTemplate(CFAllocatorRef allocator, CFStringRef tmplate, CFOptionFlags options, CFLocaleRef locale) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
  45         // no options defined, pass 0 for now
  46
  47 CF_EXPORT
  48 CFTypeID CFDateFormatterGetTypeID(void) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  49
  50 enum {  // date and time format styles
  51         kCFDateFormatterNoStyle = 0,
  52         kCFDateFormatterShortStyle = 1,
  53         kCFDateFormatterMediumStyle = 2,
  54         kCFDateFormatterLongStyle = 3,
  55         kCFDateFormatterFullStyle = 4
  56 };
  57 typedef CFIndex CFDateFormatterStyle;
  58
  59 // The exact formatted result for these date and time styles depends on the
  60 // locale, but generally:
  61 //     Short is completely numeric, such as "12/13/52" or "3:30pm"
  62 //     Medium is longer, such as "Jan 12, 1952"
  63 //     Long is longer, such as "January 12, 1952" or "3:30:32pm"
  64 //     Full is pretty complete; e.g. "Tuesday, April 12, 1952 AD" or "3:30:42pm PST"
  65 // The specifications though are left fuzzy, in part simply because a user's
  66 // preference choices may affect the output, and also the results may change
  67 // from one OS release to another.  To produce an exactly formatted date you
  68 // should not rely on styles and localization, but set the format string and
  69 // use nothing but numbers.
  70
  71 CF_EXPORT
  72 CFDateFormatterRef CFDateFormatterCreate(CFAllocatorRef allocator, CFLocaleRef locale, CFDateFormatterStyle dateStyle, CFDateFormatterStyle timeStyle) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  73         // Returns a CFDateFormatter, localized to the given locale, which
  74         // will format dates to the given date and time styles.
  75
  76 CF_EXPORT
  77 CFLocaleRef CFDateFormatterGetLocale(CFDateFormatterRef formatter) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  78
  79 CF_EXPORT
  80 CFDateFormatterStyle CFDateFormatterGetDateStyle(CFDateFormatterRef formatter) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  81
  82 CF_EXPORT
  83 CFDateFormatterStyle CFDateFormatterGetTimeStyle(CFDateFormatterRef formatter) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  84         // Get the properties with which the date formatter was created.
  85
  86 CF_EXPORT
  87 CFStringRef CFDateFormatterGetFormat(CFDateFormatterRef formatter) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  88
  89 CF_EXPORT
  90 void CFDateFormatterSetFormat(CFDateFormatterRef formatter, CFStringRef formatString) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  91         // Set the format description string of the date formatter.  This
  92         // overrides the style settings.  The format of the format string
  93         // is as defined by the ICU library.  The date formatter starts with a
  94         // default format string defined by the style arguments with
  95         // which it was created.
  96
  97
  98 CF_EXPORT
  99 CFStringRef CFDateFormatterCreateStringWithDate(CFAllocatorRef allocator, CFDateFormatterRef formatter, CFDateRef date) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 100
 101 CF_EXPORT
 102 CFStringRef CFDateFormatterCreateStringWithAbsoluteTime(CFAllocatorRef allocator, CFDateFormatterRef formatter, CFAbsoluteTime at) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 103         // Create a string representation of the given date or CFAbsoluteTime
 104         // using the current state of the date formatter.
 105
 106
 107 CF_EXPORT
 108 CFDateRef CFDateFormatterCreateDateFromString(CFAllocatorRef allocator, CFDateFormatterRef formatter, CFStringRef string, CFRange *rangep) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 109
 110 CF_EXPORT
 111 Boolean CFDateFormatterGetAbsoluteTimeFromString(CFDateFormatterRef formatter, CFStringRef string, CFRange *rangep, CFAbsoluteTime *atp) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 112         // Parse a string representation of a date using the current state
 113         // of the date formatter.  The range parameter specifies the range
 114         // of the string in which the parsing should occur in input, and on
 115         // output indicates the extent that was used; this parameter can
 116         // be NULL, in which case the whole string may be used.  The
 117         // return value indicates whether some date was computed and
 118         // (if atp is not NULL) stored at the location specified by atp.
 119
 120
 121 CF_EXPORT
 122 void CFDateFormatterSetProperty(CFDateFormatterRef formatter, CFStringRef key, CFTypeRef value) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 123
 124 CF_EXPORT
 125 CFTypeRef CFDateFormatterCopyProperty(CFDateFormatterRef formatter, CFStringRef key) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 126         // Set and get various properties of the date formatter, the set of
 127         // which may be expanded in the future.
 128
 129 CF_EXPORT const CFStringRef kCFDateFormatterIsLenient AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;        // CFBoolean
 130 CF_EXPORT const CFStringRef kCFDateFormatterTimeZone AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;         // CFTimeZone
 131 CF_EXPORT const CFStringRef kCFDateFormatterCalendarName AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;     // CFString
 132 CF_EXPORT const CFStringRef kCFDateFormatterDefaultFormat AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;    // CFString
 133 CF_EXPORT const CFStringRef kCFDateFormatterTwoDigitStartDate AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; // CFDate
 134 CF_EXPORT const CFStringRef kCFDateFormatterDefaultDate AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;      // CFDate
 135 CF_EXPORT const CFStringRef kCFDateFormatterCalendar AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;         // CFCalendar
 136 CF_EXPORT const CFStringRef kCFDateFormatterEraSymbols AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;       // CFArray of CFString
 137 CF_EXPORT const CFStringRef kCFDateFormatterMonthSymbols AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;     // CFArray of CFString
 138 CF_EXPORT const CFStringRef kCFDateFormatterShortMonthSymbols AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; // CFArray of CFString
 139 CF_EXPORT const CFStringRef kCFDateFormatterWeekdaySymbols AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;   // CFArray of CFString
 140 CF_EXPORT const CFStringRef kCFDateFormatterShortWeekdaySymbols AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; // CFArray of CFString
 141 CF_EXPORT const CFStringRef kCFDateFormatterAMSymbol AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;         // CFString
 142 CF_EXPORT const CFStringRef kCFDateFormatterPMSymbol AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;         // CFString
 143 CF_EXPORT const CFStringRef kCFDateFormatterLongEraSymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;   // CFArray of CFString
 144 CF_EXPORT const CFStringRef kCFDateFormatterVeryShortMonthSymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 145 CF_EXPORT const CFStringRef kCFDateFormatterStandaloneMonthSymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 146 CF_EXPORT const CFStringRef kCFDateFormatterShortStandaloneMonthSymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 147 CF_EXPORT const CFStringRef kCFDateFormatterVeryShortStandaloneMonthSymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 148 CF_EXPORT const CFStringRef kCFDateFormatterVeryShortWeekdaySymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 149 CF_EXPORT const CFStringRef kCFDateFormatterStandaloneWeekdaySymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 150 CF_EXPORT const CFStringRef kCFDateFormatterShortStandaloneWeekdaySymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 151 CF_EXPORT const CFStringRef kCFDateFormatterVeryShortStandaloneWeekdaySymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 152 CF_EXPORT const CFStringRef kCFDateFormatterQuarterSymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;   // CFArray of CFString
 153 CF_EXPORT const CFStringRef kCFDateFormatterShortQuarterSymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 154 CF_EXPORT const CFStringRef kCFDateFormatterStandaloneQuarterSymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 155 CF_EXPORT const CFStringRef kCFDateFormatterShortStandaloneQuarterSymbols AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFArray of CFString
 156 CF_EXPORT const CFStringRef kCFDateFormatterGregorianStartDate AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; // CFDate
 157 CF_EXPORT const CFStringRef kCFDateFormatterDoesRelativeDateFormattingKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER; // CFBoolean
 158
 159 // See CFLocale.h for these calendar constants:
 160 //      const CFStringRef kCFGregorianCalendar;
 161 //      const CFStringRef kCFBuddhistCalendar;
 162 //      const CFStringRef kCFJapaneseCalendar;
 163 //      const CFStringRef kCFIslamicCalendar;
 164 //      const CFStringRef kCFIslamicCivilCalendar;
 165 //      const CFStringRef kCFHebrewCalendar;
 166 //      const CFStringRef kCFChineseCalendar;
 167 //      const CFStringRef kCFRepublicOfChinaCalendar;
 168 //      const CFStringRef kCFPersianCalendar;
 169 //      const CFStringRef kCFIndianCalendar;
 170 //      const CFStringRef kCFISO8601Calendar;   not yet implemented
 171
 172 CF_EXTERN_C_END
 173
 174 #endif
 175
 176 #endif /* ! __COREFOUNDATION_CFDATEFORMATTER__ */
 177