TxTodo

https://docs.rs/txtodo/latest/txtodo/
Admin
A library for parsing, serializing, and managing tasks in the todo.txt format. TxTodo provides a...
Tokens:70,283
Snippets:945
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Quick Start Example

Source: https://docs.rs/txtodo/latest/txtodo/index.html

Demonstrates the basic usage of the library to parse a todo.txt string into tasks and serialize them back to the todo.txt format.

```APIDOC
## Rust Usage Example

### Description
This example shows how to initialize a `TodoTxtParser` to parse a raw todo.txt string and a `TodoTxtSerializer` to convert the resulting tasks back into the todo.txt format.

### Code
```rust
let parser = TodoTxtParser::new();
let tasks = parser.parse_file("(A) 2024-01-15 Buy milk @home +shopping")?;
let serializer = TodoTxtSerializer::new();
let output = serializer.serialize_tasks(&tasks)?;
println!("{output}");
```
```

--------------------------------

### Usage examples for Priority

Source: https://docs.rs/txtodo/latest/txtodo/task/struct.Priority.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples demonstrating how to create a Priority instance from a token and verify its properties.

```rust
fn main() -> Result<(), TxtodoError> {
    let p = Priority::from_token("(A)")?;
    assert_eq!(p.as_char(), 'A');
    assert_eq!(p.to_string(), "(A)");
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let p = Priority::from_token("(C)")?;
    assert_eq!(p.as_char(), 'C');
    Ok(())
}
```

--------------------------------

### Initialize TodoOptions

Source: https://docs.rs/txtodo/latest/txtodo/options/struct.TodoOptions.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example showing how to manually instantiate the TodoOptions struct.

```rust
let opts = TodoOptions {
    file_path: Some("todo.txt".into()),
    auto_save: true,
    extensions: Vec::new(),
    handle_subtasks: true,
};
```

--------------------------------

### TodoTxt::new

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=u32+-%3E+bool

Creates a new TodoTxt instance from the provided TodoOptions. The instance starts with an empty task list.

```APIDOC
## pub fn new(options: TodoOptions) -> Result<Self, TxtodoError>

### Description
Creates a new `TodoTxt` instance from the given `TodoOptions`. The returned instance has an empty task list; call `load` to populate it from a file.

### Parameters
- **options** (TodoOptions) - Required - The configuration options for the TodoTxt instance.

### Errors
Returns `TxtodoError` if the configured extensions fail to initialise.
```

--------------------------------

### TodoTxt::new

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=

Creates a new TodoTxt instance from the provided TodoOptions. The instance starts with an empty task list.

```APIDOC
## pub fn new(options: TodoOptions) -> Result<Self, TxtodoError>

### Description
Creates a new `TodoTxt` instance from the given `TodoOptions`. The returned instance has an empty task list.

### Parameters
- **options** (TodoOptions) - Required - Configuration options for the TodoTxt instance.

### Errors
Returns `TxtodoError` if the configured extensions fail to initialise.
```

--------------------------------

### Arc::clone_from_ref Example

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.SerializingFn.html

Demonstrates constructing an Arc from a reference using the nightly-only experimental API.

```rust
#![feature(clone_from_ref)]
use std::sync::Arc;

let hello: Arc<str> = Arc::clone_from_ref("hello");
```

--------------------------------

### resolve_index Usage Examples

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/fn.resolve_index.html

Demonstrates how to resolve positive and negative indices, including boundary conditions.

```rust
assert_eq!(resolve_index(2, 5).unwrap(), 2);
assert_eq!(resolve_index(-1, 5).unwrap(), 4);
assert_eq!(resolve_index(-5, 5).unwrap(), 0);
assert!(resolve_index(5, 5).is_err());
```

--------------------------------

### Apply a partial update to a task

Source: https://docs.rs/txtodo/latest/txtodo/task/struct.TaskPatch.html

Example showing how to initialize a TaskPatch to update a description and clear a priority field.

```rust
fn main() -> Result<(), TxtodoError> {
    let patch = TaskPatch {
        description: Some("buy milk".into()),
        priority: Some(None), // clear priority
        ..Default::default()
    };
    Ok(())
}
```

--------------------------------

### Arc::try_clone_from_ref Example

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.SerializingFn.html

Demonstrates constructing an Arc from a reference with error handling for allocation failures.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::sync::Arc;

