xref: /PHP-5.4/ext/intl/doc/datefmt_api.php (revision 9762609c)
1<?php
2
3/**
4 * Date Formatter class - locale-dependent formatting/parsing of dates using pattern strings and/or canned patterns.
5 *
6 * This class represents the ICU date formatting functionality. It allows users to
7 * display dates in a localized format or to parse strings
8 * into PHP date values using pattern strings and/or canned patterns.
9 *
10 * Example:
11 * <code>
12 * $datefmt = new DateFormatter("de-DE", LONG, SHORT, date_default_timezone_get());
13 * echo $formatter->format(time());
14 * </code>
15 *
16 * <code>
17 *  $datefmt = new DateFormatter("de-DE", LONG, SHORT, date_default_timezone_get() , GREGORIAN , "yyyy-MM-dd HH:mm:ss z");
18 *  echo $formatter->format(time());
19 * </code>
20 *
21 * @see http://www.icu-project.org/apiref/icu4c/udat_8h.html
22 *
23 */
24class DateFormatter {
25
26#############################################################################
27# Common constants.
28#############################################################################
29
30   /**
31    * The following constants are used to specify different formats
32    * in the constructor.
33    */
34    const NONE = -1;
35    const FULL = 0;
36    const LONG = 1;
37    const MEDIUM = 2;
38    const SHORT = 3;
39
40    /**
41     * The following int constants are used to specify the calendar.
42     * These calendars are all based directly on the Gregorian calendar
43     * Non-Gregorian calendars need to be specified in locale.
44     * Examples might include locale="hi@calendar=BUDDHIST"
45     */
46    const TRADITIONAL = 0; // non-Gregorian calendar that is locale-defined, required by ICU
47    const GREGORIAN = 1 ;// Gregorian calendar
48
49#############################################################################
50# Object-oriented API
51#############################################################################
52	/**
53	 * Create a date formatter
54	 *
55	 * @param string  $locale     Locale to use when formatting or parsing
56	 * @param integer $datetype   Date type to use (none, short, medium, long, full)
57	 * @param integer $timetype   Time type to use (none, short, medium, long, full)
58	 * @param [String] $timezone  Time zone ID ; default is system default
59	 * @param [integer] $calendar Calendar to use for formatting or parsing; default is
60	 *                            GREGORIAN
61	 * @param [string]  $pattern  Optional pattern to use when formatting or parsing
62	 * @return DateFormatter
63	 * @see __construct
64	 * @see datefmt_create
65	 */
66	public function __construct($locale, $datetype, $timetype, $timezone = null, $calendar= null , $pattern= null) {}
67
68	/**
69	 * Create a date formatter
70	 *
71	 * @param string  $locale     Locale to use when formatting or parsing
72	 * @param integer $datetype   Date type to use (none, short, medium, long, full)
73	 * @param integer $timetype   Time type to use (none, short, medium, long, full)
74	 * @param [string] $timezone  Time zone ID ; default is system default
75	 * @param [integer] $calendar Calendar to use for formatting or parsing; default is
76	 *                            GREGORIAN
77	 * @param [string]  $pattern  Optional pattern to use when formatting or parsing
78	 * @return DateFormatter
79	 * @see __construct
80	 * @see datefmt_create
81	 */
82	public static function create($locale, $datetype, $timetype, $timezone = null, $calendar= null , $pattern= null) {}
83
84	/**
85         * formats the time value as a string.
86	 * @param mixed $value - value to format
87         *     integer: a unix timestamp value (seconds since epoch, UTC)
88         *     array: a localtime array  - uses 24 hour clock in tm_hour field
89         * @return string  a formatted string or, if an error occurred, 'null'.
90	 */
91        public function format($value) {}
92
93
94        /**
95         * converts string $value to an incremental time value, starting at
96	 * $parse_pos and consuming as much of the input value as possible
97	 * If no error occurs before $value is consumed, $parse_pos will contain -1
98	 * otherwise it will contain the position at which parsing ended (and the error
99	 * occurred).
100	 * @param string  $value      string to convert to a time
101	 * @param integer $parse_pos  position at which to start the parsing in $value (zero-based)
102	 *                            This variable will contain the end position if the parse fails
103	 *                            If $parse_pos > strlen($value), the parse fails immediately.
104	 * @return integer timestamp  parsed value
105	 */
106	 public function parse($value, $parse_pos=0) {}
107
108
109        /**
110         * converts string $value to a field-based time value, starting at
111	 * $parse_pos and consuming as much of the input value as possible
112	 * If no error occurs before $value is consumed, $parse_pos will contain -1
113	 * otherwise it will contain the position at which parsing ended (and the error
114	 * occurred).
115	 * @param string  $value      string to convert to a time
116	 * @param integer $parse_pos  position at which to start the parsing in $value (zero-based)
117	 *                            This variable will contain the end position if the parse fails
118	 *                            If $parse_pos > strlen($value), the parse fails immediately.
119	 * @return array localtime compatible array of integers  - uses 24 hour clock in tm_hour field
120	 */
121	 public function localtime($value, $parse_pos=0) {}
122
123
124	 /**
125	  * Gets the datetype in use
126	  * @return integer the current 'datetype' value of the formatter
127	  */
128         public function getDateType() {}
129
130
131	 /**
132	  * Gets the timetype in use
133	  * @return integer the current 'timetype' value of the formatter
134	  */
135         public function getTimeType() {}
136
137
138	 /**
139	  * Gets the leniency in use
140	  * @return boolean   'true' if parser is lenient, 'false' if parser is strict
141	  *                   default value for parser is 'false'.
142	  */
143         public function isLenient() {}
144
145
146	 /**
147	  * Sets the leniency to use
148	  * @param boolean $lenient  sets whether the parser is lenient or not, default is 'false'
149          *                          'true' sets the parser to accept otherwise flawed date or
150	  *                          time patterns, parsing as much as possible to obtain a value.
151          *                          'false' sets the parser to strictly parse strings into dates.
152	  *                          Extra space, unrecognized tokens, or invalid values
153	  *                          ("Feburary 30th") are not accepted.
154	  *
155          * @return boolean          'true' if successful; 'false' if an error occurred.
156	  */
157	 public function setLenient($lenient) {}
158
159
160	 /**
161	  * Gets the locale in use
162	  * @param  [integer]  which locale should be returned?
163	  *                    values may include ULOC_ACTUAL_LOCALE,
164	  *                    ULOC_VALID_LOCALE. By default the actual
165	  *                    locale is returned.
166	  * @return string     the locale of this formatter  or 'false' if error
167	 */
168
169	 public function getLocale($type = ULOC_ACTUAL_LOCALE) {}
170
171
172         /**
173	  * @return string ID string for the time zone used by this formatter
174	  */
175	 public function getTimeZoneId() {}
176
177
178	/**
179	 * sets the time zone to use
180	 * @param string $zone zone ID string of the time zone to use.
181	 *                     if null or the empty string, the default time zone for
182	 *                     the runtime is used.
183	 * @return boolean 'true' on successful setting of the time zone, 'false'
184	 *                 if an error occurred (such as the time zone wasn't recognized).
185	 */
186        public function setTimeZoneId($zone) {}
187
188
189        /**
190         * Sets the calendar used to the appropriate calendar, which must be
191	 * one of the constants defined above. Some examples include:
192         *   - Gregorian calendar
193         *   - Traditional
194         * Default value is GREGORIAN
195	 * @param integer $which the calendar (an enumerated constant) to use.
196         * @return boolean 'true' if successful, 'false' if an error occurred or if the calendar was not recognized
197	 */
198         public function setCalendar($which) {}
199
200
201        /**
202	 * Gets the Calendar in use
203	 * @return integer the calendar being used by the formatter
204	 */
205         public function getCalendar() {}
206
207
208        /**
209	 * Gets the pattern in use
210    	 * @return string the pattern string being used to format/parse
211	 */
212	public function getPattern() {}
213
214
215        /**
216	 * Sets the pattern to  use
217         * @param  string $pattern new pattern string to use
218         * @return boolean 'true' if successful, 'false' if an error occurred. Bad format
219         *                 strings are usually the cause of the latter.
220         */
221	public function setPattern($pattern) {}
222
223
224	/**
225	 * Get the error code from last operation
226	 *
227	 * Returns error code from the last number formatting operation.
228	 *
229	 * @return integer the error code, one of UErrorCode values. Initial value is U_ZERO_ERROR.
230	 */
231	public function getErrorCode() {}
232
233
234	/**
235	 * Get the error text from the last operation.
236	 *
237	 * @return string Description of the last error.
238	 */
239	public function getErrorMessage() {}
240
241
242}
243
244#############################################################################
245# Procedural API
246#############################################################################
247
248
249	/**
250	 * Create a date formatter
251	 *
252	 * @param string  $locale     Locale to use when formatting or parsing
253	 * @param integer $datetype   Date type to use (none, short, medium, long, full)
254	 * @param integer $timetype   Time type to use (none, short, medium, long, full)
255	 * @param [string] $timezone  Time zone ID ; default is system default
256	 * @param [integer] $calendar Calendar to use for formatting or parsing; default is
257	 *                            GREGORIAN
258	 * @param [string]  $pattern  Optional pattern to use when formatting or parsing
259	 * @return DateFormatter
260	 * @see datefmt_create
261	 */
262	function datefmt_create($locale, $datetype, $timetype, $timezone = null, $calendar= null ,$pattern=null ) {}
263
264
265	/**
266         * formats the time value as a string.
267         * @param DateFormatter $fmt The date formatter resource
268	 * @param mixed $value - value to format
269         *     integer: a unix timestamp value (seconds since epoch, UTC)
270         *     array: a localtime array   - uses 24 hour clock in tm_hour field
271         * @return string  a formatted string or, if an error occurred, 'null'.
272	 */
273        function datefmt_format($fmt , $value) {}
274
275
276        /**
277         * converts string $value to an incremental time value, starting at
278	 * $parse_pos and consuming as much of the input value as possible
279	 * If no error occurs before $value is consumed, $parse_pos will contain -1
280	 * otherwise it will contain the position at which parsing ended (and the error
281	 * occurred).
282         * @param DateFormatter $fmt The date formatter resource
283	 * @param string  $value      string to convert to a time
284	 * @param integer $parse_pos  position at which to start the parsing in $value (zero-based)
285	 *                            This variable will contain the end position if the parse fails
286	 *                            If $parse_pos > strlen($value), the parse fails immediately.
287	 * @return integer timestamp  parsed value
288	 */
289	 function datefmt_parse($fmt , $value, $parse_pos=0) {}
290
291
292        /**
293         * converts string $value to a field-based time value, starting at
294	 * $parse_pos and consuming as much of the input value as possible
295	 * If no error occurs before $value is consumed, $parse_pos will contain -1
296	 * otherwise it will contain the position at which parsing ended (and the error
297	 * occurred).
298         * @param DateFormatter $fmt The date formatter resource
299	 * @param string  $value      string to convert to a time
300	 * @param integer $parse_pos  position at which to start the parsing in $value (zero-based)
301	 *                            This variable will contain the end position if the parse fails
302	 *                            If $parse_pos > strlen($value), the parse fails immediately.
303	 * @return array localtime compatible array of integers  - uses 24 hour clock in tm_hour field
304	 */
305	 function datefmt_localtime($fmt , $value, $parse_pos=0) {}
306
307
308	 /**
309	  * Gets the  Datetype in use
310          * @param DateFormatter $fmt The date formatter resource
311	  * @return integer the current 'datetype' value of the formatter
312	  */
313         function datefmt_get_datetype($fmt ) {}
314
315
316	 /**
317	  * Gets the  timetype in use
318          * @param DateFormatter $fmt The date formatter resource
319	  * @return integer the current 'timetype' value of the formatter
320	  */
321         function datefmt_get_timetype($fmt) {}
322
323
324	 /**
325	  * Gets the leniency of the formatter
326          * @param DateFormatter $fmt The date formatter resource
327	  * @return boolean   'true' if parser is lenient, 'false' if parser is strict
328	  *                   default value for parser is 'false'.
329	  */
330         function datefmt_is_lenient($fmt) {}
331
332
333	 /**
334	  * Sets the leniency of the formatter
335          * @param DateFormatter $fmt The date formatter resource
336	  * @param boolean $lenient  sets whether the parser is lenient or not, default is 'false'
337          *                          'true' sets the parser to accept otherwise flawed date or
338	  *                          time patterns, parsing as much as possible to obtain a value.
339          *                          'false' sets the parser to strictly parse strings into dates.
340	  *                          Extra space, unrecognized tokens, or invalid values
341	  *                          ("Feburary 30th") are not accepted.
342	  *
343          * @return boolean          'true' if successful; 'false' if an error occurred.
344	  */
345	 function datefmt_set_lenient($fmt , $lenient) {}
346
347
348	 /**
349	  * Gets the locale in  use
350          * @param DateFormatter $fmt The date formatter resource
351	  * @param  [integer]  which locale should be returned?
352	  *                    values may include ULOC_ACTUAL_LOCALE,
353	  *                    ULOC_VALID_LOCALE. By default the actual
354	  *                    locale is returned.
355	  * @return string     the locale of this formatter  or 'false' if error
356	 */
357	 function datefmt_get_locale($fmt , $type = ULOC_ACTUAL_LOCALE) {}
358
359
360         /**
361	  * Gets the time zone id in  use
362          * @param DateFormatter $fmt The date formatter resource
363	  * @return string ID string for the time zone used by this formatter
364	  */
365	 function datefmt_get_timezone_id($fmt) {}
366
367
368	/**
369	 * Sets the time zone to use
370         * @param DateFormatter $fmt The date formatter resource
371	 * @param string $zone zone ID string of the time zone to use.
372	 *                     if null or the empty string, the default time zone for
373	 *                     the runtime is used.
374	 * @return boolean 'true' on successful setting of the time zone, 'false'
375	 *                 if an error occurred (such as the time zone wasn't recognized).
376	 */
377        function datefmt_set_timezone_id($fmt , $zone) {}
378
379
380        /**
381         * Sets the calendar used to the appropriate calendar, which must be
382	 * one of the constants defined above. Some examples include:
383         *   - Gregorian calendar
384         *   - Traditional
385         * Default value is GREGORIAN
386         * @param DateFormatter $fmt The date formatter resource
387	 * @param integer $which the calendar (an enumerated constant) to use.
388         * @return boolean 'true' if successful, 'false' if an error occurred or if the calendar was not recognized
389	 */
390         function datefmt_set_calendar($fmt , $which) {}
391
392
393        /**
394	 * Gets the calendar in use
395         * @param DateFormatter $fmt The date formatter resource
396	 * @return integer the calendar being used by the formatter
397	 */
398         function datefmt_get_calendar($fmt) {}
399
400
401        /**
402	 * Gets the pattern in use
403         * @param DateFormatter $fmt The date formatter resource
404         * @return string the pattern string being used to format/parse
405         */
406        function  datefmt_get_pattern($fmt) {}
407
408
409        /**
410	 * Sets the pattern to use
411         * @param DateFormatter $fmt The date formatter resource
412         * @param  string $pattern new pattern string to use
413         * @return boolean 'true' if successful, 'false' if an error occurred. Bad format
414         *                 strings are usually the cause of the latter.
415         */
416        function datefmt_set_pattern($fmt , $pattern) {}
417
418
419	/**
420	 * Get the error code from last operation
421	 *
422         * @param DateFormatter $fmt The date formatter resource
423	 * Returns error code from the last number formatting operation.
424	 *
425	 * @return integer the error code, one of UErrorCode values. Initial value is U_ZERO_ERROR.
426	 */
427	function datefmt_get_error_code($fmt) {}
428
429
430	/**
431	 * Get the error text from the last operation.
432	 *
433         * @param DateFormatter $fmt The date formatter resource
434	 * @return string Description of the last error.
435	 */
436	function datefmt_get_error_message($fmt) {}
437