{"id":20186027,"url":"https://github.com/neosmart/prettysize-rs","last_synced_at":"2025-04-04T12:06:04.069Z","repository":{"id":37251697,"uuid":"144234651","full_name":"neosmart/prettysize-rs","owner":"neosmart","description":"Pretty-print file sizes and more","archived":false,"fork":false,"pushed_at":"2025-03-28T02:03:36.000Z","size":166,"stargazers_count":44,"open_issues_count":1,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T11:07:55.292Z","etag":null,"topics":["crate","formatting","rust","rust-library","units"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neosmart.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-10T03:58:04.000Z","updated_at":"2025-03-28T02:03:39.000Z","dependencies_parsed_at":"2025-03-08T21:26:16.352Z","dependency_job_id":null,"html_url":"https://github.com/neosmart/prettysize-rs","commit_stats":{"total_commits":94,"total_committers":3,"mean_commits":"31.333333333333332","dds":"0.021276595744680882","last_synced_commit":"176c8fe0b0e033d29d1bade27a25b2eaf46a6c9b"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neosmart%2Fprettysize-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neosmart%2Fprettysize-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neosmart%2Fprettysize-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neosmart%2Fprettysize-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neosmart","download_url":"https://codeload.github.com/neosmart/prettysize-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174415,"owners_count":20896078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crate","formatting","rust","rust-library","units"],"created_at":"2024-11-14T03:15:42.659Z","updated_at":"2025-04-04T12:06:04.051Z","avatar_url":"https://github.com/neosmart.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# PrettySize, rust edition\n\n[![crates.io](https://img.shields.io/crates/v/size.svg)](https://crates.io/crates/size) [![docs.rs](https://docs.rs/size/badge.svg)](https://docs.rs/size/latest/size/)\n\nA comprehensive file size crate for rust applications, meant to be light and effective.\nIncludes utilities for human-readable formatting of file sizes as well as converting\nbetween different base-two and base-ten size units and performing both mathematical and\nlogical operations on strongly-typed file sizes.\n\n[See the crate documentation](https://docs.rs/size/latest/size/) for a more complete summary of\nwhat this crate can do and how to use it.\n\n## Features\n\n`PrettySize` provides\n\n* a `Size` type that can be used to hold a strongly-typed size\n  (e.g. `let size = Size::from_gigabytes(4)`) and perform operations on it,\n* definitions for the base-two and base-ten file size units defined as `pub const` in the\n  `size::consts` namespace, available both in abbreviated and unabridged forms (i.e.\n  `consts::KiB` and `consts::KIBIBYTE` or `consts::GB` and `consts::GIGABYTE`),\n* an `std::Display` impl for `Size` to automatically display sizes in a human-readable\n  format, automatically choosing the best size unit and numeric precision to\n  give the nicest results (you can also use `Size::to_string()` instead).\n* a `Size.format()` method that gives you more control over how sizes are converted\n  to a textual representation, letting you to specify the base of the human-readable\n  units and their style (smart, abbreviated, or full; plus their lowercase variants).\n* mathematical and logical operations on strongly-typed `Size` values,\n* full support for expressing negative sizes (e.g. the difference between two sizes, or the\n  amount of space reclaimed on a disk)\n* serialization to/from bare byte fields in network payloads or other api requests/responses\n* parsing sizes from text representation in a wide variety of formats\n\nThis crate can also be used in `no_std` mode (by compiling with default features\ndisabled). This disables string conversion/formatting/parsing but keeps all the strongly-typed\nsize conversion and mathematical/logical operations available.\n\nThis crate is free of any dependencies.\n\n## Usage\n\nCargo.toml:\n\n```toml\n[dependencies]\nsize = \"0.5.0-preview2\"\n```\n\nand in your code:\n\n```rust\nuse size::{Base, Size};\n// You can use/import consts representing base2/base10 sizes individually\n// as (e.g.) size::KiB, or import all with `use size::consts::*`\n\nfn main() {\n  // Create strongly-typed sizes:\n  let byte_count = Size::from_kilobytes(42);\n  assert_eq!(42_000, byte_count.bytes());\n\n  // Use predefined constants for the various units\n  let byte_count = 42 * size::KiB;\n  assert_eq!(43_008, byte_count);\n\n  // `Size` can take any numeric type you throw at it\n  let byte_count = Size::from_mib(0.040055);\n  assert_eq!(byte_count.bytes(), 42_000);\n\n  // And for those of you that haven't yet drunk the base-two Kool-Aid:\n  let file_size = Size::from_kb(42);\n  assert_eq!(file_size.bytes(), 42_000);\n\n  println!(\"{}, I say!\", file_size);\n  // prints \"41 KiB, I say!\"\n\n  // Override the default choice of base-2 units\n  println!(\"{}, I meant!\", file_size.format().with_base(Base::Base10));\n  // prints \"42 KB, I meant!\"\n\n  // Add and subtract strongly-typed sizes, even with different underlying types\n  let sum = Size::from_mb(1.0) + Size::from_kb(200);\n  assert_eq!(sum.bytes(), 1_200_000);\n\n  // Multiply and divide strongly-typed sizes by scalar values\n  let new_size = Size::from_mib(2) * 2;\n  assert_eq!(new_size, Size::from_mib(4));\n\n  // Compare sizes for equality or order\n  let size1 = Size::from_gigabytes(2);\n  let size2 = Size::from_gibibytes(1.99);\n  assert!(size1 \u003c size2);\n\n  // Parse sizes from textual representations\n  let size1 = Size::from_str(\"12 KiB\").unwrap();\n  let size2 = Size::from_str(\"42mb\").unwrap();\n}\n```\n\n## Parsing and formatting\n\nThe `size` crate supports parsing textual representations of file sizes into strongly typed `Size` objects, both via the `Size::from_str()` function and its `FromStr` implementation that lets you call `\"1234 kilobytes\".parse()`.\n\nThe `Size` type implements `std::fmt::Display` (in addition to many other traits), which provides a facility to generate properly formatted textual representations of file sizes via the `Size::to_string()` impl of the `ToString` trait or when used in a `format!(..., Size)` context.\n\nBy default, `Size` objects are formatted as base-2 (KiB, MiB, etc) with heuristically chosen precision and units. The member function `Size::format()` can be used to override the unit base (e.g. MB vs MiB) and whether or not abbreviated unit names are used (e.g. KiB vs Kebibyte).\n\nFeel free to open a GitHub issue or PR if you need further control over formatting (precision, case, etc)!\n\n## `no_std` usage\n\nAdd the crate to `Cargo.toml` with `default-features` disabled for `no_std` support:\n\n```toml\n[dependencies]\nsize = { version = ..., default-features = false }\n```\n\nBuilding in `no_std` mode disables support for floating point `Size` operations/conversions as well as string formatting and conversion.\n\n## `serde` support\n\nFor serialization and deserialization support, add the `size` crate to your `Cargo.toml` with the `serde` feature enabled:\n\n```toml\n[dependencies]\nsize = { version = ..., features = [ \"serde\" ] }\n```\n\n**The `Size` type is serialized/deserialized transparently.** This means that it acts as if it were a `u64` field denoting the size in bytes. This was done to allow directly deserializing from network payloads from languages/apis that do not express sizes as strongly typed fields (and vice-versa).\n\nAs a concrete example, let's pretend you have the following struct that contains a `Size` field:\n\n```rust\n#[derive(Serialize, Deserialize)]\nstruct File {\n    path: PathBuf,\n    size: Size,\n}\n```\n\nUsing JSON as an example, the `File` type above will serialize to/from the following:\n\n```json\n{\n    \"path:\" \"/foo/bar\",\n    \"size:\" 1024\n}\n```\n\nAs you can see, the `size` field has been serialized directly to a numeric value (and not a `Size` object _containing_ that number value).\n\n## Parsing sizes from strings\n\nThe `FromStr` impl or the static `Size::from_str()` member function can be used to parse sizes from text, and supports a wide variety of input formats and representations:\n\n```rust\nlet size1 = Size::from_str(\"123456\").unwrap();\nlet size2 = Size::from_str(\"17mib\").unwrap();\nlet size3 = Size::from_str(\"12.8 KB\").unwrap();\nlet size4 = Size::from_str(\"18.9 gigabytes\").unwrap();\n```\n\n## About\n\nThis project started off as a port of Mahmoud's\n[PrettySize.NET](https://github.com/neosmart/PrettySize.net) library from C# to Rust. Like\nthe C# edition of this project. Rust's richer `enum` types and powerful generics made\nimplementing a custom `Size` generic over the number type without verbosity additionally\npossible. Its scope has since grown considerably.\n\n# License\n\n`PrettySize` is written and maintained by Mahmoud Al-Qudsi of NeoSmart Technologies and\nreleased to the general public under the terms of the MIT public license.\n\n## To-Do\n\n*This section is currently empty 🎉*\n\nPull requests are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneosmart%2Fprettysize-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneosmart%2Fprettysize-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneosmart%2Fprettysize-rs/lists"}