let hello: Arc<str> = Arc::try_clone_from_ref("hello")?;
```

--------------------------------

### Parse priority from token

Source: https://docs.rs/txtodo/latest/txtodo/task/struct.Priority.html

Example of parsing a priority token using the from_token method.

```rust
fn main() -> Result<(), TxtodoError> {
    let p = Priority::from_token("(C)")?;
    assert_eq!(p.as_char(), 'C');
    Ok(())
}
```

--------------------------------

### TaskFilters usage examples

Source: https://docs.rs/txtodo/latest/txtodo/filters/struct.TaskFilters.html?search=

Basic usage of TaskFilters factory methods to create filter closures.

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::completed();
    let ctx_filter = TaskFilters::by_context("work");
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::by_context("work");
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::by_contexts(&["work", "office"]);
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::by_project("txtodo");
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::by_projects(&["txtodo", "backend"]);
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::by_priority(Priority('A'));
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::by_priorities(&[
        Priority('A'),
        Priority('B'),
    ]);
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::by_completion_status(true);
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::by_extension_field("due", None);
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::by_extension_fields(&[]);
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::completed();
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::incomplete();
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::has_priority();
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::no_priority();
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::has_context();
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::no_context();
    Ok(())
}
```

```rust
fn main() -> Result<(), TxtodoError> {
    let filter = TaskFilters::has_project();
    Ok(())
}
```

--------------------------------

### Handling TxtodoError

Source: https://docs.rs/txtodo/latest/txtodo/error/enum.TxtodoError.html?search=

Example of matching on a result and verifying the presence of a machine-readable error code.

```rust
fn main() -> Result<(), TxtodoError> {
    let parser = TodoTxtParser::new();
    match parser.parse_file("bad line with invalid date 9999-99-99") {
        Ok(_) => Ok(()),
        Err(e) => {
            assert!(!e.code().is_empty());
            Ok(())
        }
    }
}
```

--------------------------------

### Add Task to TodoTxt

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/enum.TaskInput.html?search=

Example usage of adding a task to a TodoTxt instance using a raw string, which is automatically converted to TaskInput.

```rust
use txtodo::*;
let options = TodoOptions::default();
let mut todo = TodoTxt::new(options)?;
todo.add("(A) Buy milk @home")?;      // from &str
```

--------------------------------

### Rc::weak_count

Source: https://docs.rs/txtodo/latest/txtodo/sorts/type.TaskSorter.html?search=std%3A%3Avec

Gets the number of Weak pointers to the allocation.

```APIDOC
## pub fn weak_count(this: &Rc<T, A>) -> usize

### Description
Gets the number of `Weak` pointers to this allocation.
```

--------------------------------

### Initialize and Manage Tasks with TodoTxt

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Demonstrates the basic lifecycle of a TodoTxt instance, including configuration, loading from a file, adding a task, and listing tasks.

```rust
use txtodo::*;

fn main() -> Result<(), TxtodoError> {
    let options = TodoOptions {
        file_path: Some("todo.txt".into()),
        ..Default::default()
    };
    let mut todo = TodoTxt::new(options)?;
    todo.load(None)?;
    todo.add("(A) Write docs @work")?;
    let tasks = todo.list();
    println!("{} tasks loaded", tasks.len());
    Ok(())
}
```

--------------------------------

### Arc::weak_count

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.ParsingFn.html

Gets the number of Weak pointers to this allocation.

```APIDOC
## pub fn weak_count(this: &Arc<T, A>) -> usize

### Description
Gets the number of `Weak` pointers to this allocation. Note that another thread can change the weak count at any time.
```

--------------------------------

### Arc::strong_count

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.ParsingFn.html

Gets the number of strong (Arc) pointers to this allocation.

```APIDOC
## pub fn strong_count(this: &Arc<T, A>) -> usize

### Description
Gets the number of strong (`Arc`) pointers to this allocation. Note that another thread can change the strong count at any time.
```

--------------------------------

### Create a new TodoTxtExtension

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.TodoTxtExtension.html

Initialize a new extension with a specific key using default settings.

```rust
use txtodo::*;

fn main() -> Result<(), TxtodoError> {
    let ext = TodoTxtExtension::new("due");
    assert_eq!(ext.key, "due");
    Ok(())
}
```

--------------------------------

### Create a New TodoTxt Instance

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Shows how to instantiate a new TodoTxt object using default options.

```rust
use txtodo::*;
let options = TodoOptions::default();
let todo = TodoTxt::new(options)?;
assert!(todo.list().is_empty());
```

--------------------------------

### Registering and verifying extensions

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.ExtensionHandler.html?search=

Demonstrates adding multiple extensions to the handler and verifying their presence.

```rust
use txtodo::*;

fn main() -> Result<(), TxtodoError> {
    let mut handler = ExtensionHandler::new();
    handler.add_extension(TodoTxtExtension::new("due"))?;
    handler.add_extension(TodoTxtExtension::new("pri"))?;
    assert!(handler.has_extension("due"));
    assert_eq!(handler.all_extensions().len(), 2);
    Ok(())
}
```

--------------------------------

### pub fn weak_count(this: &Rc<T, A>) -> usize

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html?search=

Gets the number of Weak pointers to this allocation.

