Str

Str is an F# extension and module library for System.String. It compiles to Javascript and Typescript with Fable.

It Includes

• A Str module that has all methods from the String type as functions, and more. Adapted and extended from FSharpX

• A Computational Expression str that can be used to build up strings ( using a StringBuilder internally).

• Extension members on System.String like .Get .First .Last .SecondLast and more. With nicer IndexOutOfRangeExceptions that include the bad index and the actual size.

• Extensive Tests running on both .NET and JS

Full API Documentation

goswinr.github.io/Str

Use of AI and LLMs in the project

All core functions are written by hand to ensure performance and correctness. However, AI tools have been used for code review, typo and grammar checking in documentation and to generate not all but many of the tests.

Usage

Just open the module

open Str

this module contains:

• a static class also called Str
• a Computational Expression called str
• this will also auto open the extension members on System.String

The str Computation Expression

Build strings using a StringBuilder internally, with support for string, char, int, loops, and sequences:

let hello = // "Hello, World !!!"
    str {
        "Hello"
        ','
        " World "
        for i in 1..3 do
            "!"
    }

Use yield! to append with a trailing newline. Newlines are Environment.NewLine, so \r\n on Windows and \n elsewhere (the examples below show \n):

let lines = // "line one\nline two\nline three\n"
    str {
        yield! "line one"
        yield! "line two"
        yield! "line three"
    }

You can also yield a sequence of strings (each gets a newline):

let fromSeq = // "a\nb\nc\n"
    str {
        ["a"; "b"; "c"]
    }

Before / After / Between

Extract parts of a string relative to a delimiter. Each operation comes in three variants:

• throws if not found (e.g. before)
• try returns Option (e.g. tryBefore)
• orInput returns the full input string if not found (e.g. beforeOrInput)

Str.before  "/"  "hello/world"         // "hello"
Str.after   "/"  "hello/world"         // "world"
Str.between "("  ")" "say (hi) now"    // "hi"

Str.tryBefore "?" "no-question"        // None
Str.tryAfter  "/" "hello/world"        // Some "world"

Str.beforeOrInput "?" "no-question"    // "no-question"

Character versions are available too:

Str.beforeChar '/' "hello/world"       // "hello"
Str.afterChar  '/' "hello/world"       // "world"
Str.betweenChars '(' ')' "say (hi) now" // "hi"

Splitting

Str.splitOnce ":"  "key:value"                // ("key", "value")
Str.splitTwice "(" ")" "before(inside)after"  // ("before", "inside", "after")

// Option variants for safe splitting
Str.trySplitOnce ":" "no-colon"               // None

// Split into array (removes empty entries by default)
Str.split "," "a,,b,c"                        // [|"a"; "b"; "c"|]
Str.splitKeep "," "a,,b,c"                    // [|"a"; ""; "b"; "c"|]

// Split by characters
Str.splitChar ',' "a,b,c"                     // [|"a"; "b"; "c"|]
Str.splitChars [|',';';'|] "a,b;c"            // [|"a"; "b"; "c"|]

// Split by line endings (\r\n, \r, \n)
Str.splitLines "line1\nline2\r\nline3"        // [|"line1"; "line2"; "line3"|]

Slicing with Negative Indices

Negative indices count from the end (-1 is the last character). The end index is inclusive.

Str.sliceNeg  0   4  "Hello, World!"    // "Hello"
Str.sliceNeg  7  11  "Hello, World!"    // "World"
Str.sliceNeg  0  -1  "Hello, World!"    // "Hello, World!"
Str.sliceNeg -6  -2  "Hello, World!"    // "World"

Str.sliceIdx rejects negative indices, Str.sliceLooped wraps any index around with modulo:

Str.sliceIdx     7  11  "Hello, World!"    // "World"
Str.sliceIdx    -6  -2  "Hello, World!"    // throws StrException
Str.sliceLooped -6  -2  "Hello, World!"    // "World"
Str.sliceLooped 13  17  "Hello, World!"    // "Hello"  (13 wraps to 0, 17 to 4)

For a start index and a length use Str.sub, like Array.sub:

Str.sub 7 5 "Hello, World!"    // "World"

(Str.slice and str.Slice still work, but are obsolete: in .NET the .Slice method of some collections, like List<'T> and Span<'T>, takes a start index and a length.)

Truncate, Skip, and Take

Str.truncate 5 "Hello, World!"    // "Hello"  (safe, returns input if shorter)
Str.take     5 "Hello, World!"    // "Hello"  (fails if input is shorter)
Str.skip     7 "Hello, World!"    // "World!"

Replace Variants

Str.replace      "o" "0" "foo boo"  // "f00 b00"  (all occurrences)
Str.replaceFirst "o" "0" "foo boo"  // "f0o boo"  (first only)
Str.replaceLast  "o" "0" "foo boo"  // "foo bo0"  (last only)
Str.replaceChar  'o' '0' "foo boo"  // "f00 b00"  (all char occurrences)
Str.replace      ""  "0" "foo boo"  // "foo boo"  (an empty oldValue is a no-op)

