vendor/rails/actionpack/lib/action_view/helpers/number_helper.rb

   1 module ActionView
   2   module Helpers #:nodoc:
   3     # Provides methods for converting numbers into formatted strings.
   4     # Methods are provided for phone numbers, currency, percentage,
   5     # precision, positional notation, and file size.
   6     module NumberHelper
   7       # Formats a +number+ into a US phone number (e.g., (555) 123-9876). You can customize the format
   8       # in the +options+ hash.
   9       #
  10       # ==== Options
  11       # * <tt>:area_code</tt>  - Adds parentheses around the area code.
  12       # * <tt>:delimiter</tt>  - Specifies the delimiter to use (defaults to "-").
  13       # * <tt>:extension</tt>  - Specifies an extension to add to the end of the
  14       #   generated number.
  15       # * <tt>:country_code</tt>  - Sets the country code for the phone number.
  16       #
  17       # ==== Examples
  18       #  number_to_phone(5551234)                                           # => 555-1234
  19       #  number_to_phone(1235551234)                                        # => 123-555-1234
  20       #  number_to_phone(1235551234, :area_code => true)                    # => (123) 555-1234
  21       #  number_to_phone(1235551234, :delimiter => " ")                     # => 123 555 1234
  22       #  number_to_phone(1235551234, :area_code => true, :extension => 555) # => (123) 555-1234 x 555
  23       #  number_to_phone(1235551234, :country_code => 1)                    # => +1-123-555-1234
  24       #
  25       #  number_to_phone(1235551234, :country_code => 1, :extension => 1343, :delimiter => ".")
  26       #  => +1.123.555.1234 x 1343
  27       def number_to_phone(number, options = {})
  28         number       = number.to_s.strip unless number.nil?
  29         options      = options.symbolize_keys
  30         area_code    = options[:area_code] || nil
  31         delimiter    = options[:delimiter] || "-"
  32         extension    = options[:extension].to_s.strip || nil
  33         country_code = options[:country_code] || nil
  34
  35         begin
  36           str = ""
  37           str << "+#{country_code}#{delimiter}" unless country_code.blank?
  38           str << if area_code
  39             number.gsub!(/([0-9]{1,3})([0-9]{3})([0-9]{4}$)/,"(\\1) \\2#{delimiter}\\3")
  40           else
  41             number.gsub!(/([0-9]{0,3})([0-9]{3})([0-9]{4})$/,"\\1#{delimiter}\\2#{delimiter}\\3")
  42             number.starts_with?('-') ? number.slice!(1..-1) : number
  43           end
  44           str << " x #{extension}" unless extension.blank?
  45           str
  46         rescue
  47           number
  48         end
  49       end
  50
  51       # Formats a +number+ into a currency string (e.g., $13.65). You can customize the format
  52       # in the +options+ hash.
  53       #
  54       # ==== Options
  55       # * <tt>:precision</tt>  -  Sets the level of precision (defaults to 2).
  56       # * <tt>:unit</tt>       - Sets the denomination of the currency (defaults to "$").
  57       # * <tt>:separator</tt>  - Sets the separator between the units (defaults to ".").
  58       # * <tt>:delimiter</tt>  - Sets the thousands delimiter (defaults to ",").
  59       # * <tt>:format</tt>     - Sets the format of the output string (defaults to "%u%n"). The field types are:
  60       #
  61       #     %u  The currency unit
  62       #     %n  The number
  63       #
  64       # ==== Examples
  65       #  number_to_currency(1234567890.50)                    # => $1,234,567,890.50
  66       #  number_to_currency(1234567890.506)                   # => $1,234,567,890.51
  67       #  number_to_currency(1234567890.506, :precision => 3)  # => $1,234,567,890.506
  68       #
  69       #  number_to_currency(1234567890.50, :unit => "&pound;", :separator => ",", :delimiter => "")
  70       #  # => &pound;1234567890,50
  71       #  number_to_currency(1234567890.50, :unit => "&pound;", :separator => ",", :delimiter => "", :format => "%n %u")
  72       #  # => 1234567890,50 &pound;
  73       def number_to_currency(number, options = {})
  74         options.symbolize_keys!
  75
  76         defaults  = I18n.translate(:'number.format', :locale => options[:locale], :raise => true) rescue {}
  77         currency  = I18n.translate(:'number.currency.format', :locale => options[:locale], :raise => true) rescue {}
  78         defaults  = defaults.merge(currency)
  79
  80         precision = options[:precision] || defaults[:precision]
  81         unit      = options[:unit]      || defaults[:unit]
  82         separator = options[:separator] || defaults[:separator]
  83         delimiter = options[:delimiter] || defaults[:delimiter]
  84         format    = options[:format]    || defaults[:format]
  85         separator = '' if precision == 0
  86
  87         begin
  88           format.gsub(/%n/, number_with_precision(number,
  89             :precision => precision,
  90             :delimiter => delimiter,
  91             :separator => separator)
  92           ).gsub(/%u/, unit)
  93         rescue
  94           number
  95         end
  96       end
  97
  98       # Formats a +number+ as a percentage string (e.g., 65%). You can customize the
  99       # format in the +options+ hash.
 100       #
 101       # ==== Options
 102       # * <tt>:precision</tt>  - Sets the level of precision (defaults to 3).
 103       # * <tt>:separator</tt>  - Sets the separator between the units (defaults to ".").
 104       # * <tt>:delimiter</tt>  - Sets the thousands delimiter (defaults to "").
 105       #
 106       # ==== Examples
 107       #  number_to_percentage(100)                                        # => 100.000%
 108       #  number_to_percentage(100, :precision => 0)                       # => 100%
 109       #  number_to_percentage(1000, :delimiter => '.', :separator => ',') # => 1.000,000%
 110       #  number_to_percentage(302.24398923423, :precision => 5)           # => 302.24399%
 111       def number_to_percentage(number, options = {})
 112         options.symbolize_keys!
 113
 114         defaults   = I18n.translate(:'number.format', :locale => options[:locale], :raise => true) rescue {}
 115         percentage = I18n.translate(:'number.percentage.format', :locale => options[:locale], :raise => true) rescue {}
 116         defaults  = defaults.merge(percentage)
 117
 118         precision = options[:precision] || defaults[:precision]
 119         separator = options[:separator] || defaults[:separator]
 120         delimiter = options[:delimiter] || defaults[:delimiter]
 121
 122         begin
 123           number_with_precision(number,
 124             :precision => precision,
 125             :separator => separator,
 126             :delimiter => delimiter) + "%"
 127         rescue
 128           number
 129         end
 130       end
 131
 132       # Formats a +number+ with grouped thousands using +delimiter+ (e.g., 12,324). You can
 133       # customize the format in the +options+ hash.
 134       #
 135       # ==== Options
 136       # * <tt>:delimiter</tt>  - Sets the thousands delimiter (defaults to ",").
 137       # * <tt>:separator</tt>  - Sets the separator between the units (defaults to ".").
 138       #
 139       # ==== Examples
 140       #  number_with_delimiter(12345678)                        # => 12,345,678
 141       #  number_with_delimiter(12345678.05)                     # => 12,345,678.05
 142       #  number_with_delimiter(12345678, :delimiter => ".")     # => 12.345.678
 143       #  number_with_delimiter(12345678, :seperator => ",")     # => 12,345,678
 144       #  number_with_delimiter(98765432.98, :delimiter => " ", :separator => ",")
 145       #  # => 98 765 432,98
 146       #
 147       # You can still use <tt>number_with_delimiter</tt> with the old API that accepts the
 148       # +delimiter+ as its optional second and the +separator+ as its
 149       # optional third parameter:
 150       #  number_with_delimiter(12345678, " ")                     # => 12 345.678
 151       #  number_with_delimiter(12345678.05, ".", ",")             # => 12.345.678,05
 152       def number_with_delimiter(number, *args)
 153         options = args.extract_options!
 154         options.symbolize_keys!
 155
 156         defaults = I18n.translate(:'number.format', :locale => options[:locale], :raise => true) rescue {}
 157
 158         unless args.empty?
 159           ActiveSupport::Deprecation.warn('number_with_delimiter takes an option hash ' +
 160             'instead of separate delimiter and precision arguments.', caller)
 161           delimiter = args[0] || defaults[:delimiter]
 162           separator = args[1] || defaults[:separator]
 163         end
 164
 165         delimiter ||= (options[:delimiter] || defaults[:delimiter])
 166         separator ||= (options[:separator] || defaults[:separator])
 167
 168         begin
 169           parts = number.to_s.split('.')
 170           parts[0].gsub!(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1#{delimiter}")
 171           parts.join(separator)
 172         rescue
 173           number
 174         end
 175       end
 176
 177       # Formats a +number+ with the specified level of <tt>:precision</tt> (e.g., 112.32 has a precision of 2).
 178       # You can customize the format in the +options+ hash.
 179       #
 180       # ==== Options
 181       # * <tt>:precision</tt>  - Sets the level of precision (defaults to 3).
 182       # * <tt>:separator</tt>  - Sets the separator between the units (defaults to ".").
 183       # * <tt>:delimiter</tt>  - Sets the thousands delimiter (defaults to "").
 184       #
 185       # ==== Examples
 186       #  number_with_precision(111.2345)                    # => 111.235
 187       #  number_with_precision(111.2345, :precision => 2)   # => 111.23
 188       #  number_with_precision(13, :precision => 5)         # => 13.00000
 189       #  number_with_precision(389.32314, :precision => 0)  # => 389
 190       #  number_with_precision(1111.2345, :precision => 2, :separator => ',', :delimiter => '.')
 191       #  # => 1.111,23
 192       #
 193       # You can still use <tt>number_with_precision</tt> with the old API that accepts the
 194       # +precision+ as its optional second parameter:
 195       #   number_with_precision(number_with_precision(111.2345, 2)   # => 111.23
 196       def number_with_precision(number, *args)
 197         options = args.extract_options!
 198         options.symbolize_keys!
 199
 200         defaults           = I18n.translate(:'number.format', :locale => options[:locale], :raise => true) rescue {}
 201         precision_defaults = I18n.translate(:'number.precision.format', :locale => options[:locale],
 202                                                                         :raise => true) rescue {}
 203         defaults           = defaults.merge(precision_defaults)
 204
 205         unless args.empty?
 206           ActiveSupport::Deprecation.warn('number_with_precision takes an option hash ' +
 207             'instead of a separate precision argument.', caller)
 208           precision = args[0] || defaults[:precision]
 209         end
 210
 211         precision ||= (options[:precision] || defaults[:precision])
 212         separator ||= (options[:separator] || defaults[:separator])
 213         delimiter ||= (options[:delimiter] || defaults[:delimiter])
 214
 215         begin
 216           rounded_number = (Float(number) * (10 ** precision)).round.to_f / 10 ** precision
 217           number_with_delimiter("%01.#{precision}f" % rounded_number,
 218             :separator => separator,
 219             :delimiter => delimiter)
 220         rescue
 221           number
 222         end
 223       end
 224
 225       STORAGE_UNITS = [:byte, :kb, :mb, :gb, :tb].freeze
 226
 227       # Formats the bytes in +size+ into a more understandable representation
 228       # (e.g., giving it 1500 yields 1.5 KB). This method is useful for
 229       # reporting file sizes to users. This method returns nil if
 230       # +size+ cannot be converted into a number. You can customize the
 231       # format in the +options+ hash.
 232       #
 233       # ==== Options
 234       # * <tt>:precision</tt>  - Sets the level of precision (defaults to 1).
 235       # * <tt>:separator</tt>  - Sets the separator between the units (defaults to ".").
 236       # * <tt>:delimiter</tt>  - Sets the thousands delimiter (defaults to "").
 237       #
 238       # ==== Examples
 239       #  number_to_human_size(123)                                          # => 123 Bytes
 240       #  number_to_human_size(1234)                                         # => 1.2 KB
 241       #  number_to_human_size(12345)                                        # => 12.1 KB
 242       #  number_to_human_size(1234567)                                      # => 1.2 MB
 243       #  number_to_human_size(1234567890)                                   # => 1.1 GB
 244       #  number_to_human_size(1234567890123)                                # => 1.1 TB
 245       #  number_to_human_size(1234567, :precision => 2)                     # => 1.18 MB
 246       #  number_to_human_size(483989, :precision => 0)                      # => 473 KB
 247       #  number_to_human_size(1234567, :precision => 2, :separator => ',')  # => 1,18 MB
 248       #
 249       # You can still use <tt>number_to_human_size</tt> with the old API that accepts the
 250       # +precision+ as its optional second parameter:
 251       #  number_to_human_size(1234567, 2)    # => 1.18 MB
 252       #  number_to_human_size(483989, 0)     # => 473 KB
 253       def number_to_human_size(number, *args)
 254         return nil if number.nil?
 255
 256         options = args.extract_options!
 257         options.symbolize_keys!
 258
 259         defaults = I18n.translate(:'number.format', :locale => options[:locale], :raise => true) rescue {}
 260         human    = I18n.translate(:'number.human.format', :locale => options[:locale], :raise => true) rescue {}
 261         defaults = defaults.merge(human)
 262
 263         unless args.empty?
 264           ActiveSupport::Deprecation.warn('number_to_human_size takes an option hash ' +
 265             'instead of a separate precision argument.', caller)
 266           precision = args[0] || defaults[:precision]
 267         end
 268
 269         precision ||= (options[:precision] || defaults[:precision])
 270         separator ||= (options[:separator] || defaults[:separator])
 271         delimiter ||= (options[:delimiter] || defaults[:delimiter])
 272
 273         storage_units_format = I18n.translate(:'number.human.storage_units.format', :locale => options[:locale], :raise => true)
 274
 275         if number.to_i < 1024
 276           unit = I18n.translate(:'number.human.storage_units.units.byte', :locale => options[:locale], :count => number.to_i, :raise => true)
 277           storage_units_format.gsub(/%n/, number.to_i.to_s).gsub(/%u/, unit)
 278         else
 279           max_exp  = STORAGE_UNITS.size - 1
 280           number   = Float(number)
 281           exponent = (Math.log(number) / Math.log(1024)).to_i # Convert to base 1024
 282           exponent = max_exp if exponent > max_exp # we need this to avoid overflow for the highest unit
 283           number  /= 1024 ** exponent
 284
 285           unit_key = STORAGE_UNITS[exponent]
 286           unit = I18n.translate(:"number.human.storage_units.units.#{unit_key}", :locale => options[:locale], :count => number, :raise => true)
 287
 288           begin
 289             escaped_separator = Regexp.escape(separator)
 290             formatted_number = number_with_precision(number,
 291               :precision => precision,
 292               :separator => separator,
 293               :delimiter => delimiter
 294             ).sub(/(\d)(#{escaped_separator}[1-9]*)?0+\z/, '\1\2').sub(/#{escaped_separator}\z/, '')
 295             storage_units_format.gsub(/%n/, formatted_number).gsub(/%u/, unit)
 296           rescue
 297             number
 298           end
 299         end
 300       end
 301     end
 302   end
 303 end