```APIDOC
## pub fn weak_count(this: &Rc<T, A>) -> usize

### Description
Gets the number of `Weak` pointers to this allocation.

### Parameters
- **this** (&Rc<T, A>) - Required - The Rc pointer to check.
```

--------------------------------

### TodoTxt::new

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=std%3A%3Avec

Creates a new TodoTxt instance from the provided TodoOptions.

```APIDOC
## pub fn new(options: TodoOptions) -> Result<Self, TxtodoError>

### Description
Creates a new `TodoTxt` instance. The returned instance has an empty task list; call `load` to populate it.

### Parameters
- **options** (TodoOptions) - Required - Configuration options for the TodoTxt instance.

### Returns
- **Result<Self, TxtodoError>** - Returns the new instance or an error if extensions fail to initialize.
```

--------------------------------

### Use SortDirection in Task Sorting

Source: https://docs.rs/txtodo/latest/txtodo/sorts/enum.SortDirection.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of applying a sort direction when configuring a task sorter.

```rust
fn main() -> Result<(), TxtodoError> {
    let sorter = TaskSorts::by_description(SortDirection::Asc);
    Ok(())
}
```

--------------------------------

### TodoTxt::new

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Creates a new TodoTxt instance from the provided TodoOptions.

```APIDOC
## pub fn new(options: TodoOptions) -> Result<Self, TxtodoError>

### Description
Creates a new `TodoTxt` instance. The returned instance has an empty task list; call `load` to populate it from a file.

### Errors
Returns `TxtodoError` if the configured extensions fail to initialise.
```

--------------------------------

### TodoTxt::new

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new TodoTxt instance from the provided TodoOptions.

```APIDOC
## pub fn new(options: TodoOptions) -> Result<Self, TxtodoError>

### Description
Creates a new TodoTxt instance. The returned instance has an empty task list; call load() to populate it from a file.

### Parameters
- **options** (TodoOptions) - Required - Configuration options for the TodoTxt instance.

### Errors
Returns TxtodoError if the configured extensions fail to initialize.
```

--------------------------------

### TodoTxtExtension::new

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.TodoTxtExtension.html?search=u32+-%3E+bool

Creates a new extension instance with the specified key.

```APIDOC
## pub fn new(key: impl Into<String>) -> Self

### Description
Creates a new extension with the given key. By default, inherit and shadow are both true, and no custom parser or serializer is set (auto-detection is used).
```

--------------------------------

### pub fn strong_count(this: &Rc<T, A>) -> usize

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html?search=

Gets the number of strong (Rc) pointers to this allocation.

```APIDOC
## pub fn strong_count(this: &Rc<T, A>) -> usize

### Description
Gets the number of strong (`Rc`) pointers to this allocation.

### Parameters
- **this** (&Rc<T, A>) - Required - The Rc pointer to check.
```

--------------------------------

### TodoTxtExtension::new

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.TodoTxtExtension.html?search=

Creates a new extension instance with the specified key. By default, inherit and shadow are enabled.

```APIDOC
## pub fn new(key: impl Into<String>) -> Self

### Description
Creates a new extension with the given key. By default, inherit and shadow are both true, and no custom parser or serializer is set (auto-detection is used).

### Parameters
- **key** (impl Into<String>) - Required - The extension key as it appears in todo.txt lines.
```

--------------------------------

### Get weak reference count

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html

Returns the number of Weak pointers currently pointing to the allocation.

```rust
use std::rc::Rc;

let five = Rc::new(5);
let _weak_five = Rc::downgrade(&five);

assert_eq!(1, Rc::weak_count(&five));
```

--------------------------------

### Load Tasks from File

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Demonstrates loading tasks into a TodoTxt instance from a configured file path.

```rust
use txtodo::*;
let options = TodoOptions {
    file_path: Some("todo.txt".into()),
    ..Default::default()
};
let mut todo = TodoTxt::new(options)?;
todo.load(None)?;
```

--------------------------------

### Get strong reference count

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html

Returns the number of strong Rc pointers currently pointing to the allocation.

```rust
use std::rc::Rc;

let five = Rc::new(5);
let _also_five = Rc::clone(&five);

assert_eq!(2, Rc::strong_count(&five));
```

--------------------------------

### TodoTxtExtension::new

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.TodoTxtExtension.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new extension instance with the specified key. By default, inheritance and shadowing are enabled.

```APIDOC
## pub fn new(key: impl Into<String>) -> Self

### Description
Creates a new extension with the given `key`. By default `inherit` and `shadow` are both `true`, and no custom parser or serializer is set (auto-detection is used).
```

--------------------------------

### Parse and Serialize todo.txt Tasks

Source: https://docs.rs/txtodo/latest/txtodo/index.html

Demonstrates the basic workflow of initializing a parser, parsing a task string, and serializing the resulting task objects back to the todo.txt format.

```rust
let parser = TodoTxtParser::new();
let tasks = parser.parse_file("(A) 2024-01-15 Buy milk @home +shopping")?;
let serializer = TodoTxtSerializer::new();
let output = serializer.serialize_tasks(&tasks)?;
println!("{output}");
```

--------------------------------

### TodoTxtExtension::new

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.TodoTxtExtension.html

Creates a new extension instance with the specified key. By default, inherit and shadow are set to true, and auto-detection is used for values.

```APIDOC
## pub fn new(key: impl Into<String>) -> Self

### Description
Creates a new extension with the given key. By default, inherit and shadow are both true, and no custom parser or serializer is set.

### Parameters
- **key** (impl Into<String>) - Required - The extension key as it appears in todo.txt lines.
```

--------------------------------

### Arc::new

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.SerializingFn.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs a new Arc<T> instance.

```APIDOC
## pub fn new(data: T) -> Arc<T>

### Description
Constructs a new `Arc<T>`.

### Parameters
- **data** (T) - The value to be wrapped in the Arc.
```

--------------------------------

### Try clone Rc from reference

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html

Demonstrates constructing an Rc from a reference with error handling for allocation failures.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::rc::Rc;

let hello: Rc<str> = Rc::try_clone_from_ref("hello")?;
```

--------------------------------

### TodoTxt::load

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Loads tasks from a todo.txt file.

```APIDOC
## pub fn load(&mut self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Loads tasks from a todo.txt file. If `file_path` is provided, it is used; otherwise, the path configured at construction is used.

### Errors
Returns `TxtodoError` if the file cannot be read or the content cannot be parsed.
```

--------------------------------

### Creating a new ExtensionHandler

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.ExtensionHandler.html?search=

Initializes an empty handler with no registered extensions.

```rust
use txtodo::*;

fn main() -> Result<(), TxtodoError> {
    let handler = ExtensionHandler::new();
    assert!(handler.all_extensions().is_empty());
    Ok(())
}
```

--------------------------------

### Clone Rc from reference

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html

Demonstrates constructing an Rc from a reference using the experimental clone_from_ref feature.

```rust
#![feature(clone_from_ref)]
use std::rc::Rc;

let hello: Rc<str> = Rc::clone_from_ref("hello");
```

--------------------------------

### TodoTxt::load

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Loads tasks from a todo.txt file into the TodoTxt instance.

```APIDOC
## pub fn load(&mut self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Loads tasks from a file. If file_path is provided, it is used; otherwise, the path configured at construction is used.

### Parameters
- **file_path** (Option<&str>) - Optional - The path to the todo.txt file.
```

--------------------------------

### TodoTxt::load

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=u32+-%3E+bool

Loads tasks from a todo.txt file into the TodoTxt instance.

```APIDOC
## pub fn load(&mut self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Loads tasks from a todo.txt file. If `file_path` is provided, it is used; otherwise, the path configured at construction is used.

### Parameters
- **file_path** (Option<&str>) - Optional - The path to the todo.txt file to load.

### Errors
Returns `TxtodoError` if the file cannot be read or the content cannot be parsed.
```

--------------------------------

### TodoTxt::load

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=

Loads tasks from a todo.txt file into the TodoTxt instance.

```APIDOC
## pub fn load(&mut self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Loads tasks from a todo.txt file. If `file_path` is provided, it is used; otherwise, the path configured at construction is used.

### Parameters
- **file_path** (Option<&str>) - Optional - The path to the todo.txt file.

### Errors
Returns `TxtodoError` if the file cannot be read or the content cannot be parsed.
```

--------------------------------

### TodoTxt::load

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=std%3A%3Avec

Loads tasks from a todo.txt file into the TodoTxt instance.

```APIDOC
## pub fn load(&mut self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Loads tasks from a file. If `file_path` is provided, it is used; otherwise, the path configured at construction is used.

### Parameters
- **file_path** (Option<&str>) - Optional - The path to the todo.txt file.
```

--------------------------------

### TodoTxtParser::new

Source: https://docs.rs/txtodo/latest/txtodo/parser/struct.TodoTxtParser.html

Creates a new instance of the parser with default settings, including enabled subtask handling and no custom extensions.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new parser with default settings (no extensions, subtasks enabled).
```

--------------------------------

### Listing all extensions

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.ExtensionHandler.html?search=

Returns a vector containing references to all registered extensions.

```rust
use txtodo::*;

fn main() -> Result<(), TxtodoError> {
    let mut handler = ExtensionHandler::new();
    handler.add_extension(TodoTxtExtension::new("due"))?;
    handler.add_extension(TodoTxtExtension::new("pri"))?;
    let all = handler.all_extensions();
    assert_eq!(all.len(), 2);
    Ok(())
}
```

--------------------------------

### Retrieving an extension

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.ExtensionHandler.html?search=

Fetches a reference to a registered extension by its key.

```rust
use txtodo::*;

fn main() -> Result<(), TxtodoError> {
    let mut handler = ExtensionHandler::new();
    handler.add_extension(TodoTxtExtension::new("due"))?;
    let ext = handler.get_extension("due");
    assert!(ext.is_some());
    assert_eq!(ext.unwrap().key, "due");
    Ok(())
}
```

--------------------------------

### Parse a todo.txt file

Source: https://docs.rs/txtodo/latest/txtodo/parser/struct.TodoTxtParser.html

Demonstrates parsing a full string containing todo.txt content into a list of tasks.

```rust
let parser = TodoTxtParser::new();
let tasks = parser.parse_file("(A) 2024-01-15 Buy milk @home +shopping")?;
assert_eq!(tasks.len(), 1);
assert!(tasks[0].description.contains("Buy milk"));
```

--------------------------------

### TodoTxtSerializer::new

Source: https://docs.rs/txtodo/latest/txtodo/serializer/struct.TodoTxtSerializer.html?search=std%3A%3Avec

Creates a new serializer with default settings (no extensions).

```APIDOC
### pub fn new() -> Self

Creates a new serializer with default settings (no extensions).
```

--------------------------------

### ExtensionHandler::new

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.ExtensionHandler.html

Creates a new, empty ExtensionHandler instance.

```APIDOC
## pub fn new() -> Self

### Description
Creates an empty extension handler with no registered extensions.

### Signature
`pub fn new() -> Self`
```

--------------------------------

### Adding an extension

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.ExtensionHandler.html?search=

Registers a new extension. The key must be non-empty and unique.

```rust
use txtodo::*;

fn main() -> Result<(), TxtodoError> {
    let mut handler = ExtensionHandler::new();
    handler.add_extension(TodoTxtExtension::new("due"))?;
    assert!(handler.has_extension("due"));
    Ok(())
}
```

--------------------------------

### TodoTxtSerializer::new

Source: https://docs.rs/txtodo/latest/txtodo/serializer/struct.TodoTxtSerializer.html?search=

Creates a new instance of the TodoTxtSerializer with default settings, meaning no custom extensions are configured.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new serializer with default settings (no extensions).
```

--------------------------------

### Constructing Rc with custom allocators

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html

Nightly-only APIs for creating Rc instances using specific allocators.

```rust
#![feature(allocator_api)]

use std::rc::Rc;
use std::alloc::System;

let five = Rc::new_in(5, System);
```

```rust
#![feature(get_mut_unchecked)]
#![feature(allocator_api)]

use std::rc::Rc;
use std::alloc::System;

let mut five = Rc::<u32, _>::new_uninit_in(System);

let five = unsafe {
    // Deferred initialization:
    Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5)
```

```rust
#![feature(allocator_api)]

use std::rc::Rc;
use std::alloc::System;

let zero = Rc::<u32, _>::new_zeroed_in(System);
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

--------------------------------

### add

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=u32+-%3E+bool

Adds a single task to the list. Accepts anything that implements Into<TaskInput>.

```APIDOC
## pub fn add(&mut self, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

### Description
Adds a single task to the list. If subtask handling is enabled, the task is inserted into the tree at the correct position based on its indent level.

### Parameters
- **input** (impl Into<TaskInput>) - Required - The task to add, which can be a &str, String, or Task.

### Errors
Returns TxtodoError if the input cannot be parsed or auto-save is enabled and the file cannot be written.
```

--------------------------------

### add

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=std%3A%3Avec

Adds a single task to the list. Accepts anything that implements Into<TaskInput>.

```APIDOC
## pub fn add(&mut self, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

### Description
Adds a single task to the list. If subtask handling is enabled, the task is inserted into the tree at the correct position based on its indent level.

### Errors
Returns TxtodoError if the input cannot be parsed or auto-save is enabled and the file cannot be written.
```

--------------------------------

### ExtensionHandler::all_extensions

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.ExtensionHandler.html

Retrieves all registered extensions.

```APIDOC
## pub fn all_extensions(&self) -> Vec<&TodoTxtExtension>

### Description
Returns references to all registered extensions.
```

--------------------------------

### Arc::new_uninit

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.ParsingFn.html?search=std%3A%3Avec

Constructs a new Arc with uninitialized contents.

```APIDOC
## pub fn new_uninit() -> Arc<MaybeUninit<T>>

### Description
Constructs a new `Arc` with uninitialized contents. The caller is responsible for initializing the memory before accessing it.
```

--------------------------------

### Save Tasks to File

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Shows how to persist the current task list to the configured file path.

```rust
use txtodo::*;
let options = TodoOptions {
    file_path: Some("todo.txt".into()),
    ..Default::default()
};
let mut todo = TodoTxt::new(options)?;
todo.load(None)?;
todo.save(None)?;
```

--------------------------------

### Use Priority with from_token

Source: https://docs.rs/txtodo/latest/txtodo/task/struct.Priority.html

Demonstrates parsing a priority from a token and verifying its properties.

```rust
fn main() -> Result<(), TxtodoError> {
    let p = Priority::from_token("(A)")?;
    assert_eq!(p.as_char(), 'A');
    assert_eq!(p.to_string(), "(A)");
    Ok(())
}
```

--------------------------------

### TodoTxt::list

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Returns all tasks as a flat list.

```APIDOC
## pub fn list(&self) -> Vec<&Task>

### Description
Returns all tasks (including subtasks) as a flat list in pre-order depth-first order.
```

--------------------------------

### Sort tasks by project

Source: https://docs.rs/txtodo/latest/txtodo/sorts/struct.TaskSorts.html?search=u32+-%3E+bool

Sorts tasks alphabetically by their project tags.

```rust
fn main() -> Result<(), TxtodoError> {
    let sort = TaskSorts::by_project(SortDirection::Asc);
    Ok(())
}
```

--------------------------------

### TodoTxtParser::with_handler

Source: https://docs.rs/txtodo/latest/txtodo/parser/struct.TodoTxtParser.html?search=std%3A%3Avec

Creates a new instance of the TodoTxtParser with a custom ExtensionHandler.

```APIDOC
## pub fn with_handler(handler: ExtensionHandler) -> Self

### Description
Creates a new parser with a custom ExtensionHandler. Subtask handling is enabled by default.
```

--------------------------------

### TodoTxt::list

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=u32+-%3E+bool

Returns all tasks as a flat list in pre-order depth-first order.

```APIDOC
## pub fn list(&self) -> Vec<&Task>

### Description
Returns all tasks (including subtasks) as a flat list. The list is in pre-order depth-first order: a parent appears before its subtasks.
```

--------------------------------

### Compare Arc values

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.SerializingFn.html

Demonstrates partial comparison and relational operators for Arc instances.

```rust
use std::sync::Arc;
use std::cmp::Ordering;

let five = Arc::new(5);

assert_eq!(Some(Ordering::Less), five.partial_cmp(&Arc::new(6)));
```

```rust
use std::sync::Arc;

let five = Arc::new(5);

assert!(five < Arc::new(6));
```

```rust
use std::sync::Arc;

let five = Arc::new(5);

assert!(five <= Arc::new(5));
```

```rust
use std::sync::Arc;

let five = Arc::new(5);

assert!(five > Arc::new(4));
```

```rust
use std::sync::Arc;

let five = Arc::new(5);

assert!(five >= Arc::new(5));
```

--------------------------------

### pub fn add(&mut self, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=

Adds a single task to the list. Accepts anything that implements Into<TaskInput>, including &str, String, and Task.

```APIDOC
## pub fn add(&mut self, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

### Description
Adds a single task to the list. If subtask handling is enabled, the task is inserted into the tree at the correct position based on its indent level.

### Parameters
- **input** (impl Into<TaskInput>) - Required - The task input to add (e.g., &str, String, or Task).

### Errors
Returns TxtodoError if the input cannot be parsed or auto-save is enabled and the file cannot be written.
```

--------------------------------

### TodoTxtParser::with_handler

Source: https://docs.rs/txtodo/latest/txtodo/parser/struct.TodoTxtParser.html

Creates a new parser instance configured with a custom ExtensionHandler.

```APIDOC
## pub fn with_handler(handler: ExtensionHandler) -> Self

### Description
Creates a new parser with a custom `ExtensionHandler`. Subtask handling is enabled by default.
```

--------------------------------

### TodoTxtSerializer::with_handler

Source: https://docs.rs/txtodo/latest/txtodo/serializer/struct.TodoTxtSerializer.html?search=

Creates a new instance of the TodoTxtSerializer configured with a specific ExtensionHandler.

```APIDOC
## pub fn with_handler(handler: ExtensionHandler) -> Self

### Description
Creates a new serializer with a custom `ExtensionHandler`.
```

--------------------------------

### pub fn insert(&mut self, index: i64, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=

Inserts a task at the given position in the flat task list.

```APIDOC
## pub fn insert(&mut self, index: i64, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

### Description
Inserts a task at the given position in the flat task list. Negative indices count from the end of the list. If the index is beyond the end, the task is appended.

### Parameters
- **index** (i64) - Required - The position to insert the task.
- **input** (impl Into<TaskInput>) - Required - The task input to insert.

### Errors
Returns TxtodoError if the input cannot be parsed or auto-save is enabled and the file cannot be written.
```

--------------------------------

### Combine Task Sorters

