string_editor

Package Version Hex Docs

A Gleam library for string manipulation and extraction. Extract substrings before, after, or between specific patterns.

Installation

gleam add string_editor

Usage

import string_editor

pub fn main() -> Nil {
  // Extract text before a pattern
  let assert Ok("hello") = string_editor.before("hello world", on: " ")
  
  // Extract text after a pattern  
  let assert Ok("world") = string_editor.after("hello world", on: " ")
  
  // Extract text between two patterns
  let assert Ok("content") = string_editor.between("<div>content</div>", from: "<div>", to: "</div>")
  
  // Count occurrences of a pattern
  let count = string_editor.count("hello hello world", of: "hello") // 2
  
  // Extract at specific index
  let assert Ok("a.b") = string_editor.before_at("a.b.c.d", on: ".", at: 1)
  
  // Extract all occurrences
  let all_before = string_editor.before_all("a.b.c.d", on: ".") // ["a", "a.b", "a.b.c"]
}

API Reference

before(string: String, on pattern: String) -> Result(String, Nil)

Returns the part of a string before the first occurrence of a given substring.

Examples:

string_editor.before("hello world", on: " ")
// Ok("hello")

string_editor.before("no-match", on: "!")  
// Error(Nil)

after(string: String, on pattern: String) -> Result(String, Nil)

Returns the part of a string after the first occurrence of a given substring.

Examples:

string_editor.after("hello world", on: " ")
// Ok("world")

string_editor.after("no-match", on: "!")
// Error(Nil)

between(string: String, from start: String, to end: String) -> Result(String, Nil)

Returns the part of a string between two given substrings. Finds the first occurrence of start and then the first occurrence of end after start.

Examples:

string_editor.between("<a>link</a>", from: "<a>", to: "</a>")
// Ok("link")

string_editor.between("<h1>title</h1>", from: "<h1>", to: "</h2>")
// Error(Nil)

count(string: String, of pattern: String) -> Int

Counts the number of occurrences of a substring in a string.

Examples:

string_editor.count("hello hello world", of: "hello")
// 2

string_editor.count("gleam is fun", of: "rust")
// 0

string_editor.count("aaaa", of: "aa")
// 2 (non-overlapping matches)

before_at(string: String, on pattern: String, at index: Int) -> Result(String, Nil)

Returns the part of a string before the nth occurrence of a given substring (0-indexed).

Examples:

string_editor.before_at("a.b.c.d", on: ".", at: 1)
// Ok("a.b")

string_editor.before_at("hello world", on: " ", at: 5)
// Error(Nil)

after_at(string: String, on pattern: String, at index: Int) -> Result(String, Nil)

Returns the part of a string after the nth occurrence of a given substring (0-indexed).

Examples:

string_editor.after_at("a.b.c.d", on: ".", at: 1)
// Ok("c.d")

string_editor.after_at("hello world", on: " ", at: 5)
// Error(Nil)

between_at(string: String, from start: String, to end: String, at index: Int) -> Result(String, Nil)

Returns the part of a string between the nth occurrence of start and the first occurrence of end after that (0-indexed for start pattern).

Examples:

string_editor.between_at("<a>1</a><a>2</a>", from: "<a>", to: "</a>", at: 1)
// Ok("2")

string_editor.between_at("<h1>title</h1>", from: "<h1>", to: "</h2>", at: 0)
// Error(Nil)

before_all(string: String, on pattern: String) -> List(String)

Returns all parts of a string before each occurrence of a given substring.

Examples:

string_editor.before_all("a.b.c.d", on: ".")
// ["a", "a.b", "a.b.c"]

string_editor.before_all("hello world", on: "!")
// []

after_all(string: String, on pattern: String) -> List(String)

Returns all parts of a string after each occurrence of a given substring.

Examples:

string_editor.after_all("a.b.c.d", on: ".")
// ["b.c.d", "c.d", "d"]

string_editor.after_all("hello world", on: "!")
// []

between_all(string: String, from start: String, to end: String) -> List(String)

Returns all parts of a string between each occurrence of start and the next occurrence of end.

Examples:

string_editor.between_all("<a>1</a><b>2</b><a>3</a>", from: "<a>", to: "</a>")
// ["1", "3"]

string_editor.between_all("no matches here", from: "<div>", to: "</div>")
// []

Common Use Cases

HTML/XML Parsing

// Extract content from HTML tags
string_editor.between("<title>My Page</title>", from: "<title>", to: "</title>")
// Ok("My Page")

// Extract all link texts from HTML
string_editor.between_all("<a>Home</a> <a>About</a> <a>Contact</a>", from: "<a>", to: "</a>")
// ["Home", "About", "Contact"]

// Count div tags in HTML
string_editor.count("<div>content</div><div>more</div>", of: "<div>")
// 2

File Path Manipulation

// Get filename from path
string_editor.after("/home/user/document.txt", on: "/")
// Ok("document.txt")

