elementary / elementary/granite
Custom format_size () and format_speed () methods
- Dominant language
- Vala
- Stars
- 329
- Forks
- 65
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 31
Description
### Problem
Glib's `format_size ()` seems to be intended for things like file sizes and the strings look like `123 bytes` or `123 bits` or `123 MB` or `123 MiB` depending on the flags provided.
This may confuse your everyday user asking what does the lowercase letter `I` mean when they see `MiB` or `GiB`, or, why does my disk size differ when Files app or Installer app show me `1.1 TB` when I have a "1 terabyte" disk or I used gparted to create a "1 terabyte" partition?
### Proposal
Add custom helper methods similar to `GLib.format_size ()` (and its `FormatSizeFlags` enum) named `Granite.format_size ()` and `Granite.format_speed ()` along with `FormatSizeFlags` and `FormatSpeedFlags` (or maybe just common `FormatFlags`) with the following modified behaviour:
Glib's `format_size ()` seems to be intended for things like file sizes and the strings look like `123 bytes` or `123 bits` or `123 MB` or `123 MiB` depending on the flags provided.
The proposed two new helper methods (and flags) would output the following examples:
`Granite.format_size (123, DEFAULT)` -> `123 bytes`
`Granite.format_size (123, BITS)` -> `123 bits`
`Granite.format_size (1000, DEFAULT)` -> `1 MB`
`Granite.format_size (1000, BITS)` -> `1 Mb`
`Granite.format_size (123, IEC_UNIT)` -> `123 bytes`
`Granite.format_size (123, BITS | IEC_UNIT)` -> `123 bits`
`Granite.format_size (1024, IEC_UNIT)` -> `1 MB`
`Granite.format_size (1024, BITS | IEC_UNIT)` -> `1 Mb`
Note the difference here is that even for the `IEC_UNIT` flag (enabled or disabled) we always display "MB or "GB" and exclude the lowercase `I` so do not display `MiB` or `GiB` etc just the scale changes from 1000 to 1024.
So if we want to display things like file or disk partition sizes apps can set the `IEC_UNIT` flag but while displaying disk size can unset the `IEC_UNIT` flag since manufacturers typically use scale 1000 for disk sizes.
The other method `Granite.format_speed ()` has the same difference in behaviour from Glib with the additional feature that the units include the speed "per second" actually just `ps` appended, so the following examples:
`Granite.format_speed (123, DEFAULT)` -> `123 Bps`
`Granite.format_speed (123, BITS)` -> `123 bps`
`Granite.format_speed (1000, DEFAULT)` -> `1 MBps`
`Granite.format_speed (1000, BITS)` -> `1 Mbps`
`Granite.format_speed (123, IEC_UNIT)` -> `123 Bps`
`Granite.format_speed (123, BITS | IEC_UNIT)` -> `123 bps`
`Granite.format_speed (1024, IEC_UNIT)` -> `1 MBps`
`Granite.format_speed (1024, BITS | IEC_UNIT)` -> `1 Mbps`
Typical usage of the speed methods would be to use `IEC_UNIT` flag for things like disk files transfers and add the `BITS` flag for network transfers because ISPs typically advertise their speeds like `100 Mbps` or `5 Gbps` plans.
Rationale for this feature request is the same as the one used for the existing custom helper method: For everyday users to not wonder what the lowercase letter `I` is in the `MiB` or `GiB` and why apps like Files show different (slightly larger) sizes for things like files or disks when they, say, partition a disk (using gparted) to be 1 "terabyte" (1024 ^ 4 bytes) then the Files app (or in the Installer app) shows it as a size of "1.1 TB" seemingly off from what they intended.
Existing elementary apps (Files, Installer, system settings hardware view etc) or other Granite users can choose to easily drop-in replace the GLib helper method.
### Prior Art (Optional)
See the custom helper method here: https://github.com/elementary/settings-system/blob/main/src/Views/HardwareView.vala#L697 for an existing similar approach.
Contributor guide
Research direction
Start by reviewing the existing helper approach in settings-system's HardwareView.vala and GLib's format_size() and FormatSizeFlags APIs. Define the Granite helper and flag behavior from the proposed size and speed examples, then verify that the resulting API supports the listed unit scales, bit units, and per-second suffixes.
Written by the indexing model from the issue text.
Assessment
- Domain
- developer-experience
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100