Source: https://docs.rs/txtodo/latest/txtodo/sorts/struct.TaskSorts.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates creating a primary sort and combining it with a secondary sort using the then method.

```rust
fn main() -> Result<(), TxtodoError> {
    let sort = TaskSorts::by_priority(SortDirection::Asc);
    let multi = TaskSorts::then(&sort, &TaskSorts::by_description(SortDirection::Asc));
    Ok(())
}
```

--------------------------------

### Creating a new Arc

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.SerializingFn.html

Allocates a new Arc on the heap.

```rust
use std::sync::Arc;

let five = Arc::new(5);
```

--------------------------------

### Define a TodoTxtExtension

Source: https://docs.rs/txtodo/latest/txtodo/extension/struct.TodoTxtExtension.html

Create and register a new extension with specific inheritance and shadowing behaviors.

```rust
use txtodo::*;
use std::sync::Arc;

fn main() -> Result<(), TxtodoError> {
    let ext = TodoTxtExtension::new("pri")
        .inherit(false)
        .shadow(true);

    let mut handler = ExtensionHandler::new();
    handler.add_extension(ext)?;
    assert!(handler.has_extension("pri"));
    Ok(())
}
```

--------------------------------

### pub fn insert(&mut self, index: i64, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Inserts a task at a specific position in the flat task list.

```APIDOC
## pub fn insert(&mut self, index: i64, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

### Description
Inserts a task at the given position in the flat task list. Negative indices count from the end of the list.
```

--------------------------------

### Rc::as_ptr

Source: https://docs.rs/txtodo/latest/txtodo/sorts/type.TaskSorter.html?search=std%3A%3Avec

Provides a raw pointer to the data.

```APIDOC
## Rc::as_ptr

### Description
Provides a raw pointer to the data. The counts are not affected in any way and the Rc is not consumed. The pointer is valid for as long as there are strong counts in the Rc.

### Signature
pub fn as_ptr(this: &Rc<T, A>) -> *const T
```

--------------------------------

### List Tasks

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Retrieves a flat list of all tasks currently managed by the instance.

```rust
use txtodo::*;
let options = TodoOptions::default();
let mut todo = TodoTxt::new(options)?;
todo.add("Buy groceries")?;
assert_eq!(todo.list().len(), 1);
```

--------------------------------

### Rc::into_raw_with_allocator

Source: https://docs.rs/txtodo/latest/txtodo/sorts/type.TaskSorter.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Consumes the Rc and returns the wrapped pointer and the allocator.

```APIDOC
## Rc::into_raw_with_allocator

### Description
Consumes the Rc, returning the wrapped pointer and the allocator. The pointer must be converted back to an Rc using `Rc::from_raw_in` to avoid memory leaks.

### Signature
`pub fn into_raw_with_allocator(this: Rc<T, A>) -> (*const T, A)`

### Notes
- This is a nightly-only experimental API (`allocator_api`).
```

--------------------------------

### Try clone Rc from reference with allocator

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html?search=u32+-%3E+bool

Attempts to construct an Rc from a reference using a specific allocator, returning an error on failure. Requires allocator_api and clone_from_ref features.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::rc::Rc;
use std::alloc::System;

let hello: Rc<str, System> = Rc::try_clone_from_ref_in("hello", System)?;
```

--------------------------------

### Sort tasks by description

Source: https://docs.rs/txtodo/latest/txtodo/sorts/struct.TaskSorts.html?search=u32+-%3E+bool

Sorts tasks alphabetically by their description text.

```rust
fn main() -> Result<(), TxtodoError> {
    let sort = TaskSorts::by_description(SortDirection::Asc);
    Ok(())
}
```

--------------------------------

### Rc::into_raw_with_allocator

Source: https://docs.rs/txtodo/latest/txtodo/sorts/type.TaskSorter.html?search=std%3A%3Avec

Consumes the Rc, returning the wrapped pointer and allocator.

```APIDOC
## Rc::into_raw_with_allocator

### Description
Consumes the Rc, returning the wrapped pointer and allocator. To avoid a memory leak the pointer must be converted back to an Rc using Rc::from_raw_in.

### Signature
pub fn into_raw_with_allocator(this: Rc<T, A>) -> (*const T, A)
```

--------------------------------

### Creating uninitialized Rc pointers

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html?search=u32+-%3E+bool

new_uninit and new_zeroed allow for deferred initialization of Rc-managed memory.

```rust
use std::rc::Rc;

let mut five = Rc::<u32>::new_uninit();

// Deferred initialization:
Rc::get_mut(&mut five).unwrap().write(5);

let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

```rust
use std::rc::Rc;

let zero = Rc::<u32>::new_zeroed();
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

--------------------------------

### pub fn add(&mut self, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Adds a single task to the list. Accepts various input types and handles subtask tree insertion if enabled.

```APIDOC
## pub fn add(&mut self, input: impl Into<TaskInput>) -> Result<(), TxtodoError>

