From a425325fe6cc1a0cfe00ea6d8e89cec01308424f Mon Sep 17 00:00:00 2001 From: John Jekel Date: Sat, 10 Dec 2022 22:40:03 -0500 Subject: [PATCH] Improve docs; also improve efficiency in string.rs --- README.md | 36 ++++++++++++++++++------------------ src/byte_string.rs | 3 +-- src/lib.rs | 13 ++----------- src/string.rs | 40 +++++++++++++++++++++++++++++++--------- 4 files changed, 52 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index e0a8e86..ff99505 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,21 @@ A simple Rust library to translate from English to Pig Latin! Essentially, the word is reorganized in an effort to hide its true meaning, which can be lots of fun! +# A Quick Example + +After adding Anslatortray as a dependency in your crate, try compiling this example code: + +```rust +use anslatortray::translate; + +fn main() { + //Prints "Ellohay orldway omfray ethay Anslatortray orfay Ustray!" + println!("{}", translate("Hello world from the Translator for Rust!")); +} +``` + +# Tell me more! + The Anslatortray library can help out by converting any English text into Pig Latin quickly and easily. It is **incredibly fast** (see the Performance section below) and **requires no dependencies**! You can translate multiple sentences, including numbers, punctuation, and spacing, with a single call to `anslatortray::translate()`. @@ -17,27 +32,12 @@ Be sure to check out the documentation at check out the documentation for more. +If you wish to use the library in your crate, add anslatortray as a dependency and check out the documentation. -If you wish to use the `anslatortray` standalone binary, clone `https://git.jekel.ca/JZJ/anslatortray.git`, do `cargo build --release`, and you'll find the binary in the target/release directory. +If you wish to use the `anslatortray` standalone binary (shown in the next section), clone `https://git.jekel.ca/JZJ/anslatortray.git`, do `cargo build --release`, and you'll find the binary in the target/release directory. See the wiki for more information. -# A Quick Example - -After adding Anslatortray as a dependency in your crate, try compiling this example code: - -```rust -use anslatortray::translate; - -fn main() { - //Prints "Ellohay orldway omfray ethay Anslatortray orfay Ustray!" - println!("{}", translate("Hello world from the Translator for Rust!")); -} -``` - -Check out the documentation for more examples! - # anslatortray CLI Tool Usage There are several options supported by the `anslatortray` command: @@ -102,7 +102,7 @@ See wiki page about Anslatortray's performance! -Spoiler: It can translate one word in under **129ns** on average in the default UTF-8 mode, and in under **94ns** on average in ASCII-only mode on my dated system :) +Spoiler: `anslatortray::translate()` can process one word in under **50ns** on average! # Useful Links diff --git a/src/byte_string.rs b/src/byte_string.rs index 79252b0..5f4d92f 100644 --- a/src/byte_string.rs +++ b/src/byte_string.rs @@ -71,7 +71,6 @@ pub fn translate_with_style(english: &[u8], suffix_lower: &[u8], special_case_su } //TODO tests for this function -//TODO be sure to mention that if the strings are not ascii, the non-ascii bytes won't be affected pub(crate) fn translate_with_style_lower_and_upper_suffixes ( english: &[u8], suffix_lower: &[u8], special_case_suffix_lower: &[u8], suffix_upper: &[u8], special_case_suffix_upper: &[u8], @@ -265,7 +264,7 @@ fn push_slice_to_vector(vec: &mut Vec, slice: &[T]) { mod tests { use super::*; - //TODO test translate_with_style_lower_and_upper_suffixes (that's probably all we really need to test here) + //NOTE: We don't test byte_string::translate_with_style and other similar functions in here directly since we test them through string.rs //TODO test uppercase words diff --git a/src/lib.rs b/src/lib.rs index 44dfb76..905f8ae 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,16 +1,7 @@ -//!Anslatortray for Rust +//!Anslatortray for Rust: A simple Rust library to translate from English to Pig Latin. //! //!Welcome to the Anslatortray Documentation! //! -//!A simple Rust library to translate from English to Pig Latin. -//! -//!The Anslatortray library can help out by converting any English text into Pig Latin quickly and easily. It is **incredibly fast** and **requires no dependencies**! -//! -//!You can translate multiple sentences, including numbers, punctuation, and spacing, with a single call to [`translate()`]. -//!The function handles edge cases quite well (words without vowels, one-letter words, contractions, ALL CAPS, etc.), though there is always room for improvement. -//! -//!If you have suggestions for how the project could be improved, please visit the repository's issues page on Github or GitLab or contact me directly :) -//! //!# Building and Installation //! //!If you wish to use the library in your crate, add anslatortray as a dependency and follow along with the examples below, or check out the rest of the documentation. @@ -48,7 +39,7 @@ //! //!If none of these suit your needs, you can also choose your own suffixes with [`translate_with_style()`] //! -//!If you want more speed, and you know your text contains only ASCII characters, check out [`byte_string`] +//!If you want even more speed than the regular translation functions bring to the table, check out the [`byte_string`] module. //! //!# Useful Links //!Click here to visit the Anslatortray for Rust Git Repository!. diff --git a/src/string.rs b/src/string.rs index 11cca7f..018e30c 100644 --- a/src/string.rs +++ b/src/string.rs @@ -9,12 +9,10 @@ /* Imports */ -use crate::byte_string::translate_with_style as translate_byte_string_with_style; +use crate::byte_string::translate_with_style_lower_and_upper_suffixes as translate_byte_string_with_style_lower_and_upper_suffixes; /* Functions */ -//TODO use byte_string::translate_with_style_lower_and_upper_suffixes for speed - ///Translates a multi-word string (including punctuation) into Pig Latin! /// ///Uses the default suffix and special_case_suffix, "ay" and "way" respectively when calling [`translate_with_style()`]. @@ -82,7 +80,7 @@ pub fn translate(english: &str) -> String { ///assert_eq!(translate_way("Hyphens-are-difficult-aren't-they?"), "Yphenshay-areway-ifficultday-arenway't-eythay?"); ///``` pub fn translate_way(english: &str) -> String { - return translate_with_style(english, "ay", "way"); + return translate_with_style_lower_and_upper_suffixes(english, "ay", "way", "AY", "WAY"); } ///Translates a multi-word string (including punctuation) into Pig Latin (yay-style)! @@ -116,7 +114,7 @@ pub fn translate_way(english: &str) -> String { ///assert_eq!(translate_yay("Hyphens-are-difficult-aren't-they?"), "Yphenshay-areyay-ifficultday-arenyay't-eythay?"); ///``` pub fn translate_yay(english: &str) -> String { - return translate_with_style(english, "ay", "yay"); + return translate_with_style_lower_and_upper_suffixes(english, "ay", "yay", "AY", "YAY"); } ///Translates a multi-word string (including punctuation) into Pig Latin (hay-style)! @@ -150,7 +148,7 @@ pub fn translate_yay(english: &str) -> String { ///assert_eq!(translate_hay("Hyphens-are-difficult-aren't-they?"), "Yphenshay-arehay-ifficultday-arenhay't-eythay?"); ///``` pub fn translate_hay(english: &str) -> String { - return translate_with_style(english, "ay", "hay"); + return translate_with_style_lower_and_upper_suffixes(english, "ay", "hay", "AY", "HAY"); } ///Translates a multi-word string (including punctuation) into Ferb Latin! @@ -182,7 +180,7 @@ pub fn translate_hay(english: &str) -> String { ///assert_eq!(translate_ferb("Hyphens-are-difficult-aren't-they?"), "Yphensherb-areferb-ifficultderb-arenferb't-eytherb?"); ///``` pub fn translate_ferb(english: &str) -> String { - return translate_with_style(english, "erb", "ferb"); + return translate_with_style_lower_and_upper_suffixes(english, "erb", "ferb", "ERB", "FERB"); } ///Translates a multi-word string (including punctuation) into a custom-styled play language! @@ -229,15 +227,39 @@ pub fn translate_ferb(english: &str) -> String { ///); ///``` pub fn translate_with_style(english: &str, suffix_lower: &str, special_case_suffix_lower: &str) -> String { + //Convert the suffix and special_case_suffix we were provided to uppercase for words that are capitalized + let mut suffix_upper = String::with_capacity(suffix_lower.len()); + for letter in suffix_lower.chars() { + suffix_upper.push(letter.to_ascii_uppercase()); + } + let mut special_case_suffix_upper = String::with_capacity(special_case_suffix_lower.len()); + for letter in special_case_suffix_lower.chars() { + special_case_suffix_upper.push(letter.to_ascii_uppercase()); + } + + return translate_with_style_lower_and_upper_suffixes ( + english, + suffix_lower, special_case_suffix_lower, &suffix_upper, &special_case_suffix_upper + ); +} + +//More efficient: Does not need to convert to upppercase at runtime +fn translate_with_style_lower_and_upper_suffixes ( + english: &str, + suffix_lower: &str, special_case_suffix_lower: &str, suffix_upper: &str, special_case_suffix_upper: &str +) -> String { //Convert the string slices to byte slices and translate those (only ASCII letters are affected, non-letters or UTF-8 are preserved) let mut pig_latin_string_bytes = Vec::::with_capacity(english.len() * 2);//Plenty of headroom in case the words are very small or the suffixes are long - translate_byte_string_with_style(english.as_bytes(), suffix_lower.as_bytes(), special_case_suffix_lower.as_bytes(), &mut pig_latin_string_bytes); + translate_byte_string_with_style_lower_and_upper_suffixes ( + english.as_bytes(), + suffix_lower.as_bytes(), special_case_suffix_lower.as_bytes(), suffix_upper.as_bytes(), special_case_suffix_upper.as_bytes(), + &mut pig_latin_string_bytes + ); //This is safe since translate_byte_string_with_style does not touch any unicode bytes (it just copies them) return unsafe { String::from_utf8_unchecked(pig_latin_string_bytes) }; } - /* Tests */ #[cfg(test)]