CFDateFormatter.h
1 /* CFDateFormatter.h 2 Copyright (c) 2003-2019, Apple Inc. and the Swift project authors 3 4 Portions Copyright (c) 2014-2019, Apple Inc. and the Swift project authors 5 Licensed under Apache License v2.0 with Runtime Library Exception 6 See http://swift.org/LICENSE.txt for license information 7 See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors 8 */ 9 10 #if !defined(__COREFOUNDATION_CFDATEFORMATTER__) 11 #define __COREFOUNDATION_CFDATEFORMATTER__ 1 12 13 #include <CoreFoundation/CFBase.h> 14 #include <CoreFoundation/CFDate.h> 15 #include <CoreFoundation/CFLocale.h> 16 17 CF_IMPLICIT_BRIDGING_ENABLED 18 CF_EXTERN_C_BEGIN 19 20 typedef CFStringRef CFDateFormatterKey CF_STRING_ENUM; 21 22 typedef struct CF_BRIDGED_MUTABLE_TYPE(id) __CFDateFormatter *CFDateFormatterRef; 23 24 // CFDateFormatters are not thread-safe. Do not use one from multiple threads! 25 26 CF_EXPORT 27 CFStringRef CFDateFormatterCreateDateFormatFromTemplate(CFAllocatorRef allocator, CFStringRef tmplate, CFOptionFlags options, CFLocaleRef locale) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)); 28 // no options defined, pass 0 for now 29 30 CF_EXPORT 31 CFTypeID CFDateFormatterGetTypeID(void); 32 33 // The exact formatted result for these date and time styles depends on the 34 // locale, but generally: 35 // Short is completely numeric, such as "12/13/52" or "3:30pm" 36 // Medium is longer, such as "Jan 12, 1952" 37 // Long is longer, such as "January 12, 1952" or "3:30:32pm" 38 // Full is pretty complete; e.g. "Tuesday, April 12, 1952 AD" or "3:30:42pm PST" 39 // The specifications though are left fuzzy, in part simply because a user's 40 // preference choices may affect the output, and also the results may change 41 // from one OS release to another. To produce an exactly formatted date you 42 // should not rely on styles and localization, but set the format string and 43 // use nothing but numbers. 44 45 typedef CF_ENUM(CFIndex, CFDateFormatterStyle) { // date and time format styles 46 kCFDateFormatterNoStyle = 0, 47 kCFDateFormatterShortStyle = 1, 48 kCFDateFormatterMediumStyle = 2, 49 kCFDateFormatterLongStyle = 3, 50 kCFDateFormatterFullStyle = 4 51 }; 52 53 typedef CF_OPTIONS(CFOptionFlags, CFISO8601DateFormatOptions) { 54 /* The format for year is inferred based on whether or not the week of year option is specified. 55 - if week of year is present, "YYYY" is used to display week dates. 56 - if week of year is not present, "yyyy" is used by default. 57 */ 58 kCFISO8601DateFormatWithYear API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 0), 59 kCFISO8601DateFormatWithMonth API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 1), 60 61 kCFISO8601DateFormatWithWeekOfYear API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 2), // This includes the "W" prefix (e.g. "W49") 62 63 /* The format for day is inferred based on provided options. 64 - if month is not present, day of year ("DDD") is used. 65 - if month is present, day of month ("dd") is used. 66 - if either weekOfMonth or weekOfYear is present, local day of week ("ee") is used. 67 */ 68 kCFISO8601DateFormatWithDay API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 4), 69 70 kCFISO8601DateFormatWithTime API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 5), // This uses the format "HHmmss" 71 kCFISO8601DateFormatWithTimeZone API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 6), 72 73 kCFISO8601DateFormatWithSpaceBetweenDateAndTime API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 7), // Use space instead of "T" 74 kCFISO8601DateFormatWithDashSeparatorInDate API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 8), // Add separator for date ("-") 75 kCFISO8601DateFormatWithColonSeparatorInTime API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 9), // Add separator for time (":") 76 kCFISO8601DateFormatWithColonSeparatorInTimeZone API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = (1UL << 10), // Add ":" separator in timezone (eg. +08:00) 77 kCFISO8601DateFormatWithFractionalSeconds API_AVAILABLE(macosx(10.13), ios(11.0), watchos(4.0), tvos(11.0)) = (1UL << 11), // Add 3 significant digits of fractional seconds (".SSS") 78 79 kCFISO8601DateFormatWithFullDate API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = kCFISO8601DateFormatWithYear | kCFISO8601DateFormatWithMonth | kCFISO8601DateFormatWithDay | kCFISO8601DateFormatWithDashSeparatorInDate, 80 kCFISO8601DateFormatWithFullTime API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = kCFISO8601DateFormatWithTime | kCFISO8601DateFormatWithColonSeparatorInTime | kCFISO8601DateFormatWithTimeZone | kCFISO8601DateFormatWithColonSeparatorInTimeZone, 81 82 kCFISO8601DateFormatWithInternetDateTime API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)) = kCFISO8601DateFormatWithFullDate | kCFISO8601DateFormatWithFullTime, // RFC3339 83 }; 84 85 CF_EXPORT 86 CFDateFormatterRef CFDateFormatterCreateISO8601Formatter(CFAllocatorRef allocator, CFISO8601DateFormatOptions formatOptions) API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0)); 87 88 CF_EXPORT 89 CFDateFormatterRef CFDateFormatterCreate(CFAllocatorRef allocator, CFLocaleRef locale, CFDateFormatterStyle dateStyle, CFDateFormatterStyle timeStyle); 90 // Returns a CFDateFormatter, localized to the given locale, which 91 // will format dates to the given date and time styles. 92 93 CF_EXPORT 94 CFLocaleRef CFDateFormatterGetLocale(CFDateFormatterRef formatter); 95 96 CF_EXPORT 97 CFDateFormatterStyle CFDateFormatterGetDateStyle(CFDateFormatterRef formatter); 98 99 CF_EXPORT 100 CFDateFormatterStyle CFDateFormatterGetTimeStyle(CFDateFormatterRef formatter); 101 // Get the properties with which the date formatter was created. 102 103 CF_EXPORT 104 CFStringRef CFDateFormatterGetFormat(CFDateFormatterRef formatter); 105 106 CF_EXPORT 107 void CFDateFormatterSetFormat(CFDateFormatterRef formatter, CFStringRef formatString); 108 // Set the format description string of the date formatter. This 109 // overrides the style settings. The format of the format string 110 // is as defined by the ICU library. The date formatter starts with a 111 // default format string defined by the style arguments with 112 // which it was created. 113 114 115 CF_EXPORT 116 CFStringRef CFDateFormatterCreateStringWithDate(CFAllocatorRef allocator, CFDateFormatterRef formatter, CFDateRef date); 117 118 CF_EXPORT 119 CFStringRef CFDateFormatterCreateStringWithAbsoluteTime(CFAllocatorRef allocator, CFDateFormatterRef formatter, CFAbsoluteTime at); 120 // Create a string representation of the given date or CFAbsoluteTime 121 // using the current state of the date formatter. 122 123 124 CF_EXPORT 125 CFDateRef CFDateFormatterCreateDateFromString(CFAllocatorRef allocator, CFDateFormatterRef formatter, CFStringRef string, CFRange *rangep); 126 127 CF_EXPORT 128 Boolean CFDateFormatterGetAbsoluteTimeFromString(CFDateFormatterRef formatter, CFStringRef string, CFRange *rangep, CFAbsoluteTime *atp); 129 // Parse a string representation of a date using the current state 130 // of the date formatter. The range parameter specifies the range 131 // of the string in which the parsing should occur in input, and on 132 // output indicates the extent that was used; this parameter can 133 // be NULL, in which case the whole string may be used. The 134 // return value indicates whether some date was computed and 135 // (if atp is not NULL) stored at the location specified by atp. 136 137 138 CF_EXPORT 139 void CFDateFormatterSetProperty(CFDateFormatterRef formatter, CFStringRef key, CFTypeRef value); 140 141 CF_EXPORT 142 CFTypeRef CFDateFormatterCopyProperty(CFDateFormatterRef formatter, CFDateFormatterKey key); 143 // Set and get various properties of the date formatter, the set of 144 // which may be expanded in the future. 145 146 CF_EXPORT const CFDateFormatterKey kCFDateFormatterIsLenient; // CFBoolean 147 CF_EXPORT const CFDateFormatterKey kCFDateFormatterTimeZone; // CFTimeZone 148 CF_EXPORT const CFDateFormatterKey kCFDateFormatterCalendarName; // CFString 149 CF_EXPORT const CFDateFormatterKey kCFDateFormatterDefaultFormat; // CFString 150 CF_EXPORT const CFDateFormatterKey kCFDateFormatterTwoDigitStartDate; // CFDate 151 CF_EXPORT const CFDateFormatterKey kCFDateFormatterDefaultDate; // CFDate 152 CF_EXPORT const CFDateFormatterKey kCFDateFormatterCalendar; // CFCalendar 153 CF_EXPORT const CFDateFormatterKey kCFDateFormatterEraSymbols; // CFArray of CFString 154 CF_EXPORT const CFDateFormatterKey kCFDateFormatterMonthSymbols; // CFArray of CFString 155 CF_EXPORT const CFDateFormatterKey kCFDateFormatterShortMonthSymbols; // CFArray of CFString 156 CF_EXPORT const CFDateFormatterKey kCFDateFormatterWeekdaySymbols; // CFArray of CFString 157 CF_EXPORT const CFDateFormatterKey kCFDateFormatterShortWeekdaySymbols; // CFArray of CFString 158 CF_EXPORT const CFDateFormatterKey kCFDateFormatterAMSymbol; // CFString 159 CF_EXPORT const CFDateFormatterKey kCFDateFormatterPMSymbol; // CFString 160 CF_EXPORT const CFDateFormatterKey kCFDateFormatterLongEraSymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 161 CF_EXPORT const CFDateFormatterKey kCFDateFormatterVeryShortMonthSymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 162 CF_EXPORT const CFDateFormatterKey kCFDateFormatterStandaloneMonthSymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 163 CF_EXPORT const CFDateFormatterKey kCFDateFormatterShortStandaloneMonthSymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 164 CF_EXPORT const CFDateFormatterKey kCFDateFormatterVeryShortStandaloneMonthSymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 165 CF_EXPORT const CFDateFormatterKey kCFDateFormatterVeryShortWeekdaySymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 166 CF_EXPORT const CFDateFormatterKey kCFDateFormatterStandaloneWeekdaySymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 167 CF_EXPORT const CFDateFormatterKey kCFDateFormatterShortStandaloneWeekdaySymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 168 CF_EXPORT const CFDateFormatterKey kCFDateFormatterVeryShortStandaloneWeekdaySymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 169 CF_EXPORT const CFDateFormatterKey kCFDateFormatterQuarterSymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 170 CF_EXPORT const CFDateFormatterKey kCFDateFormatterShortQuarterSymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 171 CF_EXPORT const CFDateFormatterKey kCFDateFormatterStandaloneQuarterSymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 172 CF_EXPORT const CFDateFormatterKey kCFDateFormatterShortStandaloneQuarterSymbols API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFArray of CFString 173 CF_EXPORT const CFDateFormatterKey kCFDateFormatterGregorianStartDate API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // CFDate 174 CF_EXPORT const CFDateFormatterKey kCFDateFormatterDoesRelativeDateFormattingKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)); // CFBoolean 175 176 // See CFLocale.h for these calendar constants: 177 // const CFStringRef kCFGregorianCalendar; 178 // const CFStringRef kCFBuddhistCalendar; 179 // const CFStringRef kCFJapaneseCalendar; 180 // const CFStringRef kCFIslamicCalendar; 181 // const CFStringRef kCFIslamicCivilCalendar; 182 // const CFStringRef kCFHebrewCalendar; 183 // const CFStringRef kCFChineseCalendar; 184 // const CFStringRef kCFRepublicOfChinaCalendar; 185 // const CFStringRef kCFPersianCalendar; 186 // const CFStringRef kCFIndianCalendar; 187 // const CFStringRef kCFISO8601Calendar; 188 189 CF_EXTERN_C_END 190 CF_IMPLICIT_BRIDGING_DISABLED 191 192 #endif /* ! __COREFOUNDATION_CFDATEFORMATTER__ */ 193