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

   1 module ActionView
   2   module Helpers #:nodoc:
   3     # Provides methods for converting a 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(1235551234)                                        # => 123-555-1234
  19       #  number_to_phone(1235551234, :area_code => true)                    # => (123) 555-1234
  20       #  number_to_phone(1235551234, :delimiter => " ")                     # => 123 555 1234
  21       #  number_to_phone(1235551234, :area_code => true, :extension => 555) # => (123) 555-1234 x 555
  22       #  number_to_phone(1235551234, :country_code => 1)                    # => +1-123-555-1234
  23       #
  24       #  number_to_phone(1235551234, :country_code => 1, :extension => 1343, :delimeter => ".")
  25       #  => +1.123.555.1234 x 1343
  26       def number_to_phone(number, options = {})
  27         number       = number.to_s.strip unless number.nil?
  28         options      = options.stringify_keys
  29         area_code    = options["area_code"] || nil
  30         delimiter    = options["delimiter"] || "-"
  31         extension    = options["extension"].to_s.strip || nil
  32         country_code = options["country_code"] || nil
  33
  34         begin
  35           str = ""
  36           str << "+#{country_code}#{delimiter}" unless country_code.blank?
  37           str << if area_code
  38             number.gsub!(/([0-9]{1,3})([0-9]{3})([0-9]{4}$)/,"(\\1) \\2#{delimiter}\\3")
  39           else
  40             number.gsub!(/([0-9]{1,3})([0-9]{3})([0-9]{4})$/,"\\1#{delimiter}\\2#{delimiter}\\3")
  41           end
  42           str << " x #{extension}" unless extension.blank?
  43           str
  44         rescue
  45           number
  46         end
  47       end
  48
  49       # Formats a +number+ into a currency string (e.g., $13.65). You can customize the format
  50       # in the +options+ hash.
  51       #
  52       # ==== Options
  53       # * <tt>:precision</tt>  -  Sets the level of precision (defaults to 2).
  54       # * <tt>:unit</tt>  - Sets the denomination of the currency (defaults to "$").
  55       # * <tt>:separator</tt>  - Sets the separator between the units (defaults to ".").
  56       # * <tt>:delimiter</tt>  - Sets the thousands delimiter (defaults to ",").
  57       #
  58       # ==== Examples
  59       #  number_to_currency(1234567890.50)                    # => $1,234,567,890.50
  60       #  number_to_currency(1234567890.506)                   # => $1,234,567,890.51
  61       #  number_to_currency(1234567890.506, :precision => 3)  # => $1,234,567,890.506
  62       #
  63       #  number_to_currency(1234567890.50, :unit => "&pound;", :separator => ",", :delimiter => "")
  64       #  # => &pound;1234567890,50
  65       def number_to_currency(number, options = {})
  66         options   = options.stringify_keys
  67         precision = options["precision"] || 2
  68         unit      = options["unit"] || "$"
  69         separator = precision > 0 ? options["separator"] || "." : ""
  70         delimiter = options["delimiter"] || ","
  71
  72         begin
  73           parts = number_with_precision(number, precision).split('.')
  74           unit + number_with_delimiter(parts[0], delimiter) + separator + parts[1].to_s
  75         rescue
  76           number
  77         end
  78       end
  79
  80       # Formats a +number+ as a percentage string (e.g., 65%). You can customize the
  81       # format in the +options+ hash.
  82       #
  83       # ==== Options
  84       # * <tt>:precision</tt>  - Sets the level of precision (defaults to 3).
  85       # * <tt>:separator</tt>  - Sets the separator between the units (defaults to ".").
  86       #
  87       # ==== Examples
  88       #  number_to_percentage(100)                         # => 100.000%
  89       #  number_to_percentage(100, :precision => 0)        # => 100%
  90       #
  91       #  number_to_percentage(302.24398923423, :precision => 5)
  92       #  # => 302.24399%
  93       def number_to_percentage(number, options = {})
  94         options   = options.stringify_keys
  95         precision = options["precision"] || 3
  96         separator = options["separator"] || "."
  97
  98         begin
  99           number = number_with_precision(number, precision)
 100           parts = number.split('.')
 101           if parts.at(1).nil?
 102             parts[0] + "%"
 103           else
 104             parts[0] + separator + parts[1].to_s + "%"
 105           end
 106         rescue
 107           number
 108         end
 109       end
 110
 111       # Formats a +number+ with grouped thousands using +delimiter+ (e.g., 12,324). You
 112       # can customize the format using optional <em>delimiter</em> and <em>separator</em> parameters.
 113       #
 114       # ==== Options
 115       # * <tt>delimiter</tt>  - Sets the thousands delimiter (defaults to ",").
 116       # * <tt>separator</tt>  - Sets the separator between the units (defaults to ".").
 117       #
 118       # ==== Examples
 119       #  number_with_delimiter(12345678)       # => 12,345,678
 120       #  number_with_delimiter(12345678.05)    # => 12,345,678.05
 121       #  number_with_delimiter(12345678, ".")  # => 12.345.678
 122       #
 123       #  number_with_delimiter(98765432.98, " ", ",")
 124       #  # => 98 765 432,98
 125       def number_with_delimiter(number, delimiter=",", separator=".")
 126         begin
 127           parts = number.to_s.split('.')
 128           parts[0].gsub!(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1#{delimiter}")
 129           parts.join separator
 130         rescue
 131           number
 132         end
 133       end
 134
 135       # Formats a +number+ with the specified level of +precision+ (e.g., 112.32 has a precision of 2). The default
 136       # level of precision is 3.
 137       #
 138       # ==== Examples
 139       #  number_with_precision(111.2345)     # => 111.235
 140       #  number_with_precision(111.2345, 2)  # => 111.24
 141       #  number_with_precision(13, 5)        # => 13.00000
 142       #  number_with_precision(389.32314, 0) # => 389
 143       def number_with_precision(number, precision=3)
 144         "%01.#{precision}f" % number
 145       rescue
 146         number
 147       end
 148
 149       # Formats the bytes in +size+ into a more understandable representation
 150       # (e.g., giving it 1500 yields 1.5 KB). This method is useful for
 151       # reporting file sizes to users. This method returns nil if
 152       # +size+ cannot be converted into a number. You can change the default
 153       # precision of 1 using the precision parameter +precision+.
 154       #
 155       # ==== Examples
 156       #  number_to_human_size(123)           # => 123 Bytes
 157       #  number_to_human_size(1234)          # => 1.2 KB
 158       #  number_to_human_size(12345)         # => 12.1 KB
 159       #  number_to_human_size(1234567)       # => 1.2 MB
 160       #  number_to_human_size(1234567890)    # => 1.1 GB
 161       #  number_to_human_size(1234567890123) # => 1.1 TB
 162       #  number_to_human_size(1234567, 2)    # => 1.18 MB
 163       #  number_to_human_size(483989, 0)     # => 4 MB
 164       def number_to_human_size(size, precision=1)
 165         size = Kernel.Float(size)
 166         case
 167           when size.to_i == 1;    "1 Byte"
 168           when size < 1.kilobyte; "%d Bytes" % size
 169           when size < 1.megabyte; "%.#{precision}f KB"  % (size / 1.0.kilobyte)
 170           when size < 1.gigabyte; "%.#{precision}f MB"  % (size / 1.0.megabyte)
 171           when size < 1.terabyte; "%.#{precision}f GB"  % (size / 1.0.gigabyte)
 172           else                    "%.#{precision}f TB"  % (size / 1.0.terabyte)
 173         end.sub(/([0-9])\.?0+ /, '\1 ' )
 174       rescue
 175         nil
 176       end
 177     end
 178   end
 179 end