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_size
Usage
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"
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") # => 2621440
Structured 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) # => false
API
| Method | Description |
|---|---|
HumanSize.format(bytes, binary: false, precision: 2) |
Convert integer bytes to a human-readable string (SI or binary units) |
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.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 |
Development
bundle install
bundle exec rspec
bundle exec rubocop
Support
If you find this project useful: