Cargo.toml

 [package]
 name = "anslatortray"
-version = "0.1.1"
+version = "0.5.0"
 description = "A simple Rust library to translate from English to Pig Latin!"
 authors = ["John Zacarias Jekel <john@jekel.ca>"]
 readme = "README.md"
 #homepage = ""
 repository = "https://git.jekel.ca/JZJ/anslatortray-rs"
 license = "MIT"
-license-file = "LICENSE"
+#license-file = "LICENSE"
 edition = "2021"
 keywords = ["pig", "latin", "text", "translate", "translator"]
 categories = ["text-processing", "command-line-utilities", "localization"]
+default-run = "anslatortray"
+documentation = "https://docs.rs/anslatortray/latest/anslatortray/"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[features]
+default = []
+nightly-features = ["nightly-features-benches"]
+nightly-features-benches = []
 
-[dependencies]
+[lib]
+name = "anslatortray"
+path = "src/lib.rs"
+
+[[bin]]
+name = "anslatortray"
+path = "src/anslatortray.rs"
+
+[profile.dev]
+incremental = true
+
+[profile.release]
+codegen-units = 1
+strip = true
+overflow-checks = false
+panic = "abort"
+lto = true
+
+[profile.release-with-debug]
+inherits = "release"
+strip = false
+overflow-checks = false
+panic = "abort"
+lto = false
+debug = true

README.md

-# anslatortray-rs
+# Anslatortray for Rust
 
 A simple Rust library to translate from English to Pig Latin!
 
@@ -6,40 +6,120 @@ 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!
 
-The Anslatortray library can help out by converting any English text into Pig Latin quickly and easily.
+# A Quick Example
 
-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, etc.), though there is always room for improvement.
+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()`.
+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 <a href="https://github.com/JZJisawesome/anslatortray-rs/issues">Github</a> or <a href="https://gitlab.com/JZJisawesome/anslatortray-rs/-/issues">GitLab</a> or contact me directly :)
 
-# Examples
+Be sure to check out the documentation at <https://docs.rs/anslatortray/latest/anslatortray/>!
+
+# Building and Installation
+
+If you wish to use the library in your crate, add anslatortray as a dependency and <a href="https://docs.rs/anslatortray/latest/anslatortray/">check out the documentation</a>.
 
-Try compiling this example code:
+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 <a href="https://git.jekel.ca/JZJ/anslatortray-rs/wiki/Building-And-Installing">wiki</a> for more information.
+
+# anslatortray CLI Tool Usage
+
+There are several options supported by the `anslatortray` command:
 
 ```
