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

bytes( n ) → bytesize click to toggle source

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
eb( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n exabytes.

# File lib/bytesize.rb, line 215
        
eib( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n exbibytes.

# File lib/bytesize.rb, line 295
        
gb( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n gigabytes.

# File lib/bytesize.rb, line 185
        
gib( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n gibibytes.

# File lib/bytesize.rb, line 265
        
kb( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n kilobytes.

# File lib/bytesize.rb, line 165
        
kib( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n kibibytes.

# File lib/bytesize.rb, line 245
        
mb( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n megabytes.

# File lib/bytesize.rb, line 175
        
mib( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n mebibytes.

# File lib/bytesize.rb, line 255
        
new( integer ) click to toggle source
new( string )

Create a new instance of ByteSize from an Integer or String.

# File lib/bytesize.rb, line 381
def initialize( bytes )
        @bytes = bytes
end
parse( string ) → bytesize click to toggle source

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
pb( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n petabytes.

# File lib/bytesize.rb, line 205
        
pib( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n pebibytes.

# File lib/bytesize.rb, line 285
        
tb( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n terabytes.

# File lib/bytesize.rb, line 195
        
tib( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n tebibytes.

# File lib/bytesize.rb, line 275
        
yb( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n yottabytes.

# File lib/bytesize.rb, line 235
        
yib( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n yobibytes.

# File lib/bytesize.rb, line 315
        
zb( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n zettabytes.

# File lib/bytesize.rb, line 225
        
zib( n ) → bytesize click to toggle source

Returns a new instance of ByteSize representing n zebibytes.

# File lib/bytesize.rb, line 305
        

Public Instance Methods

bytesize % val → bytesize click to toggle source

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
bytesize * val → bytesize click to toggle source

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
bytesize ** pow → bytesize click to toggle source

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
bytesize + val → bytesize click to toggle source

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
+bytesize → bytesize click to toggle source

Unary Plus — Returns the receiver’s value.

# File lib/bytesize.rb, line 739
def +@
        self
end
bytesize - val → bytesize click to toggle source

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
-bytesize → bytesize click to toggle source

Unary Minus — Returns the receiver’s value, negated.

# File lib/bytesize.rb, line 775
def -@
        self.class.new( 0 - bytes )
end
bytesize / val → bytesize or float click to toggle source

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
bytesize < val → true or false click to toggle source

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
bytesize <= val → true or false click to toggle source

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
bytesize <=> other → -1, 0, 1, or nil click to toggle source

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
bytesize == other → true or false click to toggle source

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
bytesize === other → true or false click to toggle source

Alias for {==}[#method-i-3D-3D].

# File lib/bytesize.rb, line 864
        
bytesize > val → true or false click to toggle source

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
bytesize >= val → true or false click to toggle source

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
bytes → integer click to toggle source

Returns the number of bytes as an Integer.

# File lib/bytesize.rb, line 878
        
eql?( other_bytesize ) → true or false click to toggle source

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
inspect → string click to toggle source

Return a String describing this object.

Example:
ByteSize.bytes(3000000000000)  #=> (3 TB)
# File lib/bytesize.rb, line 932
def inspect
        sprintf( '(%s)', to_s )
end
negative? → true or false click to toggle source

Returns true if the ByteSize is less than 0.

# File lib/bytesize.rb, line 944
def negative?
        bytes < 0
end
positive? → true or false click to toggle source

Returns true if the ByteSize is greater than 0.

# File lib/bytesize.rb, line 956
def positive?
        bytes > 0
end
to_bytes → integer click to toggle source

Alias for #bytes.

# File lib/bytesize.rb, line 968
        
to_eb → float click to toggle source

Returns a Float representing the equivalent number of exabytes.

# File lib/bytesize.rb, line 443
        
to_eib → float click to toggle source

Returns a Float representing the equivalent number of exbibytes.

# File lib/bytesize.rb, line 523
        
to_gb → float click to toggle source

Returns a Float representing the equivalent number of gigabytes.

# File lib/bytesize.rb, line 413
        
to_gib → float click to toggle source

Returns a Float representing the equivalent number of gibibytes.

# File lib/bytesize.rb, line 493
        
to_i → integer click to toggle source

Returns the number of bytes as an Integer.

# File lib/bytesize.rb, line 982
def to_i
        bytes.to_i
end
to_iec → iecbytesize click to toggle source

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
to_kb → float click to toggle source

Returns a Float representing the equivalent number of kilobytes.

# File lib/bytesize.rb, line 393
        
to_kib → float click to toggle source

Returns a Float representing the equivalent number of kibibytes.

# File lib/bytesize.rb, line 473
        
to_mb → float click to toggle source

Returns a Float representing the equivalent number of megabytes.

# File lib/bytesize.rb, line 403
        
to_mib → float click to toggle source

Returns a Float representing the equivalent number of mebibytes.

# File lib/bytesize.rb, line 483
        
to_pb → float click to toggle source

Returns a Float representing the equivalent number of petabytes.

# File lib/bytesize.rb, line 433
        
to_pib → float click to toggle source

Returns a Float representing the equivalent number of pebibytes.

# File lib/bytesize.rb, line 513
        
to_s → string click to toggle source
to_s( decimal_places ) → string

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
to_si → bytesize click to toggle source

Returns the size as an instance of ByteSize.

If called on an instance of ByteSize it returns self.

# File lib/bytesize.rb, line 1058
def to_si
        self.class == ByteSize ? self : ByteSize.new(self.to_i)
end
to_tb → float click to toggle source

Returns a Float representing the equivalent number of terabytes.

# File lib/bytesize.rb, line 423
        
to_tib → float click to toggle source

Returns a Float representing the equivalent number of tebibytes.

# File lib/bytesize.rb, line 503
        
to_yb → float click to toggle source

Returns a Float representing the equivalent number of yottabytes.

# File lib/bytesize.rb, line 463
        
to_yib → float click to toggle source

Returns a Float representing the equivalent number of yobibytes.

# File lib/bytesize.rb, line 543
        
to_zb → float click to toggle source

Returns a Float representing the equivalent number of zettabytes.

# File lib/bytesize.rb, line 453
        
to_zib → float click to toggle source

Returns a Float representing the equivalent number of zebibytes.

# File lib/bytesize.rb, line 533
        
zero? → true or false click to toggle source

Returns true if the ByteSize has a zero value.

# File lib/bytesize.rb, line 1070
def zero?
        bytes == 0
end