Text.Capitalize, Text.Replace, Text.Repeat, Text.Left, Text.Right

Text.Capitalize(s) → string · Text.Replace(s, old, new) → string · Text.Repeat(s, n) → string · Text.Left/Right(s, n) → string

Produce a new string from an old one: upper-case the first letter, replace every occurrence of a substring, repeat it, or take characters from one end. Replace hits every non-overlapping occurrence left-to-right and throws on an empty search; Left/Right clamp rather than throw. All run in memory.

Summary#

Each of these returns a new string. Text.Capitalize(s) upper-cases the first character and leaves the rest alone. Text.Replace(s, old, new) swaps every occurrence of old for new. Text.Repeat(s, n) concatenates s with itself n times. Text.Left(s, n) and Text.Right(s, n) take n characters from the start or end.

Signature#

Text.Capitalize(<string> s) -> string             // first character upper, rest unchanged
Text.Replace(<string> s, <string> old, <string> new) -> string   // EVERY occurrence
Text.Repeat(<string> s, <int> n) -> string
Text.Left(<string> s, <int> n)  -> string         // first n characters
Text.Right(<string> s, <int> n) -> string         // last n characters

Description#

Capitalize touches only the first character#

Text.Capitalize upper-cases the first character and copies the rest verbatim — it does not lower-case the tail, and it does not touch other words. Text.Capitalize("hELLO wORLD") is "HELLO wORLD". If you want each word title-cased with its tail lowered, that is a different function — Text.TitleCase. The casing is invariant simple-case mapping, so a ligature like ﬁ is left as it is rather than expanded.

Replace hits EVERY occurrence, left-to-right, non-overlapping#

Text.Replace("a-b-c", "-", "+") is "a+b+c". Matching is greedy and left-to-right with no overlap, so Text.Replace("aaa", "aa", "b") is "ba" — the first "aa" is replaced, leaving a trailing "a". The search is a literal, not a pattern: Text.Replace("a.b", ".", "-") replaces the actual dot. An empty old throws (there is nothing to find) — guard it if the search text is user-supplied.

Repeat and Left/Right clamp, they do not throw#

Text.Repeat(s, 0) and a negative count both yield "". Text.Left/Text.Right clamp: asking for more characters than the string has returns the whole string, and a negative count returns "" — neither throws. (This is unlike Text.Substring, which throws when its range runs past the end.)

All of these run in memory on a value already in hand.

Examples#

// Capitalise, then keep it short with an ellipsis if it overruns.
string ShortLabel(string raw) {
  var c = Text.Capitalize(raw);
  if (Text.Length(c) <= 8) { return c; }
  return Text.Left(c, 7) + "…";
}

[Test]
void Text_transform_answers() {
  Assert.Equal("Hello", ShortLabel("hello"));
  Assert.Equal("Announc…", ShortLabel("announcement"));   // clamped Left + ellipsis

  Assert.Equal("HELLO wORLD", Text.Capitalize("hELLO wORLD"));   // only the first char
  Assert.Equal("a+b+c", Text.Replace("a-b-c", "-", "+"));
  Assert.Equal("ba", Text.Replace("aaa", "aa", "b"));            // greedy, non-overlapping
  Assert.Equal("a-b", Text.Replace("a.b", ".", "-"));            // the dot is literal

  Assert.Equal("ababab", Text.Repeat("ab", 3));
  Assert.Equal("", Text.Repeat("ab", -2));                       // clamps to empty

  Assert.Equal("He", Text.Left("Hello", 2));
  Assert.Equal("lo", Text.Right("Hello", 2));
  Assert.Equal("Hello", Text.Left("Hello", 99));                 // clamps, never throws
  Assert.Equal("", Text.Right("Hello", -1));
}