RFP - Add Line and Fragment Extraction Functions to Text Module

[sphilipakis]

RFP: Add Line and Fragment Extraction Functions to Text Module

Overview

Add new utility functions to the text module in rhai to enable easy extraction of first/last lines and fragments from text content. These functions will complement the existing text manipulation capabilities.

Motivation

These additions would provide developers with essential text parsing capabilities that are commonly needed when processing structured text content. The functions would enable:

• Easy extraction of header/footer lines
• Simple parsing of delimited text content
• More granular control over text processing workflows
• Better handling of formatted text outputs from various sources

Proposed Implementation Details

Add four new functions to the text module:

Line Functions

1. text::first_line(content: string) -> string

   • Returns the first line of the input string
   • Returns empty string if input is empty
   • Includes line content up to but not including the newline character

2. text::last_line(content: string) -> string

   • Returns the last line of the input string
   • Returns empty string if input is empty
   • Returns the entire string if no newline is found

Fragment Functions

3. text::first_fragment(content: string, separator: string) -> string

   • Returns the first non-empty fragment before the separator
   • Returns empty string if no non-empty fragment is found
   • Trims whitespace from the fragment before returning

4. text::last_fragment(content: string, separator: string) -> string

   • Returns the last non-empty fragment after the last separator
   • Returns empty string if no non-empty fragment is found
   • Trims whitespace from the fragment before returning

Example Usage

let text = "First line\nMiddle line\nLast line";
let first = text::first_line(text); // Returns "First line"
let last = text::last_line(text);   // Returns "Last line"

let path = "home/user/documents/file.txt";
let filename = text::last_fragment(path, "/");  // Returns "file.txt"
let root = text::first_fragment(path, "/");     // Returns "home"

let csv = "item1,item2,,item3";
let first_item = text::first_fragment(csv, ","); // Returns "item1"
let last_item = text::last_fragment(csv, ",");   // Returns "item3"

Implementation Notes

• All functions should handle edge cases gracefully (empty strings, missing separators)
• Fragment functions should ignore empty fragments between separators
• Whitespace handling should be consistent with existing module functions
• Functions should maintain the module's current error handling patterns
• Performance considerations should be made for large string processing

The implementation should follow the existing pattern in the module of using FuncRegistration for function registration and proper documentation formats.