philiprehberger-human_size
Bidirectional byte size formatting with SI and binary units
Requirements
- Ruby >= 3.1
Installation
Add to your Gemfile:
gem "philiprehberger-human_size"Or install directly:
gem install philiprehberger-human_sizeUsage
require "philiprehberger/human_size"
Philiprehberger::HumanSize.format(1_500_000) # => "1.5 MB"Formatting Bytes
Convert integer bytes to human-readable strings using SI units (base 1000) by default:
Philiprehberger::HumanSize.format(1_500_000) # => "1.5 MB"
Philiprehberger::HumanSize.format(1_000_000_000) # => "1 GB"
Philiprehberger::HumanSize.format(0) # => "0 B"Binary Units
Pass binary: true to use IEC binary units (base 1024) instead of SI:
Philiprehberger::HumanSize.format(1_572_864, binary: true) # => "1.5 MiB"
Philiprehberger::HumanSize.format(1_048_576, binary: true) # => "1 MiB"
Philiprehberger::HumanSize.format(5_368_709_120, binary: true) # => "5 GiB"Precision Control
Use the precision option to control the number of decimal places (default is 2). Trailing zeros are stripped automatically:
Philiprehberger::HumanSize.format(1_500_000, precision: 0) # => "2 MB"
Philiprehberger::HumanSize.format(1_234_567, precision: 3) # => "1.235 MB"
Philiprehberger::HumanSize.format(1_500_000, precision: 4) # => "1.5 MB"Fixed-unit formatting
Use convert to format bytes to a specific unit (rather than auto-picking the largest fitting unit). The precision option controls the number of decimal places (default is 2):
Philiprehberger::HumanSize.convert(1_500_000, unit: "MB") # => "1.50 MB"
Philiprehberger::HumanSize.convert(1024 * 1024, unit: "MiB") # => "1.00 MiB"
Philiprehberger::HumanSize.convert(1_500_000, unit: "MB", precision: 0) # => "2 MB"Throughput (rate) formatting
Format a byte count and an elapsed duration into a human-readable /s rate. Raises HumanSize::Error for non-positive durations:
Philiprehberger::HumanSize.format_rate(1_500_000, 1) # => "1.5 MB/s"
Philiprehberger::HumanSize.format_rate(3_000_000, 2) # => "1.5 MB/s"
Philiprehberger::HumanSize.format_rate(1_048_576, 1, binary: true) # => "1 MiB/s"
Philiprehberger::HumanSize.format_rate(500_000, 0.5) # => "1 MB/s"Parsing
Parse human-readable byte strings back to integer byte counts. Parsing is case-insensitive and supports both SI and binary units:
Philiprehberger::HumanSize.parse("1.5 GB") # => 1500000000
Philiprehberger::HumanSize.parse("500 KiB") # => 512000
Philiprehberger::HumanSize.parse("1 TB") # => 1000000000000
Philiprehberger::HumanSize.parse("2.5 MiB") # => 2621440Structured Output
Use format_parts to get the numeric value and unit separately:
Philiprehberger::HumanSize.format_parts(1_500_000) # => { value: 1.5, unit: "MB" }
Philiprehberger::HumanSize.format_parts(1_572_864, binary: true) # => { value: 1.5, unit: "MiB" }
Philiprehberger::HumanSize.format_parts(0) # => { value: 0.0, unit: "B" }Validation
Check if a string is a valid byte size without raising:
Philiprehberger::HumanSize.valid?("1.5 GB") # => true
Philiprehberger::HumanSize.valid?("nope") # => false
Philiprehberger::HumanSize.valid?(123) # => falseCompact Formatting
Drop the space between the value and the unit for dense UI surfaces (badges,
tables, log lines). Pass compact: true to format or use the dedicated
format_compact shortcut:
Philiprehberger::HumanSize.format(1_500_000, compact: true) # => "1.5MB"
Philiprehberger::HumanSize.format_compact(1_500_000) # => "1.5MB"
Philiprehberger::HumanSize.format_compact(1_572_864, binary: true) # => "1.5MiB"
Philiprehberger::HumanSize.format_compact(500) # => "500B"Comparing Sizes
Spaceship comparison of two sizes — accepts strings, numbers, or a mix:
Philiprehberger::HumanSize.compare('500 MB', '1.5 GB') # => -1
Philiprehberger::HumanSize.compare('1024 MiB', '1 GiB') # => 0
Philiprehberger::HumanSize.compare('2 TB', '500 GB') # => 1
Philiprehberger::HumanSize.compare(2048, '1 KB') # => 1
# Sort filenames by size:
['1 GB', '500 MB', '2 KB', '1.5 TB'].sort do |a, b|
Philiprehberger::HumanSize.compare(a, b)
end
# => ["2 KB", "500 MB", "1 GB", "1.5 TB"]API
| Method | Description |
|---|---|
HumanSize.format(bytes, binary: false, precision: 2, compact: false) |
Convert integer bytes to a human-readable string (SI or binary units); pass compact: true to drop the separator |
HumanSize.format_compact(bytes, binary: false, precision: 2) |
Shortcut for format(..., compact: true) — no space between value and unit |
HumanSize.format_parts(bytes, binary: false, precision: 2) |
Return a hash with :value (Float) and :unit (String) |
HumanSize.convert(bytes, unit:, precision: 2) |
Format bytes to a specific unit (e.g. 'MB', 'GiB'); raises HumanSize::Error on unknown units |
HumanSize.format_rate(bytes, seconds, binary: false, precision: 2) |
Format a throughput as a human-readable /s rate; raises on non-positive seconds
|
HumanSize.parse(string) |
Parse a human-readable byte string back to an integer byte count |
HumanSize.valid?(string) |
Check if a string is a valid parseable byte size |
HumanSize.compare(a, b) |
Spaceship comparison of two sizes (accepts strings, numbers, or a mix); returns -1, 0, or 1
|
Development
bundle install
bundle exec rspec
bundle exec rubocopSupport
If you find this project useful: