CNumberFormatter

Package system.i18n
Inheritance class CNumberFormatter » CComponent
Since 1.0
Source Code framework/i18n/CNumberFormatter.php
CNumberFormatter provides number localization functionalities.

CNumberFormatter formats a number (integer or float) and outputs a string based on the specified format. A CNumberFormatter instance is associated with a locale, and thus generates the string representation of the number in a locale-dependent fashion.

CNumberFormatter currently supports currency format, percentage format, decimal format, and custom format. The first three formats are specified in the locale data, while the custom format allows you to enter an arbitrary format string.

A format string may consist of the following special characters:
  • dot (.): the decimal point. It will be replaced with the localized decimal point.
  • comma (,): the grouping separator. It will be replaced with the localized grouping separator.
  • zero (0): required digit. This specifies the places where a digit must appear (will pad 0 if not).
  • hash (#): optional digit. This is mainly used to specify the location of decimal point and grouping separators.
  • currency (¤): the currency placeholder. It will be replaced with the localized currency symbol.
  • percentage (%): the percentage mark. If appearing, the number will be multiplied by 100 before being formatted.
  • permillage (‰): the permillage mark. If appearing, the number will be multiplied by 1000 before being formatted.
  • semicolon (;): the character separating positive and negative number sub-patterns.


Anything surrounding the pattern (or sub-patterns) will be kept.

The followings are some examples:
Pattern "#,##0.00" will format 12345.678 as "12,345.68".
Pattern "#,#,#0.00" will format 12345.6 as "1,2,3,45.60".
Note, in the first example, the number is rounded first before applying the formatting. And in the second example, the pattern specifies two grouping sizes.

CNumberFormatter attempts to implement number formatting according to the Unicode Technical Standard #35. The following features are NOT implemented:
  • significant digit
  • scientific format
  • arbitrary literal characters
  • arbitrary padding

Public Methods

Method Description Defined By
__call() Calls the named method which is not a class method. CComponent
__construct() Constructor. CNumberFormatter
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__unset() Sets a component property to be null. CComponent
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
format() Formats a number based on the specified pattern. CNumberFormatter
formatCurrency() Formats a number using the currency format defined in the locale. CNumberFormatter
formatDecimal() Formats a number using the decimal format defined in the locale. CNumberFormatter
formatPercentage() Formats a number using the percentage format defined in the locale. CNumberFormatter
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
raiseEvent() Raises an event. CComponent

Protected Methods

Method Description Defined By
formatNumber() Formats a number based on a format. CNumberFormatter
parseFormat() Parses a given string pattern. CNumberFormatter

Method Details

__construct() method

public void __construct(mixed $locale)
$locale mixed locale ID (string) or CLocale instance
Source Code: framework/i18n/CNumberFormatter.php#69 (show)
public function __construct($locale)
{
    if(
is_string($locale))
        
$this->_locale=CLocale::getInstance($locale);
    else
        
$this->_locale=$locale;
}

Constructor.

format() method

public string format(string $pattern, mixed $value, string $currency=NULL)
$pattern string format pattern
$value mixed the number to be formatted
$currency string 3-letter ISO 4217 code. For example, the code "USD" represents the US Dollar and "EUR" represents the Euro currency. The currency placeholder in the pattern will be replaced with the currency symbol. If null, no replacement will be done.
{return} string the formatting result.
Source Code: framework/i18n/CNumberFormatter.php#90 (show)
public function format($pattern,$value,$currency=null)
{
    
$format=$this->parseFormat($pattern);
    
$result=$this->formatNumber($format,$value);
    if(
$currency===null)
        return 
$result;
    elseif((
$symbol=$this->_locale->getCurrencySymbol($currency))===null)
        
$symbol=$currency;
    return 
str_replace('¤',$symbol,$result);
}

Formats a number based on the specified pattern. Note, if the format contains '%', the number will be multiplied by 100 first. If the format contains '‰', the number will be multiplied by 1000. If the format contains currency placeholder, it will be replaced by the specified localized currency symbol.

formatCurrency() method

public string formatCurrency(mixed $value, string $currency)
$value mixed the number to be formatted
$currency string 3-letter ISO 4217 code. For example, the code "USD" represents the US Dollar and "EUR" represents the Euro currency. The currency placeholder in the pattern will be replaced with the currency symbol.
{return} string the formatting result.
Source Code: framework/i18n/CNumberFormatter.php#108 (show)
public function formatCurrency($value,$currency)
{
    return 
$this->format($this->_locale->getCurrencyFormat(),$value,$currency);
}

Formats a number using the currency format defined in the locale.

formatDecimal() method

public string formatDecimal(mixed $value)
$value mixed the number to be formatted
{return} string the formatting result.
Source Code: framework/i18n/CNumberFormatter.php#130 (show)
public function formatDecimal($value)
{
    return 
$this->format($this->_locale->getDecimalFormat(),$value);
}

Formats a number using the decimal format defined in the locale.

formatNumber() method

protected string formatNumber(array $format, mixed $value)
$format array format with the following structure:
array(
	// number of required digits after the decimal point,
	// will be padded with 0 if not enough digits,
	// -1 means we should drop the decimal point
	'decimalDigits'=>2,
	// maximum number of digits after the decimal point,
	// additional digits will be truncated.
	'maxDecimalDigits'=>3,
	// number of required digits before the decimal point,
	// will be padded with 0 if not enough digits
	'integerDigits'=>1,
	// the primary grouping size, 0 means no grouping
	'groupSize1'=>3,
	// the secondary grouping size, 0 means no secondary grouping
	'groupSize2'=>0,
	'positivePrefix'=>'+',  // prefix to positive number
	'positiveSuffix'=>'',   // suffix to positive number
	'negativePrefix'=>'(',  // prefix to negative number
	'negativeSuffix'=>')',  // suffix to negative number
	'multiplier'=>1,        // 100 for percent, 1000 for per mille
);
$value mixed the number to be formatted
{return} string the formatted result
Source Code: framework/i18n/CNumberFormatter.php#165 (show)
protected function formatNumber($format,$value)
{
    
$negative=$value<0;
    
$value=abs($value*$format['multiplier']);
    if(
$format['maxDecimalDigits']>=0)
        
$value=number_format($value,$format['maxDecimalDigits'],'.','');
    
$value="$value";
    if(
false !== $pos=strpos($value,'.'))
    {
        
$integer=substr($value,0,$pos);
        
$decimal=substr($value,$pos+1);
    }
    else
    {
        
$integer=$value;
        
$decimal='';
    }
    if(
$format['decimalDigits']>strlen($decimal))
        
$decimal=str_pad($decimal,$format['decimalDigits'],'0');
    elseif(
$format['decimalDigits']<strlen($decimal))
    {
        
$decimal_temp='';
        for(
$i=strlen($decimal)-1;$i>=0;$i--)
            if(
$decimal[$i]!=='0' || strlen($decimal_temp)>0)
                
$decimal_temp=$decimal[$i].$decimal_temp;
        
$decimal=$decimal_temp;
    }
    if(
strlen($decimal)>0)
        
$decimal=$this->_locale->getNumberSymbol('decimal').$decimal;

    
$integer=str_pad($integer,$format['integerDigits'],'0',STR_PAD_LEFT);
    if(
$format['groupSize1']>&& strlen($integer)>$format['groupSize1'])
    {
        
$str1=substr($integer,0,-$format['groupSize1']);
        
$str2=substr($integer,-$format['groupSize1']);
        
$size=$format['groupSize2']>0?$format['groupSize2']:$format['groupSize1'];
        
$str1=str_pad($str1,(int)((strlen($str1)+$size-1)/$size)*$size,' ',STR_PAD_LEFT);
        
$integer=ltrim(implode($this->_locale->getNumberSymbol('group'),str_split($str1,$size))).$this->_locale->getNumberSymbol('group').$str2;
    }

    if(
$negative)
        
$number=$format['negativePrefix'].$integer.$decimal.$format['negativeSuffix'];
    else
        
$number=$format['positivePrefix'].$integer.$decimal.$format['positiveSuffix'];

    return 
strtr($number,array('%'=>$this->_locale->getNumberSymbol('percentSign'),'‰'=>$this->_locale->getNumberSymbol('perMille')));
}

Formats a number based on a format. This is the method that does actual number formatting.

formatPercentage() method

public string formatPercentage(mixed $value)
$value mixed the number to be formatted
{return} string the formatting result.
Source Code: framework/i18n/CNumberFormatter.php#120 (show)
public function formatPercentage($value)
{
    return 
$this->format($this->_locale->getPercentFormat(),$value);
}

Formats a number using the percentage format defined in the locale. Note, if the percentage format contains '%', the number will be multiplied by 100 first. If the percentage format contains '‰', the number will be multiplied by 1000.

parseFormat() method

protected array parseFormat(string $pattern)
$pattern string the pattern to be parsed
{return} array the parsed pattern
Source Code: framework/i18n/CNumberFormatter.php#219 (show)
protected function parseFormat($pattern)
{
    if(isset(
$this->_formats[$pattern]))
        return 
$this->_formats[$pattern];

    
$format=array();

    
// find out prefix and suffix for positive and negative patterns
    
$patterns=explode(';',$pattern);
    
$format['positivePrefix']=$format['positiveSuffix']=$format['negativePrefix']=$format['negativeSuffix']='';
    if(
preg_match('/^(.*?)[#,\.0]+(.*?)$/',$patterns[0],$matches))
    {
        
$format['positivePrefix']=$matches[1];
        
$format['positiveSuffix']=$matches[2];
    }

    if(isset(
$patterns[1]) && preg_match('/^(.*?)[#,\.0]+(.*?)$/',$patterns[1],$matches))  // with a negative pattern
    
{
        
$format['negativePrefix']=$matches[1];
        
$format['negativeSuffix']=$matches[2];
    }
    else
    {
        
$format['negativePrefix']=$this->_locale->getNumberSymbol('minusSign').$format['positivePrefix'];
        
$format['negativeSuffix']=$format['positiveSuffix'];
    }
    
$pat=$patterns[0];

    
// find out multiplier
    
if(strpos($pat,'%')!==false)
        
$format['multiplier']=100;
    elseif(
strpos($pat,'‰')!==false)
        
$format['multiplier']=1000;
    else
        
$format['multiplier']=1;

    
// find out things about decimal part
    
if(($pos=strpos($pat,'.'))!==false)
    {
        if((
$pos2=strrpos($pat,'0'))>$pos)
            
$format['decimalDigits']=$pos2-$pos;
        else
            
$format['decimalDigits']=0;
        if((
$pos3=strrpos($pat,'#'))>=$pos2)
            
$format['maxDecimalDigits']=$pos3-$pos;
        else
            
$format['maxDecimalDigits']=$format['decimalDigits'];
        
$pat=substr($pat,0,$pos);
    }
    else   
// no decimal part
    
{
        
$format['decimalDigits']=0;
        
$format['maxDecimalDigits']=0;
    }

    
// find out things about integer part
    
$p=str_replace(',','',$pat);
    if((
$pos=strpos($p,'0'))!==false)
        
$format['integerDigits']=strrpos($p,'0')-$pos+1;
    else
        
$format['integerDigits']=0;
    
// find out group sizes. some patterns may have two different group sizes
    
$p=str_replace('#','0',$pat);
    if((
$pos=strrpos($pat,','))!==false)
    {
        
$format['groupSize1']=strrpos($p,'0')-$pos;
        if((
$pos2=strrpos(substr($p,0,$pos),','))!==false)
            
$format['groupSize2']=$pos-$pos2-1;
        else
            
$format['groupSize2']=0;
    }
    else
        
$format['groupSize1']=$format['groupSize2']=0;

    return 
$this->_formats[$pattern]=$format;
}

Parses a given string pattern.

See Also

© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CNumberFormatter