strscan

README

strscan

Go package that provides functions to scan and iterate over strings.

Why

When operating on strings, it is common to use utilities like strings.Split, however in many circumstances it is unnecessary to allocate a slice and could lead to issues such as memory exhaustion when operating on untrusted inputs.

Both, Scan and Reversed perform a minimal amount of allocations, that doesn't scale with the amount of separators or the length of the input.

Usage

Scan

Scans a string left-to-right, returning substrings between the separator.

for s := range strscan.Scan("1.1.1.1, 127.0.0.1, ::1", ',', true) {
  // s will have the following values (in order):
  // - "1.1.1.1"
  // - "127.0.0.1"
  // - "::1"
  _ = s
}

Reversed

This was created for use with Real IP middleware, primarily when parsing X-Forwarded-For, where you want to scan a string right-to-left, finding the first non-trusted address.

for s := range strscan.Reversed("1.1.1.1, 127.0.0.1, ::1", ',', true) {
  // s will have the following values (in order):
  // - "::1"
  // - "127.0.0.1"
  // - "1.1.1.1"
  _ = s
}

See strscan_test.go for more details and examples.

Installation

go get github.com/matthewpi/strscan

Documentation

Overview

Package strscan provides functions to scan and iterate over strings.

Index

• func Reversed(s string, sep byte, trim bool) iter.Seq[string]
• func Scan(s string, sep byte, trim bool) iter.Seq[string]

Examples

• Reversed
• Scan

Functions

func Reversed

func Reversed(s string, sep byte, trim bool) iter.Seq[string]

Reversed scans the string s for instances of sep, returning the substrings via an iterator. Reversed starts at len(s) and stops at 0.

If trim is true, substrings will have any leading and trailing space characters removed before being passed to the iterator.

If a substring is empty, it will be silently skipped. A substring is considered empty when it's length is 0. This is caused by s containing back-to-back separators or when the substring consists entirely of space characters (only when trim is enabled).

Example

package main

import (
	"fmt"

	"github.com/matthewpi/strscan"
)

func main() {
	for s := range strscan.Reversed("1.1.1.1, 127.0.0.1, ::1", ',', false) {
		// quotes were added to show that trim removes whitespace
		fmt.Printf("\"%s\"\n", s)
	}
	fmt.Println()
	for s := range strscan.Reversed("1.1.1.1, 127.0.0.1, ::1", ',', true) {
		// quotes were added to show that trim removes whitespace
		fmt.Printf("\"%s\"\n", s)
	}

}

Output:

" ::1"
" 127.0.0.1"
"1.1.1.1"

"::1"
"127.0.0.1"
"1.1.1.1"

func Scan

func Scan(s string, sep byte, trim bool) iter.Seq[string]

Scan scans the string s for instances of sep, returning the substrings via an iterator. Scan starts from index 0 and stops at len(s).

If trim is true, substrings will have any leading and trailing space characters removed before being passed to the iterator.

If a substring is empty, it will be silently skipped. A substring is considered empty when it's length is 0. This is caused by s containing back-to-back separators or when the substring consists entirely of space characters (only when trim is enabled).

Example

package main

import (
	"fmt"

	"github.com/matthewpi/strscan"
)

func main() {
	for s := range strscan.Scan("1.1.1.1, 127.0.0.1, ::1", ',', false) {
		// quotes were added to show that trim removes whitespace
		fmt.Printf("\"%s\"\n", s)
	}
	fmt.Println()
	for s := range strscan.Scan("1.1.1.1, 127.0.0.1, ::1", ',', true) {
		// quotes were added to show that trim removes whitespace
		fmt.Printf("\"%s\"\n", s)
	}

}

Output:

"1.1.1.1"
" 127.0.0.1"
" ::1"

"1.1.1.1"
"127.0.0.1"
"::1"