Import std.text.string

String

std.text.string

extend

Extend String

Searching, slicing, splitting, and changing a String, by byte position, and its lengths in bytes, code points, and grapheme clusters.

std/text/string.fb, line 33

Public Property Length: Int property #
How many bytes its UTF-8 has, which is also the position just past its end.

Examples
```
Local text = "héllo"
Expect(text.Length == 6 && text.CharCount == 5)
```
Public Property CharCount: Int property #

How many characters, code points, it has.
Public Property GraphemeCount: Int property #

How many grapheme clusters it has: what people see as one character, like an "e" with its accent after it, or an emoji made of several.
Public Static Method FromUtf8(bytes: UInt8[]): String? static method #

A String of the UTF-8 in bytes, or Null when they aren't well-formed UTF-8.
Public Method IsEmpty(): Bool method #

Whether it has no characters.
Public Method IsBlank(): Bool method #

Whether it has no characters but whitespace.
Public Method Contains(part: String): Bool method #

Whether part is in it. Every String has "" in it.
Public Method Contains(c: Char): Bool method #

Whether c is in it.
Public Method StartsWith(prefix: String): Bool method #

Whether it starts with prefix.
Public Method EndsWith(suffix: String): Bool method #

Whether it ends with suffix.
@PanicsAtCaller Public Method Find(part: String, from: Int = 0): Int? method #
Where part first starts, at from or after, or Null when it isn't there. Panics when from isn't a position in the String.

Examples
```
Expect("hello".Find("l") == 2)
Expect("hello".FindLast("l") == 3)
Expect("hello".Find("z") == Null)
Expect("hello".Slice(1, 4) == "ell")
```
Public Method FindLast(part: String): Int? method #

Where part last starts, or Null when it isn't there.
@PanicsAtCaller Public Method FindLast(part: String, before: Int): Int? method #

Where part last starts that ends at before or before it, or Null when it isn't there. Panics when before isn't a position in the String.
@PanicsAtCaller Public Method FindAll(part: String): Int[] method #

Where part starts, each time, from the start: after one is found, the next is looked for after its end. An empty part panics.
@PanicsAtCaller Public Method Count(part: String): Int method #

How many times part is in it, counting each from the end of the one before, as FindAll does. An empty part panics.
@PanicsAtCaller Public Method Slice(start: Int, finish: Int): String method #

The text from start up to finish. Panics unless both are positions in the String, between its characters, with start not after finish.
Public Method Before(part: String): String? method #

The text before the first part, or Null when part isn't there.
Public Method After(part: String): String? method #

The text after the first part, or Null when part isn't there.
Public Method SplitOnce(separator: String): (String, String)? method #

The text before the first separator and after it, or Null when separator isn't there.

@PanicsAtCaller Public Method Split(separator: String): String[] method #

The parts between each separator: "a,,b" split by "," is "a", "", and "b". An empty separator panics.

Examples

Expect("a,b,,c".Split(",") == ["a", "b", "", "c"])
Expect("  two  words ".SplitWhitespace() == ["two", "words"])
Expect("key=value=more".SplitOnce("=") == ("key", "value=more"))

@PanicsAtCaller Public Method SplitN(separator: String, count: Int): String[] method #

The parts between each separator, at most count of them, the last holding the rest. An empty separator, or a count below 1, panics.
Public Method SplitLines(): String[] method #

Its lines, without their line breaks: "\n", "\r\n", or "\r". A line break at the end makes no empty line after it, and an empty String has no lines.
Public Method SplitWhitespace(): String[] method #

Its words: the parts between runs of whitespace, which make no empty ones.
@PanicsAtCaller Public Method Join(parts: String[]): String method #

The parts with this String between each two: ", ".Join(["a", "b"]) is "a, b". Panics past the most a String holds.
@PanicsAtCaller Public Method Replace(old: String, replacement: String): String method #
A copy with each old, from the start, replaced by replacement. An empty old panics, and so does a copy past the most a String holds.

Examples
```
Expect("a-b-c".Replace("-", "+") == "a+b+c")
Expect("a-b-c".ReplaceFirst("-", "+") == "a+b-c")
```
@PanicsAtCaller Public Method ReplaceFirst(old: String, replacement: String): String method #

A copy with the first old replaced by replacement, or the String itself when old isn't there. An empty old panics.
Public Method Trim(): String method #
A copy without the whitespace at its start and end.

Examples
```
Expect("  hi  ".Trim() == "hi")
Expect("v1.2".TrimPrefix("v") == "1.2")
```
Public Method TrimStart(): String method #

A copy without the whitespace at its start.
Public Method TrimEnd(): String method #

A copy without the whitespace at its end.
Public Method TrimPrefix(prefix: String): String method #

A copy without prefix at its start, or the String itself when it doesn't start with it.
Public Method TrimSuffix(suffix: String): String method #

A copy without suffix at its end, or the String itself when it doesn't end with it.
@PanicsAtCaller Public Method ToUpper(): String method #

A copy in uppercase, by Unicode's full case mapping, so "straße" is "STRASSE". Panics past the most a String holds.
@PanicsAtCaller Public Method ToLower(): String method #

A copy in lowercase, by Unicode's full case mapping, with a capital sigma that ends a word as a final sigma: "ΣΑΣ" is "σας". Panics past the most a String holds.
@PanicsAtCaller Public Method Repeated(count: Int): String method #

The String count times over, as std.core's Repeated gives a value. A negative count panics.
@PanicsAtCaller Public Method PadLeft(width: Int, fill: Char = ' '): String method #
A copy with fill before it, as many as it takes to make width characters, or the String itself when it has as many already. Panics past the most a String holds.

Examples
```
Expect("7".PadLeft(3, '0') == "007")
Expect("hi".Center(6) == "  hi  ")
```
@PanicsAtCaller Public Method PadRight(width: Int, fill: Char = ' '): String method #

A copy with fill after it, as many as it takes to make width characters, or the String itself when it has as many already. Panics past the most a String holds.
@PanicsAtCaller Public Method Center(width: Int, fill: Char = ' '): String method #

A copy with fill on both sides, as many as it takes to make width characters, one more after it than before when they don't split evenly, or the String itself when it has as many already. Panics past the most a String holds.
Public Method Compare(other: String): Int method #

-1 when it comes before other, 0 when they're equal, and 1 when it comes after, by their code points, as < compares them.
@PanicsAtCaller Public Method EqualsIgnoreCase(other: String): Bool method #

Whether it's equal to other but for case, as Unicode's case folding has it: "STRASSE" and "straße" are. Panics when both fold past the most a String holds, where one alone is longer than the other.
Public Method NaturalCompare(other: String): Int method #
-1, 0, or 1, as Compare gives, but with each run of the digits 0 to 9 compared as a number, so "file9" comes before "file10". Runs equal as numbers, like "07" and "7", go by their length after that, the shorter first.

Examples
```
Expect("file2".NaturalCompare("file10") < 0)
Expect("file2".Compare("file10") > 0)
```
Public Method Lines(): LineIterator method #

Its lines, one at a time, as SplitLines gives them.
Public Method Graphemes(): GraphemeIterator method #

Its grapheme clusters, one at a time: what people see as one character each.

Report an issue with this page or with FutureBlitz on GitHub.