xref: /PHP-5.6/ext/intl/doc/formatter_api.php (revision 9762609c)
1<?php
2
3/**
4 * Number formatter class - locale-dependent number formatting/parsing.
5 *
6 * This class represents the ICU number formatting functionality. It allows to display
7 * number according to the localized format or given pattern or set of rules, and to
8 * parse strings into numbers according to the above patterns.
9 *
10 * Example:
11 * <code>
12 * $value = 1234567;
13 * $formatter = new NumberFormatter("de_DE", NumberFormatter::DECIMAL);
14 * echo $formatter->format($value);
15 * </code>
16 *
17 * @see http://www.icu-project.org/apiref/icu4c/unum_8h.html
18 * @see http://www.icu-project.org/apiref/icu4c/classNumberFormat.html
19 *
20 * The class would also contain all the constants listed in the following enums:
21 * UNumberFormatStyle, UNumberFormatRoundingMode, UNumberFormatPadPosition,
22 * UNumberFormatAttribute, UNumberFormatTextAttribute, UNumberFormatSymbol.
23 */
24class NumberFormatter {
25#############################################################################
26# Common constants.
27#############################################################################
28
29	/*
30	 * WARNING:
31	 * The values described here are NOT the actual values in PHP code.
32	 * They are references to the ICU C definitions, so the line
33	 *    const PATTERN_DECIMAL = 'UNUM_PATTERN_DECIMAL';
34	 * actually means that NumberFormatter::PATTERN_DECIMAL is the same as
35	 * UNUM_PATTERN_DECIMAL constant in the ICU library.
36	 */
37
38	/*
39	 * These constants define formatter/parser argument type - integer, floating point or currency.
40	 */
41	const TYPE_DEFAULT     = 'FORMAT_TYPE_DEFAULT';
42	const TYPE_INT32       = 'FORMAT_TYPE_INT32';
43	const TYPE_INT64       = 'FORMAT_TYPE_INT64';
44	const TYPE_DOUBLE      = 'FORMAT_TYPE_DOUBLE';
45	const TYPE_CURRENCY    = 'FORMAT_TYPE_CURRENCY';
46
47	/*
48	 * UNumberFormatStyle constants
49	 */
50	const PATTERN_DECIMAL   = 'UNUM_PATTERN_DECIMAL';
51	const DECIMAL           = 'UNUM_DECIMAL';
52	const CURRENCY          = 'UNUM_CURRENCY';
53	const PERCENT           = 'UNUM_PERCENT';
54	const SCIENTIFIC        = 'UNUM_SCIENTIFIC';
55	const SPELLOUT          = 'UNUM_SPELLOUT';
56	const ORDINAL           = 'UNUM_ORDINAL';
57	const DURATION          = 'UNUM_DURATION';
58	const PATTERN_RULEBASED = 'UNUM_PATTERN_RULEBASED';
59	const DEFAULT           = 'UNUM_DEFAULT';
60	const IGNORE            = 'UNUM_IGNORE';
61
62	/*
63	 * UNumberFormatRoundingMode
64	 */
65	const ROUND_CEILING  = 'UNUM_ROUND_CEILING';
66	const ROUND_FLOOR    = 'UNUM_ROUND_FLOOR';
67	const ROUND_DOWN     = 'UNUM_ROUND_DOWN';
68	const ROUND_UP       = 'UNUM_ROUND_UP';
69	const ROUND_HALFEVEN = 'UNUM_ROUND_HALFEVEN';
70	const ROUND_HALFDOWN = 'UNUM_ROUND_HALFDOWN';
71	const ROUND_HALFUP   = 'UNUM_ROUND_HALFUP';
72
73	/*
74	 * UNumberFormatPadPosition
75	 */
76	const PAD_BEFORE_PREFIX = 'UNUM_PAD_BEFORE_PREFIX';
77	const PAD_AFTER_PREFIX  = 'UNUM_PAD_AFTER_PREFIX';
78	const PAD_BEFORE_SUFFIX = 'UNUM_PAD_BEFORE_SUFFIX';
79	const PAD_AFTER_SUFFIX  = 'UNUM_PAD_AFTER_SUFFIX';
80
81	/*
82	 * UNumberFormatAttribute
83	 */
84	const PARSE_INT_ONLY          = 'UNUM_PARSE_INT_ONLY';
85	const GROUPING_USED           = 'UNUM_GROUPING_USED';
86	const DECIMAL_ALWAYS_SHOWN    = 'UNUM_DECIMAL_ALWAYS_SHOWN';
87	const MAX_INTEGER_DIGITS      = 'UNUM_MAX_INTEGER_DIGITS';
88	const MIN_INTEGER_DIGITS      = 'UNUM_MIN_INTEGER_DIGITS';
89	const INTEGER_DIGITS          = 'UNUM_INTEGER_DIGITS';
90	const MAX_FRACTION_DIGITS     = 'UNUM_MAX_FRACTION_DIGITS';
91	const MIN_FRACTION_DIGITS     = 'UNUM_MIN_FRACTION_DIGITS';
92	const FRACTION_DIGITS         = 'UNUM_FRACTION_DIGITS';
93	const MULTIPLIER              = 'UNUM_MULTIPLIER';
94	const GROUPING_SIZE           = 'UNUM_GROUPING_SIZE';
95	const ROUNDING_MODE           = 'UNUM_ROUNDING_MODE';
96	const ROUNDING_INCREMENT      = 'UNUM_ROUNDING_INCREMENT';
97	const FORMAT_WIDTH            = 'UNUM_FORMAT_WIDTH';
98	const PADDING_POSITION        = 'UNUM_PADDING_POSITION';
99	const SECONDARY_GROUPING_SIZE = 'UNUM_SECONDARY_GROUPING_SIZE';
100	const SIGNIFICANT_DIGITS_USED = 'UNUM_SIGNIFICANT_DIGITS_USED';
101	const MIN_SIGNIFICANT_DIGITS  = 'UNUM_MIN_SIGNIFICANT_DIGITS';
102	const MAX_SIGNIFICANT_DIGITS  = 'UNUM_MAX_SIGNIFICANT_DIGITS';
103	const LENIENT_PARSE           = 'UNUM_LENIENT_PARSE';
104
105	/*
106	 * UNumberFormatTextAttribute
107	 */
108	const POSITIVE_PREFIX   = 'UNUM_POSITIVE_PREFIX';
109	const POSITIVE_SUFFIX   = 'UNUM_POSITIVE_SUFFIX';
110	const NEGATIVE_PREFIX   = 'UNUM_NEGATIVE_PREFIX';
111	const NEGATIVE_SUFFIX   = 'UNUM_NEGATIVE_SUFFIX';
112	const PADDING_CHARACTER = 'UNUM_PADDING_CHARACTER';
113	const CURRENCY_CODE     = 'UNUM_CURRENCY_CODE';
114	const DEFAULT_RULESET   = 'UNUM_DEFAULT_RULESET';
115	const PUBLIC_RULESETS   = 'UNUM_PUBLIC_RULESETS';
116
117	/*
118	 * UNumberFormatSymbol
119	 */
120	const DECIMAL_SEPARATOR_SYMBOL           = 'UNUM_DECIMAL_SEPARATOR_SYMBOL';
121	const GROUPING_SEPARATOR_SYMBOL          = 'UNUM_GROUPING_SEPARATOR_SYMBOL';
122	const PATTERN_SEPARATOR_SYMBOL           = 'UNUM_PATTERN_SEPARATOR_SYMBOL';
123	const PERCENT_SYMBOL                     = 'UNUM_PERCENT_SYMBOL';
124	const ZERO_DIGIT_SYMBOL                  = 'UNUM_ZERO_DIGIT_SYMBOL';
125	const DIGIT_SYMBOL                       = 'UNUM_DIGIT_SYMBOL';
126	const MINUS_SIGN_SYMBOL                  = 'UNUM_MINUS_SIGN_SYMBOL';
127	const PLUS_SIGN_SYMBOL                   = 'UNUM_PLUS_SIGN_SYMBOL';
128	const CURRENCY_SYMBOL                    = 'UNUM_CURRENCY_SYMBOL';
129	const INTL_CURRENCY_SYMBOL               = 'UNUM_INTL_CURRENCY_SYMBOL';
130	const MONETARY_SEPARATOR_SYMBOL          = 'UNUM_MONETARY_SEPARATOR_SYMBOL';
131	const EXPONENTIAL_SYMBOL                 = 'UNUM_EXPONENTIAL_SYMBOL';
132	const PERMILL_SYMBOL                     = 'UNUM_PERMILL_SYMBOL';
133	const PAD_ESCAPE_SYMBOL                  = 'UNUM_PAD_ESCAPE_SYMBOL';
134	const INFINITY_SYMBOL                    = 'UNUM_INFINITY_SYMBOL';
135	const NAN_SYMBOL                         = 'UNUM_NAN_SYMBOL';
136	const SIGNIFICANT_DIGIT_SYMBOL           = 'UNUM_SIGNIFICANT_DIGIT_SYMBOL';
137	const MONETARY_GROUPING_SEPARATOR_SYMBOL = 'UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL';
138
139	/**
140	 * Create a number formatter
141	 *
142	 * Creates a number formatter from locale and pattern. This formatter would be used to
143	 * format or parse numbers.
144	 *
145	 * @param integer $style     Style of the formatting, one of the UNumberFormatStyle constants
146	 * @param string $locale     Locale in which the number would be formatted
147	 * @param [string] $pattern  Pattern string in case chose style requires pattern
148	 * @return NumberFormatter
149	 */
150	public function __construct($locale, $style, $pattern = null) {}
151
152	/**
153	 * Create a number formatter
154	 *
155	 * Creates a number formatter from locale and pattern. This formatter would be used to
156	 * format or parse numbers.
157	 *
158	 * This method is useful when you prefer just to get null on error,
159	 * as if you called numfmt_create().
160	 *
161	 * @param integer  $style    Style of the formatting, one of the UNumberFormatStyle constants
162	 * @param string   $locale   Locale in which the number would be formatted
163	 * @param [string] $pattern  Pattern string in case chose style requires pattern
164	 * @return NumberFormatter
165	 * @see __construct
166	 * @see numfmt_create
167	 */
168	public static function create($locale, $style, $pattern = null) {}
169
170	/**
171	 * Format a number according to current formatting rules.
172	 *
173	 * If the type is not specified, the type is derived from the $number parameter. I.e., if it's
174	 * integer then INT32 would be chosen on 32-bit, INT64 on 64-bit, if it's double, DOUBLE would be
175	 * chosen. It is possible to format 64-bit number on 32-bit machine by passing it as double and using
176	 * TYPE_INT64.
177	 * When formatting currency, default formatter's currency code is used.
178	 *
179	 * @param integer|double $number Number to format
180	 * @param [integer]      $type   Type of the formatting - one of TYPE constants. If not specified, default for the type.
181	 * @return string formatted number
182	 */
183	public function format($number, $type = 0) {}
184
185	/**
186	 * Parse a number according to current formatting rules.
187	 *
188	 * @param string     $string   String to parse
189	 * @param [integer]  $type     Type of the formatting - one of TYPE constants.
190	 *                             TYPE_DOUBLE is used by default.
191	 * @param [integer]  $position On input, the position to start parsing, default is 0;
192	 *                             on output, moved to after the last successfully parse character;
193	 *                             on parse failure, does not change.
194	 * @return integer|double|false  Parsed number, false if parsing failed
195	 */
196	public function parse($string, $type, &$position) {}
197
198	/**
199	 * Format number as currency.
200	 *
201	 * Uses user-defined currency string.
202	 *
203	 * @param double $number    Number to format
204	 * @param string $currency  3-letter currency code (ISO 4217) to use in format
205	 */
206	public function formatCurrency($number, $currency) {}
207
208	/**
209	 * Parse currency string
210	 *
211	 * This parser would use parseCurrency API string to parse currency string. The format is defined by the
212	 * formatter, returns both number and currency code.
213	 *
214	 * @param string    $string    String to parse
215	 * @param string    $currency  Parameter to return parsed currency code
216	 * @param [integer] $position  On input, the position within text to match, default is 0;
217	 *                             on output, the position after the last matched character;
218	 *                             on parse failure, does not change.
219	 * @return double currency number
220	 */
221	public function parseCurrency($string, &$currency, &$position) {}
222
223	/**
224	 * Set formatter attribute.
225	 *
226	 * This function is used to set any of the formatter attributes. Example:
227	 *
228	 * $formatter->setAttribute(NumberFormat::FORMAT_WIDTH, 10);
229 	 *
230	 * @param integer        $attr  One of UNumberFormatAttribute constants
231	 * @param integer|double $value Value of the attribute
232	 * @return false if attribute is unknown or can not be set, true otherwise
233	 */
234	public function setAttribute($attr, $value) {}
235	/**
236	 * Set formatter attribute.
237	 *
238	 * This function is used to set any of the formatter attributes. Example:
239	 *
240	 * $formatter->setTextAttribute(NumberFormat::POSITIVE_PREFIX, "+");
241	 *
242	 * @param integer $attr  One of UNumberFormatTextAttribute constants
243	 * @param string  $value Value of the attribute
244	 * @return false if attribute is unknown or can not be set, true otherwise
245	 */
246	public function setTextAttribute($attr, $value) {}
247	/**
248	 * Set formatting symbol.
249	 *
250	 * Example:
251	 *
252	 * $formatter->setSymbol(NumberFormat::EXPONENTIAL_SYMBOL, "E");
253	 *
254	 * @param integer|array $attr  One of UNumberFormatSymbol constants or array of symbols, indexed by
255	 * 								these constants
256	 * @param string        $value Value of the symbol
257	 */
258	public function setSymbol($attr, $value) {}
259	/**
260	 * Set pattern used by the formatter
261	 *
262	 * Valid only if the formatter is using pattern and is not rule-based.
263	 * @see http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html
264	 * Localized patterns are not currently supported.
265	 *
266	 * @param string $pattern  The pattern to be used.
267	 * @return boolean         false if formatter pattern could not be set, true otherwise
268	 */
269	public function setPattern($pattern) {}
270	/**
271	 * Get value of the formatter attribute
272	 *
273	 * @param integer $attr One of UNumberFormatAttribute constants
274	 * @return integer|double value of the attribute or false if the value can not be obtained
275	 */
276	public function getAttribute($attr) {}
277	/**
278	 * Get value of the formatter attribute
279	 *
280	 * @param integer $attr One of UNumberFormatTextAttribute constants
281	 * @return string value of the attribute or false if the value can not be obtained
282	 */
283	public function getTextAttribute($attr) {}
284	/**
285	 * Get value of the formatter symbol
286	 *
287	 * @param integer $attr One of UNumberFormatSymbol constants specifying the symbol
288	 * @return string|false The symbol value, or false if the value can not be obtained
289	 */
290	public function getSymbol($attr) {}
291	/**
292	 * Get pattern used by the formatter.
293	 *
294	 * Gets current state of the formatter as a pattern.
295	 * Localized patterns are not currently supported.
296	 *
297	 * Valid only if the formatter is UNUM_PATTERN_DECIMAL
298	 * @return string|false The pattern used by the formatter or false if formatter is of a type
299	 *                      that does not support patterns.
300	 */
301	public function getPattern() {}
302	/**
303	 * Get the locale for which the formatter was created.
304	 *
305	 * @param [integer] $type One of  ULocDataLocaleType  values
306	 * @return string locale name
307	 */
308	public function getLocale($type = 0) {}
309	/**
310	 * Get the error code from last operation
311	 *
312	 * Returns error code from the last number formatting operation.
313	 *
314	 * @return integer the error code, one of UErrorCode values. Initial value is U_ZERO_ERROR.
315	 */
316	public function getErrorCode() {}
317	/**
318	 * Get the error text from the last operation.
319	 *
320	 * @return string Description of the last occurred error.
321	 */
322	public public function getErrorMessage() {}
323
324}
325
326/** Now the same as procedural API */
327
328/**
329 * Create a number formatter
330 *
331 * Creates a number formatter from locale and pattern. This formatter would be used to
332 * format or parse numbers.
333 *
334 * @param string   $locale   Locale in which the number would be formatted
335 * @param integer  $style    Style of the formatting, one of the UNumberFormatStyle constants
336 * @param [string] $pattern  Pattern string in case chose style requires pattern
337 * @return Numberformatter resource NumberFormatter
338 */
339function numfmt_create($locale, $style, $pattern = null) {}
340/**
341 * Format a number according to current formatting rules.
342 *
343 * If the type is not specified, the type is derived from the $number parameter. I.e., if it's
344 * integer then INT32 would be chosen on 32-bit, INT64 on 64-bit, if it's double, DOUBLE would be
345 * chosen. It is possible to format 64-bit number on 32-bit machine by passing it as double and using
346 * TYPE_INT64.
347 *
348 * @param NumberFormatter $formatter The formatter resource
349 * @param integer|double  $number	 Number to format
350 * @param [integer]       $type		 Type of the formatting - one of TYPE constants. If not specified, default for the type.
351 * @return string formatted number
352 */
353function numfmt_format($formatter, $number, $type = null) {}
354/**
355 * Parse a number according to current formatting rules.
356 *
357 * This parser uses DOUBLE type by default. When parsing currency,
358 * default currency definitions are used.
359 *
360 * @param NumberFormatter $formatter       The formatter resource
361 * @param string                 $string   String to parse
362 * @param [integer]              $type     Type of the formatting - one of TYPE constants.
363 * @param [integer]              $position String position after the end of parsed data.
364 * @return integer|double|false  Parsed number, false if parsing failed
365 */
366function numfmt_parse($formatter, $string, $type, &$position) {}
367/**
368 * Format number as currency.
369 *
370 * Uses user-defined currency string.
371 *
372 * @param NumberFormatter $formatter The formatter resource
373 * @param double          $number    Number to format
374 * @param string          $currency  3-letter currency code (ISO 4217) to use in format
375 */
376function numfmt_format_currency($formatter, $number, $currency) {}
377/**
378 * Parse currency string
379 *
380 * This parser would use parseCurrency API string to parse currency string. The format is defined by the
381 * formatter, returns both number and currency code.
382 *
383 * @param NumberFormatter $formatter The formatter resource
384 * @param string          $string    String to parse
385 * @param string          $currency  Parameter to return parsed currency code
386 * @param [integer]       $position  String position after the end of parsed data.
387 * @return double currency number
388 */
389function numfmt_parse_currency($formatter, $string, &$currency, &$position) {}
390/**
391 * Set formatter attribute.
392 *
393 * This function is used to set any of the formatter attributes. Example:
394 *
395 * numfmt_format_set_attribute($formatter, NumberFormat::FORMAT_WIDTH, 10);
396 *
397 * @param NumberFormatter $formatter The formatter resource
398 * @param integer         $attr      One of UNumberFormatAttribute constants
399 * @param integer|double  $value     Value of the attribute
400 * @return false if attribute is unknown or can not be set, true otherwise
401 */
402function numfmt_set_attribute($formatter, $attribute, $value) {}
403/**
404 * Set formatter attribute.
405 *
406 * This function is used to set any of the formatter attributes. Example:
407 *
408 * numfmt_format_set_text_attribute($formatter, NumberFormat::POSITIVE_PREFIX, "+");
409 *
410 * @param NumberFormatter $formatter The formatter resource
411 * @param integer         $attr      One of UNumberFormatTextAttribute constants
412 * @param string          $value     Value of the attribute
413 * @return false if attribute is unknown or can not be set, true otherwise
414 */
415function numfmt_set_text_attribute($formatter, $attribute, $value) {}
416/**
417 * Set formatting symbol.
418 *
419 * Example:
420 *
421 * $formatter->setSymbol(NumberFormat::EXPONENTIAL_SYMBOL, "E");
422 *
423 * @param NumberFormatter $formatter The formatter resource
424 * @param integer|array   $attr      One of UNumberFormatSymbol constants or array of symbols,
425 *                                   indexed by these constants
426 * @param string $value Value of the symbol
427 */
428function numfmt_set_symbol($formatter, $attribute, $value) {}
429/**
430 * Set pattern used by the formatter
431 *
432 * Valid only if the formatter is using pattern and is not rule-based.
433 * @see http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html
434 * Localized patterns are not currently supported.
435 *
436 * @param NumberFormatter $formatter The formatter resource
437 * @param string          $pattern   The pattern to be used.
438 * @return boolean false if formatter pattern could not be set, true otherwise
439 */
440function numfmt_set_pattern($formatter, $pattern) {}
441/**
442 * Get value of the formatter attribute
443 *
444 * @param NumberFormatter $formatter The formatter resource
445 * @param integer         $attribute One of UNumberFormatAttribute constants
446 * @return integer|double value of the attribute or false if the value can not be obtained
447 */
448function numfmt_get_attribute($formatter, $attribute) {}
449/**
450 * Get value of the formatter attribute
451 *
452 * @param NumberFormatter $formatter The formatter resource
453 * @param integer         $attribute One of UNumberFormatTextAttribute constants
454 * @return string value of the attribute or false if the value can not be obtained
455 */
456function numfmt_get_text_attribute($formatter, $attribute) {}
457/**
458 * Get value of the formatter symbol
459 *
460 * @param NumberFormatter $formatter The formatter resource
461 * @param integer         $attribute One of UNumberFormatSymbol constants specifying the symbol
462 * @return string|false The symbol value, or false if the value can not be obtained
463 */
464function numfmt_get_symbol($formatter, $attribute) {}
465/**
466 * Get pattern used by the formatter.
467 *
468 * Gets current state of the formatter as a pattern.
469 * Localized patterns are not currently supported.
470 *
471 * Valid only if the formatter is   UNUM_PATTERN_DECIMAL
472 * @param NumberFormatter $formatter The formatter resource
473 * @return string|false The pattern used by the formatter or false if formatter is of a type
474 *                      that does not support patterns.
475 */
476function numfmt_get_pattern($formatter) {}
477/**
478 * Get the locale for which the formatter was created.
479 *
480 * @param NumberFormatter $formatter The formatter resource
481 * @param [integer]       $type      One of ULocDataLocaleType values
482 * @return string locale name
483 */
484function numfmt_get_locale($formatter, $type = 0) {}
485/**
486 * Get the error code from last operation
487 *
488 * Returns error code from the last number formatting operation.
489 *
490 * @param NumberFormatter $formatter The formatter resource
491 * @return integer the error code, one of UErrorCode values. Initial value is U_ZERO_ERROR.
492 */
493function numfmt_get_error_code($formatter) {}
494/**
495 * Get the error text from the last operation.
496 *
497 * @param NumberFormatter $formatter The formatter resource
498 * @return string Description of the last occurred error.
499 */
500function numfmt_get_error_message($formatter) {}
501