-use anslatortray::translate;
+> anslatortray --help
+Anslatortray: frontend for the Anslatortray for Rust library
+
+Options:
+--help            Print this helpful text!
+--interactive     Start an interactive translation session
+--file            Translate a file (requires two arguments, the file to translate and the destination)
+--benchmark-file  Benchmark translating a file (requires two arguments, the file to translate and the number of iterations to perform)
+--translate-args  Translates all remaining arguments provided and outputs them to stdout
+--stdin-to-stdout Translates input from stdin directly to stdout
+
+Avehay away oodgay ayday!
+```
 
-//Prints "Ellohay orldway omfray ethay Anslatortray orfay Ustray!"
-println!("{}", translate("Hello world from the Translator for Rust!"));
+You can start an interactive session by specifying --interactive (or no arguments at all):
+
+```
+> anslatortray --interactive
+Anslatortray: frontend for the Anslatortray for Rust library
+
+Starting interactive mode!
+Type what you'd like to translate and then press enter, or press Ctrl+C to exit...
+
+anslatortray> The fitness gram pacer test is a multi-stage areobic endurance test that...
+Ethay itnessfay amgray acerpay esttay isway away ultimay-agestay areobicway enduranceway esttay atthay...
+
+anslatortray> ^C
+>
+```
+
+You can also pipe text into the command for use in scripting:
+
+```
+> echo "Testing pipes" | anslatortray --stdin-to-stdout > test_pipes.txt
+Anslatortray: frontend for the Anslatortray for Rust library
+
+> cat test_pipes.txt
+Estingtay ipespay
+```
+
+If you'd like, you can even translate a text file:
+
+```
+> echo "Test file" > test_file.txt && cat test_file.txt
+Test file
+> anslatortray --file test_file.txt output_file.txt
+Anslatortray: frontend for the Anslatortray for Rust library
+
+Sucessful: took 3540ns to translate
+> cat output_file.txt
+Esttay ilefay
 ```
 
+See <a href="https://git.jekel.ca/JZJ/anslatortray-rs/wiki/Using-the-anslatortray-binary">this wiki page</a> for more!
+
+# Performance
+
+Check out the <a href="https://git.jekel.ca/JZJ/anslatortray-rs/wiki/Performance">wiki page about Anslatortray's performance</a>!
+
+Spoiler: `anslatortray::translate()` can process one word in under **50ns** on average!
+
 # Useful Links
 
 <a href="https://git.jekel.ca/JZJ/anslatortray-rs">Click here to visit the Anslatortray for Rust Git Repository!</a>.
 
 You can also visit the <a href="https://github.com/JZJisawesome/anslatortray-rs/issues">Github</a> or <a href="https://gitlab.com/JZJisawesome/anslatortray-rs/-/issues">GitLab</a> mirrors to leave issues!
 
-Anslatortray for Rust is a spiritual sucessor of my original <a href="https://git.jekel.ca/JZJ/anslatortray">Anslatortray</a> (for C++).
+Be sure to check out the documentation at <https://docs.rs/anslatortray/latest/anslatortray/> and the wiki at <https://git.jekel.ca/JZJ/anslatortray-rs/wiki>.
 
-# Anslatortray Code and Documentation Licence
+Anslatortray for Rust is a spiritual sucessor of my original <a href="https://git.jekel.ca/JZJ/anslatortray">Anslatortray</a> (for C++).
 
-MIT License
+# Dependencies
 
-Copyright (c) 2022 John Jekel
+None other than the standard libraries!
 
-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:
+# Anslatortray Code and Documentation Licence
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+Copyright (c) 2022 John Jekel
 
-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.
+MIT Licensed (see the LICENSE file for details)

TODO integration tests for ALL regular and byte_string functions.txt

+ 

src/anslatortray.rs

+/* anslatortray
+ * Copyright (C) 2022 John Jekel
+ * See the LICENSE file at the root of the project for licensing info.
+ *
+ * Command-line frontend for the anslatortray library
+ *
+*/
+
+/* Imports */
+
+use anslatortray::translate;
+use anslatortray::byte_string;
+
+/* Functions */
+
+fn main() {
+    eprintln!("Anslatortray: frontend for the Anslatortray for Rust library\n");
+
+    //Get all arguments after the executable's name
+    let mut args: Vec<String> = std::env::args().collect();
+    args.remove(0);
+
+    if args.len() == 0 {
+        interactive(&args);
+        return;
+    }
+
+    let option = args[0].clone();
+    args.remove(0);
+
+    match option.as_str() {
+        "--help" => { help(); },
+        "--interactive" => { interactive(&args); },
+        "--file" => { file(&args); },
+        "--benchmark-file" => { benchmark_file(&args); },
+        "--translate-args" => { translate_args(&args); },
+        "--stdin-to-stdout" => { stdin_to_stdout(&args); },
+        bad_option => {
+            eprintln!("Error: {} is not a valid option", bad_option);
+            help();
+        }
+    }
+}
+
+fn help() {
+    eprintln!("Options:");
+    eprintln!("--help            Print this helpful text!");
+    eprintln!("--interactive     Start an interactive translation session");
+    eprintln!("--file            Translate a file (requires two arguments, the file to translate and the destination)");
+    eprintln!("--benchmark-file  Benchmark translating a file (requires two arguments, the file to translate and the number of iterations to perform)");
+    eprintln!("--translate-args  Translates all remaining arguments provided and outputs them to stdout");
+    eprintln!("--stdin-to-stdout Translates input from stdin directly to stdout");
+
+    eprintln!("\n{}", translate("Have a good day!"));
+}
+
+fn interactive(args: &Vec<String>) {
+    if args.len() != 0 {
+        eprintln!("Error: didn't expect any arguments");
+        help();
+        return;
+    }
+
+    eprintln!("Starting interactive mode!");
+    eprintln!("Type what you'd like to translate and then press enter, or press Ctrl+C to exit...\n");
+
+    let stdin = std::io::stdin();
+    let mut line_buffer = String::new();
+    loop {
+        eprint!("anslatortray> ");
+        stdin.read_line(&mut line_buffer).unwrap();
+        eprintln!("{}", translate(&line_buffer));
+        line_buffer.truncate(0);
+    }
+}
+
+fn file(args: &Vec<String>) {
+    eprintln!("Note: anslatortray --file is highly experimental and has poor error handling. You have been warned.");
+
+    if args.len() != 2 {
+        eprintln!("Error: expected two arguments, two arguments, the file to translate and the destination");
+        help();
+        return;
+    }
+
+    //TODO error handling
+    //TODO switch to using byte_string for efficiency
+
+    let input_file = &args[0];
+    let output_file = &args[1];
+
+    let file_contents = std::fs::read_to_string(input_file).unwrap();
+    let start_time = std::time::Instant::now();
+    let translated_file_contents = translate(&file_contents);
+    let time_to_translate = start_time.elapsed();
+    std::fs::write(output_file, &translated_file_contents).unwrap();
+
+    eprintln!("Sucessful: took {}ns to translate", time_to_translate.as_nanos());
+}
+
+fn benchmark_file(args: &Vec<String>) {
+    eprintln!("Note: anslatortray --benchmark-file is highly experimental and has poor error handling. You have been warned.");
+
+    if args.len() != 2 {
+        eprintln!("Error: expected two arguments, the file to translate and the number of iterations to perform");
+        help();
+        return;
+    }
+
+    //TODO error handling
+
+    let input_file = &args[0];
+    let iterations = args[1].parse::<u128>().unwrap();//TODO error handling
+
+    let file_contents = std::fs::read_to_string(input_file).unwrap();
+
+    let mut total_duration_regular = std::time::Duration::new(0, 0);
+
+    for _ in 0..iterations {
+        let start_time = std::time::Instant::now();
+        let translated_file_contents = translate(&file_contents);
+        let time_to_translate = start_time.elapsed();
+
+        total_duration_regular += time_to_translate;
+        std::fs::write("/dev/null", &translated_file_contents).unwrap();//TODO avoid needing unix
+    }
+    eprintln!("Sucessful: Regular translation took {}ns to translate on average over {} runs.", total_duration_regular.as_nanos() / iterations, iterations);
+
+    let mut total_duration_byte_string = std::time::Duration::new(0, 0);
+
+    let mut translated_file_contents = Vec::<u8>::new();//TODO set a sane initial size
+    for _ in 0..iterations {
+        let start_time = std::time::Instant::now();
+        translated_file_contents.truncate(0);
+        byte_string::translate(file_contents.as_bytes(), &mut translated_file_contents);
+        let time_to_translate = start_time.elapsed();
+        total_duration_byte_string += time_to_translate;
+        std::fs::write("/dev/null", &translated_file_contents).unwrap();//TODO avoid needing unix
+    }
+    eprintln!("Sucessful: Byte-string translation with reused allocations took {}ns to translate on average over {} runs.", total_duration_byte_string.as_nanos() / iterations, iterations);
+}
+
+fn translate_args(args: &Vec<String>) {
+    if args.len() == 0 {
+        eprintln!("Error: expected at least one string to translate");
+        help();
+        return;
+    }
+
+    //Translate the arguments and print them out for the user
+    for string in args {
+        print!("{} ", translate(&string));
+    }
+    println!();
+}
+
+fn stdin_to_stdout(args: &Vec<String>) {
+    use std::io::{Read, Write};
+
+    if args.len() != 0 {
+        eprintln!("Error: didn't expect any arguments");
+        help();
+        return;
+    }
+
+    let mut stdin = std::io::stdin();
+    let mut stdout = std::io::stdout();
+    let mut buffer = String::new();
+
+    while let Ok(bytes_read) = stdin.read_to_string(&mut buffer) {
+        if bytes_read == 0 { return; }
+        write!(stdout, "{}", translate(&buffer)).unwrap();//TODO do this more efficiently (avoid format string)
+        buffer.truncate(0);//TODO is this needed here?
+    }
+}