// Get file extension
string_editor.after("document.txt", on: ".")
// Ok("txt")

// Get all directory components
string_editor.after_all("/home/user/projects/myapp", on: "/")
// ["home/user/projects/myapp", "user/projects/myapp", "projects/myapp", "myapp"]

// Count directory levels
string_editor.count("/home/user/projects/myapp", of: "/")
// 4

URL Parsing

// Extract domain from URL
string_editor.between("https://example.com/path", from: "://", to: "/")
// Ok("example.com")

Configuration Parsing

// Extract values from key=value pairs
string_editor.after("DATABASE_URL=postgres://localhost", on: "=")
// Ok("postgres://localhost")

// Parse all environment variables from a string
string_editor.after_all("PORT=3000\nDB_HOST=localhost\nDB_PORT=5432", on: "=")
// ["3000\nDB_HOST=localhost\nDB_PORT=5432", "localhost\nDB_PORT=5432", "5432"]

// Count configuration entries
string_editor.count("key1=value1,key2=value2,key3=value3", of: "=")
// 3

Log Processing

// Extract all timestamps from logs
string_editor.before_all("2023-01-01 INFO: message\n2023-01-02 ERROR: problem", on: " INFO:")
// Would extract timestamp parts before INFO entries

// Count error occurrences
string_editor.count("INFO: ok\nERROR: fail\nINFO: ok\nERROR: fail", of: "ERROR:")
// 2

Error Handling

Functions have different return types based on their purpose:

Result Functions

Functions that return Result(String, Nil) return Error(Nil) when:

Count Function

count() always returns an Int (never fails), returning 0 when no matches are found.

List Functions

*_all functions always return a List(String) (never fail), returning an empty list [] when no matches are found.

Performance Analysis

Here’s an analysis of the performance characteristics of each function:

before() and after() Functions

Time Complexity: O(n) where n is the length of the input string

Space Complexity: O(k) where k is the length of the result substring

Performance Characteristics:

between() Function

Time Complexity: O(n) where n is the length of the input string

Space Complexity: O(k) where k is the length of the extracted content

Performance Characteristics:

count() Function

Time Complexity: O(n) where n is the length of the input string

Space Complexity: O(m) where m is the number of splits

Performance Characteristics:

Indexed Functions (*_at)

Time Complexity: O(n) where n is the length of the input string

Space Complexity: O(m) where m is the number of parts after splitting

Performance Characteristics:

Multi-Instance Functions (*_all)

Time Complexity: O(n + m²) where n is string length, m is number of splits

Space Complexity: O(m × k) where m is matches, k is average result length

Performance Characteristics:

between_all() Function

Time Complexity: O(n + m² + r) where n is input length, m is start matches, r is total results

Space Complexity: O(m × k + r × j) where k is average after_all result size, j is final result size

Performance Characteristics:

Real-World Performance Implications

Suitable for simple use cases involving:

Scaling characteristics:

Function Selection Guidelines:

Comparison with alternatives:

Optimization Tips

  1. Pattern placement: Consider placing the most unique part of your pattern first (may improve performance in some cases)
  2. Function selection:
    • Use count instead of length(before_all(...)) for counting
    • Use *_at when you know the specific index needed
    • Use *_all for batch operations instead of multiple individual calls
  3. For between() operations: More unique start patterns improve performance
  4. Memory considerations:
    • Basic functions have lower memory overhead
    • *_all functions create intermediate lists - consider this for large datasets
    • count uses less memory when you only need frequency information
  5. Pattern considerations: Shorter, more specific patterns can reduce false matches

Development

gleam test  # Run the tests
gleam format # Format the code

Releasing a New Version

When releasing a new version of string_editor, follow these steps:

1. Update Version Numbers

Update the version in the following files:

2. Update CHANGELOG.md

Add a new section to the top of CHANGELOG.md following this format:

## [x.y.z] - YYYY-MM-DD

### Added
- New features

### Changed
- Changes to existing functionality

### Fixed
- Bug fixes

### Removed
- Removed features (if any)

3. Pre-release Checks

Run these commands to ensure everything is working correctly:

gleam format      # Format code consistently
gleam check       # Type check all modules
gleam test        # Run all tests
gleam docs build  # Verify documentation generates correctly

4. Commit and Tag

# Stage your changes
git add gleam.toml CHANGELOG.md

# Commit with a descriptive message
git commit -m "Update to vX.Y.Z: Brief description of changes"

# Create an annotated tag
git tag -a vX.Y.Z -m "Release vX.Y.Z

- Brief summary of major changes
- Another change if needed"

# Push commits and tag to remote
git push origin main vX.Y.Z

5. Publish to Hex

Once all checks pass and the tag is pushed:

gleam publish

This will publish the new version to hex.pm.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request!

Documentation

Further documentation can be found at https://hexdocs.pm/string_editor.

Search Document