class ByteSize
This class is used to represent a size in bytes.
It uses the SI standard unit symbols: kB, MB, GB, TB, PB, EB, ZB, YB.
For a version that uses the IEC standard unit symbols, see {IECByteSize}[IECByteSize.html].
Examples of use¶ ↑
ByteSize.new( 4127 ) #=> (4.13 kB) ByteSize.new( "22 GB" ) #=> (22 GB) ByteSize.new( "22 GiB" ) #=> (23.62 GB) ByteSize.bytes( 42 ) #=> (42 bytes) ByteSize.kb( 42 ) #=> (42 kB) ByteSize.mb( 42 ) #=> (42 MB) ByteSize.gb( 42 ) #=> (42 GB) ByteSize.tb( 42 ) #=> (42 TB) ByteSize.pb( 42 ) #=> (42 PB) ByteSize.eb( 42 ) #=> (42 EB) ByteSize.zb( 42 ) #=> (42 ZB) ByteSize.yb( 42 ) #=> (42 YB)
Conversion of values:¶ ↑
ByteSize.gb( 100 ).to_gib #=> 93.13225746154785 ByteSize.gib( 2.42 ).to_mib #=> 2478.079999923706
With numeric convenience methods:¶ ↑
require 'bytesize/unit' 100.gb.to_gib #=> 93.13225746154785 2.42.gib.to_mib #=> 2478.079999923706
Constants
- ALL_UNIT_SYMBOLS
- BASE
- ORDERS_OF_MAGNITUDE
- UNIT_SYMBOLS
- VERSION
Public Class Methods
Returns a new instance of ByteSize representing n bytes.
# File lib/bytesize.rb, line 152 def self.bytes( b ) raise( TypeError, "expected #{Numeric}, got #{b.class}" ) unless b.is_a?(Numeric) self.new( b.round ) end
Returns a new instance of ByteSize representing n exabytes.
# File lib/bytesize.rb, line 215
Returns a new instance of ByteSize representing n exbibytes.
# File lib/bytesize.rb, line 295
Returns a new instance of ByteSize representing n gigabytes.
# File lib/bytesize.rb, line 185
Returns a new instance of ByteSize representing n gibibytes.
# File lib/bytesize.rb, line 265
Returns a new instance of ByteSize representing n kilobytes.
# File lib/bytesize.rb, line 165
Returns a new instance of ByteSize representing n kibibytes.
# File lib/bytesize.rb, line 245
Returns a new instance of ByteSize representing n megabytes.
# File lib/bytesize.rb, line 175
Returns a new instance of ByteSize representing n mebibytes.
# File lib/bytesize.rb, line 255
Parses a String into either a ByteSize or IECByteSize depending on it's unit symbol.
# File lib/bytesize.rb, line 326 def self.parse( val ) if val.is_a?(String) if m = val.match(BYTES_REGEX) ByteSize.new( m[1].to_i ) elsif m = val.match(SI_REGEX) ByteSize.send( m[3].downcase.to_sym, m[2].nil? ? m[1].to_i : m[1].to_f ) elsif m = val.match(IEC_REGEX) IECByteSize.send( m[3].downcase.to_sym, m[2].nil? ? m[1].to_i : m[1].to_f ) else raise( ArgumentError, "invalid #{ByteSize} or #{IECByteSize} string: #{val.inspect}" ) end else raise( TypeError, "expected #{String}, got #{val.class}" ) end end
Returns a new instance of ByteSize representing n petabytes.
# File lib/bytesize.rb, line 205
Returns a new instance of ByteSize representing n pebibytes.
# File lib/bytesize.rb, line 285
Returns a new instance of ByteSize representing n terabytes.
# File lib/bytesize.rb, line 195
Returns a new instance of ByteSize representing n tebibytes.
# File lib/bytesize.rb, line 275
Returns a new instance of ByteSize representing n yottabytes.
# File lib/bytesize.rb, line 235
Returns a new instance of ByteSize representing n yobibytes.
# File lib/bytesize.rb, line 315
Returns a new instance of ByteSize representing n zettabytes.
# File lib/bytesize.rb, line 225
Returns a new instance of ByteSize representing n zebibytes.
# File lib/bytesize.rb, line 305
Public Instance Methods
Performs a modulo operation with val, returning an instance of ByteSize.
val can be another ByteSize or a Numeric.
# File lib/bytesize.rb, line 643 def %( val ) case val when Numeric self.class.new(( bytes % val ).round) when ByteSize self.class.new( bytes % val.bytes ) else raise( TypeError, "#{val.class} can't be coerced into #{self.class}" ) end end
Performs multiplication, returning an instance of ByteSize.
val must be a Numeric. Multiplication with another ByteSize is disallowed because it does not make symantic sense.
# File lib/bytesize.rb, line 668 def *( val ) case val when Numeric self.class.new(( bytes * val ).round) when ByteSize raise( TypeError, "cannot multiply #{ByteSize} with #{val.class}" ) else raise( TypeError, "#{val.class} can't be coerced into #{self.class}" ) end end
Raises bytesize to the power of pow, returning an instance of ByteSize.
pow must be a Numeric. Raising to the power of another ByteSize is disallowed because it does not make symantic sense.
# File lib/bytesize.rb, line 693 def **( pow ) case pow when Numeric self.class.new(( bytes ** pow ).round) when ByteSize raise( TypeError, "cannot raise #{ByteSize} to a power of #{pow.class}" ) else raise( TypeError, "#{pow.class} can't be coerced into #{self.class}" ) end end
Performs addition, returning an instance of ByteSize.
val can be another ByteSize or a Numeric.
# File lib/bytesize.rb, line 717 def +( val ) case val when Numeric self.class.new(( bytes + val ).round) when ByteSize self.class.new( bytes + val.bytes ) else raise( TypeError, "#{val.class} can't be coerced into #{self.class}" ) end end
Unary Plus — Returns the receiver’s value.
# File lib/bytesize.rb, line 739 def +@ self end
Performs subtraction, returning an instance of ByteSize.
val can be another ByteSize or a Numeric.
# File lib/bytesize.rb, line 753 def -( val ) case val when Numeric self.class.new(( bytes - val ).round) when ByteSize self.class.new( bytes - val.bytes ) else raise( TypeError, "#{val.class} can't be coerced into #{self.class}" ) end end
Unary Minus — Returns the receiver’s value, negated.
# File lib/bytesize.rb, line 775 def -@ self.class.new( 0 - bytes ) end
Performs division.
If val is a Numeric it returns an instance of ByteSize. If val is an instance of ByteSize it returns a Float.
# File lib/bytesize.rb, line 792 def /( val ) case val when Numeric self.class.new(( bytes / val ).round) when ByteSize bytes.to_f / val.bytes.to_f else raise( TypeError, "#{val.class} can't be coerced into #{self.class}" ) end end
Returns true
if the value of bytesize is less than that of val.
# File lib/bytesize.rb, line 553 def <( other ) case other when ByteSize bytes < other.bytes when Numeric bytes < other else raise( ArgumentError, "comparison of #{self.class} with #{other.inspect} failed" ) end end
Returns true
if the value of bytesize is less than or equal to that of val.
# File lib/bytesize.rb, line 575 def <=( other ) case other when ByteSize bytes <= other.bytes when Numeric bytes <= other else raise( ArgumentError, "comparison of #{self.class} with #{other.inspect} failed" ) end end
Compares bytesize to other and returns 0
if they are equal, -1
if bytesize is less than other, or 1
if bytesize is greater than other.
Returns nil
if the two values are incomparable.
# File lib/bytesize.rb, line 818 def <=>( other ) case other when Numeric bytes <=> other when ByteSize bytes <=> other.bytes else nil end end
Returns true
if bytesize is equal to other.
If other is not an instance of ByteSize an attempt will be made to convert it to one.
# File lib/bytesize.rb, line 842 def ==( other ) case other when Numeric bytes == other when ByteSize bytes == other.bytes else false end end
Alias for {==}[#method-i-3D-3D].
# File lib/bytesize.rb, line 864
Returns true
if the value of bytesize is greater than that of val.
# File lib/bytesize.rb, line 597 def >( other ) case other when ByteSize bytes > other.bytes when Numeric bytes > other else raise( ArgumentError, "comparison of #{self.class} with #{other.inspect} failed" ) end end
Returns true
if the value of bytesize is greater than or equal to that of val.
# File lib/bytesize.rb, line 619 def >=( other ) case other when ByteSize bytes >= other.bytes when Numeric bytes >= other else raise( ArgumentError, "comparison of #{self.class} with #{other.inspect} failed" ) end end
Returns the number of bytes as an Integer.
# File lib/bytesize.rb, line 878
Returns true
if the ByteSize is equal to other_bytesize.
# File lib/bytesize.rb, line 908 def eql?( other ) other.class == self.class && other.bytes == bytes end
Returns true
if the ByteSize is less than 0
.
# File lib/bytesize.rb, line 944 def negative? bytes < 0 end
Returns true
if the ByteSize is greater than 0
.
# File lib/bytesize.rb, line 956 def positive? bytes > 0 end
Alias for #bytes.
# File lib/bytesize.rb, line 968
Returns a Float representing the equivalent number of exabytes.
# File lib/bytesize.rb, line 443
Returns a Float representing the equivalent number of exbibytes.
# File lib/bytesize.rb, line 523
Returns a Float representing the equivalent number of gigabytes.
# File lib/bytesize.rb, line 413
Returns a Float representing the equivalent number of gibibytes.
# File lib/bytesize.rb, line 493
Returns the number of bytes as an Integer.
# File lib/bytesize.rb, line 982 def to_i bytes.to_i end
Returns the size as an instance of IECByteSize.
If called on an instance of IECByteSize it returns self
.
# File lib/bytesize.rb, line 996 def to_iec self.class == IECByteSize ? self : IECByteSize.new(self.to_i) end
Returns a Float representing the equivalent number of kilobytes.
# File lib/bytesize.rb, line 393
Returns a Float representing the equivalent number of kibibytes.
# File lib/bytesize.rb, line 473
Returns a Float representing the equivalent number of megabytes.
# File lib/bytesize.rb, line 403
Returns a Float representing the equivalent number of mebibytes.
# File lib/bytesize.rb, line 483
Returns a Float representing the equivalent number of petabytes.
# File lib/bytesize.rb, line 433
Returns a Float representing the equivalent number of pebibytes.
# File lib/bytesize.rb, line 513
Format this ByteSize as a String.
The second form formats it with exactly decimal_places decimal places.
Example:¶ ↑
ByteSize.bytes(3000000000000).to_s #=> "3 TB" ByteSize.bytes(2460000000000).to_s #=> "2.46 TB" ByteSize.bytes(3000000000000).to_s(2) #=> "3.00 TB" ByteSize.bytes(1234567890000).to_s(2) #=> "1.23 TB" ByteSize.bytes(1234567890000).to_s(4) #=> "1.2346 TB"
# File lib/bytesize.rb, line 1020 def to_s( decimal_places=nil ) unless decimal_places.nil? raise( TypeError, "expected #{Integer}, got #{decimal_places.class}" ) unless decimal_places.is_a?(Integer) raise( RangeError, "decimal places cannot be negative" ) unless decimal_places >= 0 end b = bytes.abs scale = self.class::ORDERS_OF_MAGNITUDE.sort{|(ak,av),(bk,bv)| av <=> bv } if b == 0 unit = scale.first else unit = scale.find_index{|k,v| v > b } if unit.nil? unit = scale.last else unit = scale[unit-1] end end if decimal_places.nil? sprintf( negative? ? '-%g %s' : '%g %s', ((b/Float(unit.last))*100).round/100.0, unit.first.to_s ) else sprintf( negative? ? "-%.0#{decimal_places}f %s" : "%.0#{decimal_places}f %s", b / Float(unit.last), unit.first.to_s ) end end
Returns a Float representing the equivalent number of terabytes.
# File lib/bytesize.rb, line 423
Returns a Float representing the equivalent number of tebibytes.
# File lib/bytesize.rb, line 503
Returns a Float representing the equivalent number of yottabytes.
# File lib/bytesize.rb, line 463
Returns a Float representing the equivalent number of yobibytes.
# File lib/bytesize.rb, line 543
Returns a Float representing the equivalent number of zettabytes.
# File lib/bytesize.rb, line 453
Returns a Float representing the equivalent number of zebibytes.
# File lib/bytesize.rb, line 533
Returns true
if the ByteSize has a zero value.
# File lib/bytesize.rb, line 1070 def zero? bytes == 0 end