pad-0.1.5/.gitignore010064400007650000024000000000241277157260700125020ustar0000000000000000/target /Cargo.lock pad-0.1.5/.travis.yml010064400007650000024000000001431325104017300126030ustar0000000000000000language: rust rust: - stable - beta - nightly matrix: allow_failures: - rust: nightly pad-0.1.5/Cargo.toml.orig010064400007650000024000000004511325104126500133660ustar0000000000000000[package] name = "pad" description = "Library for padding strings at runtime" authors = ["Ben S "] documentation = "https://docs.rs/pad/" homepage = "https://github.com/ogham/rust-pad" license = "MIT" readme = "README.md" version = "0.1.5" [dependencies] unicode-width = "0.1.1" pad-0.1.5/Cargo.toml0000644000000014730000000000000076450ustar00# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g. crates.io) dependencies # # If you believe there's an error in this file please file an # issue against the rust-lang/cargo repository. If you're # editing this file be aware that the upstream Cargo.toml # will likely look very different (and much more reasonable) [package] name = "pad" version = "0.1.5" authors = ["Ben S "] description = "Library for padding strings at runtime" homepage = "https://github.com/ogham/rust-pad" documentation = "https://docs.rs/pad/" readme = "README.md" license = "MIT" [dependencies.unicode-width] version = "0.1.1" pad-0.1.5/LICENCE010064400007650000024000000020561325104035300114640ustar0000000000000000MIT License Copyright (c) 2018 Benjamin Sago Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. pad-0.1.5/README.md010064400007650000024000000066451325104066100117700ustar0000000000000000# rust-pad [![pad on crates.io](http://meritbadge.herokuapp.com/pad)](https://crates.io/crates/pad) [![Build status](https://travis-ci.org/ogham/rust-pad.svg?branch=master)](https://travis-ci.org/ogham/rust-pad) This is a library for padding strings at runtime. The routines in `std::fmt` only work with formatting strings provided at compile-time, making them unsuitable for padding to a custom or user-defined value. Rather than re-implement all of `std::fmt`, padding is probably the most common use case, which is written in a more runtime-friendly fashion here. It provides four helper functions for the most common use cases, and one main function to cover the other cases. ### [View the Rustdoc](https://docs.rs/pad) # Installation This crate works with [Cargo](http://crates.io). Add the following to your `Cargo.toml` dependencies section: ```toml [dependencies] pad = "0.1" ``` # Usage You can pad a string to have a minimum width with the `pad_to_width` method: ```rust use pad::PadStr; println!("{}", "Hi there!".pad_to_width(16)); ``` This will print out “Hi there!” followed by seven spaces, which is the number of spaces necessary to bring it up to a total of sixteen characters wide. String length is determined with the [unicode_width](https://unicode-rs.github.io/unicode-width/unicode_width/index.html) crate, without assuming CJK. ## Alignment By default, strings are left-aligned: any extra characters are added on the right. To change this, pass in an `Alignment` value: ```rust use pad::{PadStr, Alignment}; let s = "I'm over here".pad_to_width_with_alignment(20, Alignment::Right); ``` There are four of these in total: - **Left**, which puts the text on the left and spaces on the right; - **Right**, which puts the text on the right and spaces on the left; - **Middle**, which centres the text evenly, putting it slightly to the left if it can’t be exactly centered; - **MiddleRight**, as above, but to the right. ## Characters Another thing that’s set by default is the character that’s used to pad the strings — by default, it’s space, but you can change it: ```rust use pad::PadStr; let s = "Example".pad_to_width_with_char(10, '_'); ``` ## Truncation Finally, you can override what happens when a value exceeds the width you give. By default, the width parameter indicates a *minimum width*: any string less will be padded, but any string greater will still be returned in its entirety. You can instead tell it to pad with a maximum value, which will truncate the input when a string longer than the width is passed in. ```rust use pad::PadStr; let short = "short".with_exact_width(10); // "short " let long = "this string is long".with_exact_width(10); // "this strin" ``` # A Full Example All of the above functions delegate to the `pad` function, which you can use in special cases. Here, in order to **right**-pad a number with **zeroes**, pass in all the arguments: ```rust use pad::{PadStr, Alignment}; let s = "12345".pad(10, '0', Alignment::Right, true); ``` (The `true` at the end could just as easily be `false`. It’s whether to truncate or not.) # A Note on Debugging One very last point: the width function takes a `usize`, rather than a signed number type. This means that if you try to pass in a negative size, it’ll wrap around to a positive size, and produce a massive string and possibly crash your program. So if your padding calls are failing for some reason, this is probably why. pad-0.1.5/src/lib.rs010064400007650000024000000176251325104151100124070ustar0000000000000000#![crate_name = "pad"] #![crate_type = "rlib"] #![crate_type = "dylib"] #![deny(unsafe_code)] #![warn(missing_copy_implementations)] #![warn(missing_debug_implementations)] #![warn(missing_docs)] #![warn(trivial_numeric_casts)] #![warn(unreachable_pub)] #![warn(unused_results)] //! This is a library for padding strings at runtime. //! //! The routines in `std::fmt` only work with formatting strings provided at //! compile-time, making them unsuitable for padding to a custom or //! user-defined value. Rather than re-implement all of `std::fmt`, padding is //! probably the most common use case, which is written in a more //! runtime-friendly fashion here. //! //! It provides four helper functions for the most common use cases, and one //! main function (`pad`) to cover the other cases. //! //! String length is determined with the //! [width](http://doc.rust-lang.org/nightly/std/str/trait.StrExt.html#tymethod.width) //! function, without assuming CJK. //! //! Examples //! -------- //! //! You can pad a string to have a minimum width with the `pad_to_width` //! method: //! //! ```rust //! use pad::PadStr; //! println!("{}", "Hi there!".pad_to_width(16)); //! ``` //! //! This will print out "Hi there!" followed by seven spaces, which is the //! number of spaces necessary to bring it up to a total of sixteen characters //! wide. //! //! //! Alignment //! --------- //! //! By default, strings are left-aligned: any extra characters are added on //! the right. To change this, pass in an `Alignment` value: //! //! ```rust //! use pad::{PadStr, Alignment}; //! let s = "I'm over here".pad_to_width_with_alignment(20, Alignment::Right); //! ``` //! //! There are four of these in total: //! //! - **Left**, which puts the text on the left and spaces on the right; //! - **Right**, which puts the text on the right and spaces on the left; //! - **Middle**, which centres the text evenly, putting it slightly to the //! left if it can't be exactly centered; //! - **MiddleRight**, as above, but to the right. //! //! //! Characters //! ---------- //! //! Another thing that's set by default is the character that's used to pad //! the strings - by default, it's space, but you can change it: //! //! ```rust //! use pad::PadStr; //! let s = "Example".pad_to_width_with_char(10, '_'); //! ``` //! //! //! Truncation //! ---------- //! //! Finally, you can override what happens when a value exceeds the width you //! give. By default, the width parameter indicates a *minimum width*: any //! string less will be padded, but any string greater will still be returned //! in its entirety. //! //! You can instead tell it to pad with a maximum value, which will truncate //! the input when a string longer than the width is passed in. //! //! ```rust //! use pad::PadStr; //! let short = "short".with_exact_width(10); // "short " //! let long = "this string is long".with_exact_width(10); // "this strin" //! ``` //! //! //! A Full Example //! -------------- //! //! All of the above functions delegate to the `pad` function, which you can //! use in special cases. Here, in order to **right**-pad a number with //! **zeroes**, pass in all the arguments: //! //! ```rust //! use pad::{PadStr, Alignment}; //! let s = "12345".pad(10, '0', Alignment::Right, true); //! ``` //! //! (The `true` at the end could just as easily be `false`. It's whether to //! truncate or not.) //! //! //! Note on Debugging //! ----------------- //! //! One very last point: the width function takes a `usize`, rather than a //! signed number type. This means that if you try to pass in a negative size, //! it'll wrap around to a positive size, and produce a massive string and //! possibly crash your program. So if your padding calls are failing for some //! reason, this is probably why. extern crate unicode_width; use unicode_width::UnicodeWidthStr; /// An **alignment** tells the padder where to put the spaces. #[derive(PartialEq, Eq, Debug, Copy, Clone)] pub enum Alignment { /// Text on the left, spaces on the right. Left, /// Text on the right, spaces on the left. Right, /// Text in the middle, spaces around it, but **shifted to the left** if it can't be exactly central. Middle, /// Text in the middle, spaces around it, but **shifted to the right** if it can't be exactly central. MiddleRight, } /// Functions to do with string padding. pub trait PadStr { /// Pad a string to be at least the given width by adding spaces on the /// right. fn pad_to_width(&self, width: usize) -> String { self.pad(width, ' ', Alignment::Left, false) } /// Pad a string to be at least the given width by adding the given /// character on the right. fn pad_to_width_with_char(&self, width: usize, pad_char: char) -> String { self.pad(width, pad_char, Alignment::Left, false) } /// Pad a string to be at least the given with by adding spaces around it. fn pad_to_width_with_alignment(&self, width: usize, alignment: Alignment) -> String { self.pad(width, ' ', alignment, false) } /// Pad a string to be *exactly* the given width by either adding spaces /// on the right, or by truncating it to that width. fn with_exact_width(&self, width: usize) -> String { self.pad(width, ' ', Alignment::Left, true) } /// Pad a string to the given width somehow. fn pad(&self, width: usize, pad_char: char, alignment: Alignment, truncate: bool) -> String; } impl PadStr for str { fn pad(&self, width: usize, pad_char: char, alignment: Alignment, truncate: bool) -> String { use self::Alignment::*; // Use width instead of len for graphical display let cols = UnicodeWidthStr::width(self); if cols >= width { if truncate { return self[..width].to_string(); } else { return self.to_string(); } } let diff = width - cols; let (left_pad, right_pad) = match alignment { Left => (0, diff), Right => (diff, 0), Middle => (diff / 2, diff - diff / 2), MiddleRight => (diff - diff / 2, diff / 2), }; let mut s = String::new(); for _ in 0..left_pad { s.push(pad_char) } s.push_str(self); for _ in 0..right_pad { s.push(pad_char) } s } } #[cfg(test)] mod test { use super::PadStr; use super::Alignment::*; macro_rules! test { ($name: ident: $input: expr => $result: expr) => { #[test] fn $name() { assert_eq!($result.to_string(), $input) } }; } test!(zero: "".pad_to_width(0) => ""); test!(simple: "hello".pad_to_width(10) => "hello "); test!(spaces: "".pad_to_width(6) => " "); test!(too_long: "hello".pad_to_width(2) => "hello"); test!(still_to_long: "hi there".pad_to_width(0) => "hi there"); test!(exact_length: "greetings".pad_to_width(9) => "greetings"); test!(one_more: "greetings".pad_to_width(10) => "greetings "); test!(one_less: "greetings".pad_to_width(8) => "greetings"); test!(left: "left align".pad_to_width_with_alignment(13, Left) => "left align "); test!(right: "right align".pad_to_width_with_alignment(13, Right) => " right align"); test!(centre_even: "good day".pad_to_width_with_alignment(12, Middle) => " good day "); test!(centre_odd: "salutations".pad_to_width_with_alignment(13, Middle) => " salutations "); test!(centre_offset: "odd".pad_to_width_with_alignment(6, Middle) => " odd "); test!(centre_offset_2: "odd".pad_to_width_with_alignment(6, MiddleRight) => " odd "); test!(character: "testing".pad_to_width_with_char(10, '_') => "testing___"); test!(accent: "pâté".pad_to_width(6) => "pâté "); test!(truncate: "this song is just six words long".with_exact_width(7) => "this so"); test!(too_short: "stormclouds".with_exact_width(15) => "stormclouds "); }