### Description
Adds a single task to the list. Accepts anything that implements `Into<TaskInput>`, including `&str`, `String`, and `Task`.
```

--------------------------------

### TodoTxt::save

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=u32+-%3E+bool

Saves the current task list to a todo.txt file.

```APIDOC
## pub fn save(&self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Saves the current task list to a todo.txt file. If `file_path` is provided, it is used; otherwise, the path configured at construction is used.

### Parameters
- **file_path** (Option<&str>) - Optional - The path to the file where tasks should be saved.

### Errors
Returns `TxtodoError` if no file path is available, tasks cannot be serialised, or the file cannot be written.
```

--------------------------------

### TodoTxt::save

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=

Saves the current task list to a todo.txt file.

```APIDOC
## pub fn save(&self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Saves the current task list to a todo.txt file. If `file_path` is provided, it is used; otherwise, the path configured at construction is used.

### Parameters
- **file_path** (Option<&str>) - Optional - The path to the todo.txt file.

### Errors
Returns `TxtodoError` if no file path is available, the tasks cannot be serialised, or the file cannot be written.
```

--------------------------------

### TodoTxt::save

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=std%3A%3Avec

Saves the current task list to a todo.txt file.

```APIDOC
## pub fn save(&self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Persists the current task list to disk.

### Parameters
- **file_path** (Option<&str>) - Optional - The destination file path.
```

--------------------------------

### TodoTxt::save

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html

Saves the current task list to a todo.txt file.

```APIDOC
## pub fn save(&self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Saves the current task list to a todo.txt file. If `file_path` is provided, it is used; otherwise, the path configured at construction is used.

### Errors
Returns `TxtodoError` if no file path is available, the tasks cannot be serialised, or the file cannot be written.
```

--------------------------------

### TodoTxt::save

Source: https://docs.rs/txtodo/latest/txtodo/todotxt/struct.TodoTxt.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Saves the current task list to a todo.txt file.

```APIDOC
## pub fn save(&self, file_path: Option<&str>) -> Result<(), TxtodoError>

### Description
Persists the current task list to disk. If file_path is provided, it is used; otherwise, the path configured at construction is used.

### Parameters
- **file_path** (Option<&str>) - Optional - The path to save the tasks to.
```

--------------------------------

### Arc::from_raw_in

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.SerializingFn.html?search=std%3A%3Avec

Constructs an Arc<T, A> from a raw pointer. This is an experimental nightly-only API.

```APIDOC
## pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Arc<T, A>

### Description
Constructs an `Arc<T, A>` from a raw pointer. The raw pointer must have been previously returned by a call to `Arc<U, A>::into_raw` or `Arc<U, A>::into_raw_with_allocator`.

### Safety
- Creating an `Arc` from an invalid pointer is undefined behavior.
- The pointer must point to a block of memory allocated by `alloc`.
- The user must ensure a specific value of `T` is only dropped once.
```

--------------------------------

### Arc::new_uninit_in

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.ParsingFn.html

Constructs a new Arc with uninitialized contents in the provided allocator.

```APIDOC
## pub fn new_uninit_in(alloc: A) -> Arc<MaybeUninit<T>, A>

### Description
Constructs a new `Arc` with uninitialized contents in the provided allocator. This is a nightly-only experimental API.
```

--------------------------------

### Arc::new_in

Source: https://docs.rs/txtodo/latest/txtodo/extension/type.ParsingFn.html?search=std%3A%3Avec

Constructs a new Arc in the provided allocator. This is a nightly-only experimental API.

```APIDOC
## pub fn new_in<T, A>(data: T, alloc: A) -> Arc<T, A>

### Description
Constructs a new `Arc<T>` using the provided allocator `A`.
```

--------------------------------

### TodoTxtSerializer::with_handler

Source: https://docs.rs/txtodo/latest/txtodo/serializer/struct.TodoTxtSerializer.html?search=std%3A%3Avec

Creates a new serializer with a custom ExtensionHandler.

```APIDOC
### pub fn with_handler(handler: ExtensionHandler) -> Self

Creates a new serializer with a custom `ExtensionHandler`.
```

--------------------------------

### pub fn downgrade(this: &Rc<T, A>) -> Weak<T, A>

Source: https://docs.rs/txtodo/latest/txtodo/filters/type.TaskFilter.html?search=

Creates a new Weak pointer to this allocation.

```APIDOC
## pub fn downgrade(this: &Rc<T, A>) -> Weak<T, A>

### Description
Creates a new `Weak` pointer to this allocation.

### Parameters
- **this** (&Rc<T, A>) - Required - The Rc pointer to downgrade.
```
Tokens:
Raw