1 unstable release
0.0.1 | May 23, 2021 |
---|
#35 in #iterate
22KB
172 lines
Iterate Text
Library of helper functions and structures for iterating over text and files
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
git@github.com:<NAME>/<REPO>.git
...
mkdir -p ~/git/hub/rust-utilities
cd ~/git/hub/rust-utilities/iterate-text
git remote add fork git@github.com:<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 setfork
as the default remote, eg.git push -u fork main
however, this will also default thefork
remote for pulling from too! Meaning that pulling updates fromorigin
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
-
Matrix --
@kaplan
offered suberb, and efficent, code that totally solved my Rust related issues -
Matrix --
@projectmoon
had excelent instincts of owningline
enabling character iteration -
Matrix --
@tanriol
patently explained why code from@kaplan
was so good, and answered my questions -
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.