Modules

Num
extends Kohana_Num

Number helper class. Provides additional formatting methods that for working with numbers.

package
Kohana
category
Helpers
author
Kohana Team
copyright
© 2009-2012 Kohana Team
license
http://kohanaframework.org/license

Class declared in SYSPATH/classes/Num.php on line 3.

Constants

ROUND_HALF_UP

integer 1

ROUND_HALF_DOWN

integer 2

ROUND_HALF_EVEN

integer 3

ROUND_HALF_ODD

integer 4

Properties

public static array $byte_units

Valid byte units => power of 2 that defines the unit's size

array(33) (
    "B" => integer 0
    "K" => integer 10
    "Ki" => integer 10
    "KB" => integer 10
    "KiB" => integer 10
    "M" => integer 20
    "Mi" => integer 20
    "MB" => integer 20
    "MiB" => integer 20
    "G" => integer 30
    "Gi" => integer 30
    "GB" => integer 30
    "GiB" => integer 30
    "T" => integer 40
    "Ti" => integer 40
    "TB" => integer 40
    "TiB" => integer 40
    "P" => integer 50
    "Pi" => integer 50
    "PB" => integer 50
    "PiB" => integer 50
    "E" => integer 60
    "Ei" => integer 60
    "EB" => integer 60
    "EiB" => integer 60
    "Z" => integer 70
    "Zi" => integer 70
    "ZB" => integer 70
    "ZiB" => integer 70
    "Y" => integer 80
    "Yi" => integer 80
    "YB" => integer 80
    "YiB" => integer 80
)

Methods

public static bytes( string $size ) (defined in Kohana_Num)

Converts a file size number to a byte value. File sizes are defined in the format: SB, where S is the size (1, 8.5, 300, etc.) and B is the byte unit (K, MiB, GB, etc.). All valid byte units are defined in Num::$byte_units

echo Num::bytes('200K');  // 204800
echo Num::bytes('5MiB');  // 5242880
echo Num::bytes('1000');  // 1000
echo Num::bytes('2.5GB'); // 2684354560

Parameters

  • string $size required - $bytes file size in SB format

Return Values

  • float

Source Code

public static function bytes($size)
{
	// Prepare the size
	$size = trim( (string) $size);

	// Construct an OR list of byte units for the regex
	$accepted = implode('|', array_keys(Num::$byte_units));

	// Construct the regex pattern for verifying the size format
	$pattern = '/^([0-9]+(?:\.[0-9]+)?)('.$accepted.')?$/Di';

	// Verify the size format and store the matching parts
	if ( ! preg_match($pattern, $size, $matches))
		throw new Kohana_Exception('The byte unit size, ":size", is improperly formatted.', array(
			':size' => $size,
		));

	// Find the float value of the size
	$size = (float) $matches[1];

	// Find the actual unit, assume B if no unit specified
	$unit = Arr::get($matches, 2, 'B');

	// Convert the size into bytes
	$bytes = $size * pow(2, Num::$byte_units[$unit]);

	return $bytes;
}

public static format( float $number , integer $places [, boolean $monetary = bool FALSE ] ) (defined in Kohana_Num)

Locale-aware number and monetary formatting.

// In English, "1,200.05"
// In Spanish, "1200,05"
// In Portuguese, "1 200,05"
echo Num::format(1200.05, 2);

// In English, "1,200.05"
// In Spanish, "1.200,05"
// In Portuguese, "1.200.05"
echo Num::format(1200.05, 2, TRUE);

Parameters

  • float $number required - Number to format
  • integer $places required - Decimal places
  • boolean $monetary = bool FALSE - Monetary formatting?

Tags

  • Since - 3.0.2

Return Values

  • string

Source Code

public static function format($number, $places, $monetary = FALSE)
{
	$info = localeconv();

	if ($monetary)
	{
		$decimal   = $info['mon_decimal_point'];
		$thousands = $info['mon_thousands_sep'];
	}
	else
	{
		$decimal   = $info['decimal_point'];
		$thousands = $info['thousands_sep'];
	}

	return number_format($number, $places, $decimal, $thousands);
}

public static ordinal( integer $number ) (defined in Kohana_Num)

Returns the English ordinal suffix (th, st, nd, etc) of a number.

echo 2, Num::ordinal(2);   // "2nd"
echo 10, Num::ordinal(10); // "10th"
echo 33, Num::ordinal(33); // "33rd"

Parameters

  • integer $number required - $number

Return Values

  • string

Source Code

public static function ordinal($number)
{
	if ($number % 100 > 10 AND $number % 100 < 14)
	{
		return 'th';
	}

	switch ($number % 10)
	{
		case 1:
			return 'st';
		case 2:
			return 'nd';
		case 3:
			return 'rd';
		default:
			return 'th';
	}
}

public static round( float $value [, integer $precision = integer 0 , integer $mode = integer 1 , boolean $native = bool TRUE ] ) (defined in Kohana_Num)

Round a number to a specified precision, using a specified tie breaking technique

Parameters

  • float $value required - Number to round
  • integer $precision = integer 0 - Desired precision
  • integer $mode = integer 1 - Tie breaking mode, accepts the PHP_ROUND_HALF_* constants
  • boolean $native = bool TRUE - Set to false to force use of the userland implementation

Return Values

  • float - Rounded number

Source Code

public static function round($value, $precision = 0, $mode = self::ROUND_HALF_UP, $native = TRUE)
{
	if (version_compare(PHP_VERSION, '5.3', '>=') AND $native)
	{
		return round($value, $precision, $mode);
	}

	if ($mode === self::ROUND_HALF_UP)
	{
		return round($value, $precision);
	}
	else
	{
		$factor = ($precision === 0) ? 1 : pow(10, $precision);

		switch ($mode)
		{
			case self::ROUND_HALF_DOWN:
			case self::ROUND_HALF_EVEN:
			case self::ROUND_HALF_ODD:
				// Check if we have a rounding tie, otherwise we can just call round()
				if (($value * $factor) - floor($value * $factor) === 0.5)
				{
					if ($mode === self::ROUND_HALF_DOWN)
					{
						// Round down operation, so we round down unless the value
						// is -ve because up is down and down is up down there. ;)
						$up = ($value < 0);
					}
					else
					{
						// Round up if the integer is odd and the round mode is set to even
						// or the integer is even and the round mode is set to odd.
						// Any other instance round down.
						$up = ( ! ( ! (floor($value * $factor) & 1)) === ($mode === self::ROUND_HALF_EVEN));
					}

					if ($up)
					{
						$value = ceil($value * $factor);
					}
					else
					{
						$value = floor($value * $factor);
					}
					return $value / $factor;
				}
				else
				{
					return round($value, $precision);
				}
			break;
		}
	}
}