Iterate Text

Library of helper functions and structures for iterating over text and files

---

• ⬆ Top of Document

• 🏗 Requirements

• ⚡ Quick Start

• 🧰 Usage

• 🔣 API

  • file::characters::IterateFileCharacters
  • file::lines::IterateFileLines
  • string::characters::IterateStringCharacters
  • string::lines::IterateStringLines

• 🗒 Notes

• 📈 Contributing

  • 🔱 Forking
  • 💱 Sponsor

• 📇 Attribution

• ⚖ Licensing

---

Requirements

This repository requires Rust language/compiler to build from source

As of last update to this ReadMe file, the recommended method of installing Rust is via the installer script...

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

---

Quick Start

This repository is a Rust library, define it as a dependency within a project Cargo.toml file...

Cargo.toml (snip)

[dependencies]
iterate-text = "0.0.1"

Check Rust -- Doc -- Specifying Dependencies for details about defining dependencies.

Then include within a source file via use statement...

src/main.rs (snip)

extern crate iterate_text;

use iterate_text::file::characters::IterateFileCharacters;
use iterate_text::file::lines::IterateFileLines;

use iterate_text::string::characters::IterateStringCharacters;
use iterate_text::string::lines::IterateStringLines;

---

Usage

Check the examples/ directory of this project for detailed usage examples.

src/main.rs

#!/usr/bin/env rust

use std::env;

extern crate iterate_text;
use iterate_text::file::lines::IterateFileLines;


fn main() {
    let args: Vec<String> = env::args().collect();

    let path = &args[1];
    let iter = IterateFileLines::new(path.into());

    let mut count = 0;
    for line in iter {
        count += 1;
        print!("{}: {}", count, line);
    }
}

---

API

Documentation for classes, methods, parameters, and custom types/data-structures

---

file::characters::IterateFileCharacters

Reads from path, buffer, or descriptor and iterates over characters until EOF is reached

Example

use iterate_text::file::characters::IterateFileCharacters;

let p = "tests/file/characters/file.txt";
let mut c = IterateFileCharacters::new(p);

assert_eq!(c.next(), Some('T'));
assert_eq!(c.next(), Some('h'));
assert_eq!(c.next(), Some('i'));
assert_eq!(c.next(), Some('s'));

---

file::lines::IterateFileLines

Reads from file path, buffer, or descriptor and iterates over lines until EOF is reached

use iterate_text::file::lines::IterateFileLines;

let p = "tests/file/lines/file.txt";
let mut l = IterateFileLines::new(p);

assert_eq!(l.next(), Some("First line\n".to_string()));
assert_eq!(l.next(), Some("Second line\n".to_string()));
assert_eq!(l.next(), Some("Third line\n".to_string()));
assert_eq!(l.next(), None);

---

string::characters::IterateStringCharacters

Iterates over characters within string

Example

use iterate_text::string::characters::IterateStringCharacters;

let s = String::from("test!");
let mut c = IterateStringCharacters::new(s);

assert_eq!(c.next(), Some('t'));
assert_eq!(c.next(), Some('e'));
assert_eq!(c.next(), Some('s'));
assert_eq!(c.next(), Some('t'));
assert_eq!(c.next(), Some('!'));
assert_eq!(c.next(), None);

---

string::lines::IterateStringLines

Iterates over lines within string and includes new-line separator

Example

use iterate_text::string::lines::IterateStringLines;

let s = String::from("This is\na \\n test string\n");
let mut l = IterateStringLines::new(s);

assert_eq!(l.next(), Some("This is\n".to_string()));
assert_eq!(l.next(), Some("a \\n test string\n".to_string()));
assert_eq!(l.next(), None);

---

Notes

The characters iterators currently use String.char_indices() which may split certain Unicode characters in unexpected ways.

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

---

Contributing

Options for contributing to iterate-text and rust-utilities

---

Forking

Start making a Fork of this repository to an account that you have write permissions for.

• Add remote for fork URL. The URL syntax is [email protected]:<NAME>/<REPO>.git...

mkdir -p ~/git/hub/rust-utilities

cd ~/git/hub/rust-utilities/iterate-text

git remote add fork [email protected]:<NAME>/iterate-text.git

• Ensure all tests pass

cargo test

• Run any examples by name

cargo run --example file-reader -- --file .github/README.md -c 10

• Commit your changes and push to your fork to fix an issue or add a feature...

cd ~/git/hub/rust-utilities/iterate-text


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

• Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

---

Sponsor

Thanks for even considering it!

Via Liberapay you may on a repeating basis.

Regardless of if you're able to financially support projects such as iterate-text that rust-utilities maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.

---

Attribution

• GitHub -- github-utilities/make-readme

• Matrix -- @kaplan offered suberb, and efficent, code that totally solved my Rust related issues

  • Rust Playground -- IterateFileChars
  • Matrix -- message #/room/#rust:matrix.org/$sERdrXYCkiVh_eITLzeA7tOsB2YsqnnkOV3a6fdNx6w

• Matrix -- @projectmoon had excelent instincts of owning line enabling character iteration

  • Matrix -- mesage #/room/#rust:matrix.org/$kXoPpn5bNQ_yjzq-sJiPsptzAYKQ8ZR0vMfbbgSaNcY

• Matrix -- @tanriol patently explained why code from @kaplan was so good, and answered my questions

  • Matrix -- message #/room/#rust:matrix.org/$_-SCswfFnfvwwkxcfFQXzsRSQfCVKnt2Wie1ct7dLGI

• Rust Doc -- Attributes

• Rust Doc -- Development dependencies

• Rust Doc -- Publishing on crates.io

• Specifying Dependencies

• StackOverflow -- How do I write a Rust unit test that ensures that a panic has occurred?

• StackOverflow -- How do I test a code in a sub-sub-directory?

---

License

Library of helper functions and structures for iterating over text and files
Copyright (C) 2021 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.