Delete

Str.delete     "World" "Hello World"  // "Hello "
Str.deleteChar '!'     "Hi!!!"        // "Hi"

Case Functions

Str.up1    "hello"  // "Hello"  (capitalize first letter)
Str.low1   "Hello"  // "hello"  (lowercase first letter)
Str.toUpper "hi"    // "HI"
Str.toLower "HI"    // "hi"

Contains and Comparison

Str.contains           "world" "hello world"  // true
Str.containsIgnoreCase "WORLD" "hello world"  // true
Str.notContains        "xyz"   "hello world"  // true

Str.startsWith  "hello" "hello world"   // true
Str.endsWith    "world" "hello world"   // true
Str.equals      "abc"   "abc"           // true  (ordinal)
Str.equalsIgnoreCase "ABC" "abc"        // true

Counting

Str.countSubString "ab" "ababab"  // 3
Str.countChar      'a'  "banana"  // 3

Whitespace and Emptiness Checks

Str.isWhite    "  \t "   // true
Str.isNotWhite "hello"   // true
Str.isEmpty    ""         // true
Str.isNotEmpty "hello"   // true

Padding, Quoting, and Affixes

Str.padLeft      10 "hi"         // "        hi"
Str.padRightWith 10 '.' "hi"    // "hi........"
Str.addPrefix "pre-"  "fix"     // "pre-fix"
Str.addSuffix "-end"  "start"   // "start-end"
Str.inQuotes       "hi"         // "\"hi\""
Str.inSingleQuotes "hi"         // "'hi'"

Number Formatting

Str.addThousandSeparators '\'' "1234567"       // "1'234'567"
Str.addThousandSeparators ','  "1234567.1234"  // "1,234,567.123,4"

Normalize (Remove Diacritics)

Str.normalize "cafe\u0301"  // "cafe"  (removes combining accent)
Str.normalize "Zürich"      // "Zurich"

Display Formatting

Str.formatInOneLine "hello\n  world"            // "hello world"
Str.formatTruncated 10 "a long string here"     // "\"a long(..)\"" (truncated with placeholder)
Str.formatTruncatedToMaxLines 2 "a\nb\nc\nd"    // shows first 2 lines + note

Joining

Str.concat ", " ["a"; "b"; "c"]   // "a, b, c"
Str.concatLines  ["a"; "b"; "c"]  // "a\nb\nc" (joined with Environment.NewLine)

Extension Members (auto-opened)

These are available on any string as soon as you open Str:

let s = "Hello, World!"

s.Contains('W')              // true  (char overload)
s.DoesNotContain("xyz")     // true
s.IsWhite                   // false
s.IsNotEmpty                // true

Extension Members (from ExtensionsString module)

For richer indexing and slicing, also open the ExtensionsString module:

open Str.ExtensionsString

let s = "Hello"
s.First        // 'H'
s.Last         // 'o'
s.Second       // 'e'
s.SecondLast   // 'l'
s.ThirdLast    // 'l'
s.LastX 3      // "llo"
s.LastIndex    // 4

s.Get 0        // 'H'  (with descriptive errors on out-of-range)
s.GetNeg(-1)   // 'o'  (negative index, -1 = last)
s.GetLooped 7  // 'l'  (wraps around: 7 % 5 = 2)

s.SliceNeg(0, 2)    // "Hel"  (inclusive end index)
s.SliceNeg(-3, -1)  // "llo"
s.SliceIdx(1, 3)    // "ell"  (throws on negative indices)
s.SliceLooped(5, 7) // "Hel"  (5 wraps to 0, 7 to 2)

s.ReplaceFirst("l", "L")  // "HeLlo"  (only first match)
s.ReplaceLast ("l", "L")  // "HelLo"  (only last match)

StringBuilder Extensions (auto-opened)

open Str also adds convenience methods to System.Text.StringBuilder:

open System.Text

let sb = StringBuilder()
sb.Add "hello"       // Append returning unit (instead of StringBuilder)
sb.Add ','           // Append char returning unit
sb.AddLine " world"  // AppendLine returning unit
sb.Contains "hello"  // true
sb.IndexOf ","       // 5

Tests

All Tests run in both javascript and dotnet. Successful Fable compilation to typescript is verified too.

The tests use Scriptorium (Scriptorium.Quill + Scriptorium.Nib). The same test definitions and entry point run on .NET and on JS.

For testing with .NET:

dotnet run --project ./Tests/Tests.fsproj

for JS testing (Fable compiles the tests and runs them with Node.js via dotnet fable --runScript) and TS verification:

cd Tests
npm run testTS   # = npm test && npm run buildTS

License

MIT

Changelog

see CHANGELOG.md