std.string

String handling functions.

Objects of types string, wstring, and dstring are value types and cannot be mutated element-by-element. For using mutation during building strings, use char[], wchar[], or dchar[]. The xxxstring types are preferable because they don't exhibit undesired aliasing, thus making code more robust.

The following functions are publicly imported:

ModuleFunctions
Publicly imported functions
std.algorithmcmp count endsWith startsWith
std.arrayjoin replace replaceInPlace split empty
std.formatformat sformat
std.uniicmp toLower toLowerInPlace toUpper toUpperInPlace

There is a rich set of functions for string handling defined in other modules. Functions related to Unicode and ASCII are found in std.uni and std.ascii, respectively. Other functions that have a wider generality than just strings can be found in std.algorithm and std.range.

Public Imports

std.format
public import std.format : format, sformat;
std.uni
public import std.uni : icmp, toLower, toLowerInPlace, toUpper, toUpperInPlace;
std.algorithm.comparison
public import std.algorithm.comparison : cmp;
std.algorithm.searching
public import std.algorithm.searching : startsWith, endsWith, count;
std.array
public import std.array : join, replace, replaceInPlace, split, empty;

Members

Aliases

CaseSensitive
alias CaseSensitive = Flag!"caseSensitive"

Flag indicating whether a search is case-sensitive.

KeepTerminator
alias KeepTerminator = Flag!"keepTerminator"

Split s into an array of lines according to the unicode standard using '\r', '\n', "\r\n", std.uni.lineSep, std.uni.paraSep, U+0085 (NEL), '\v' and '\f' as delimiters. If keepTerm is set to KeepTerminator.yes, then the delimiter is included in the strings returned.

Classes

StringException
class StringException

Exception thrown on errors in std.string functions.

Functions

abbrev
string[string] abbrev(string[] values)

Construct an associative array consisting of all abbreviations that uniquely map to the strings in values.

assumeUTF
auto assumeUTF(T[] arr)

Assume the given array of integers arr is a well-formed UTF string and return it typed as a UTF string.

capitalize
S capitalize(S input)

Capitalize the first character of s and convert the rest of s to lowercase.

center
S center(S s, size_t width, dchar fillChar)

Center s in a field width characters wide. fillChar is the character that will be used to fill up the space in the field that s doesn't fill.

centerJustifier
auto centerJustifier(Range r, size_t width, dchar fillChar)

Center justify r in a field width characters wide. fillChar is the character that will be used to fill up the space in the field that r doesn't fill.

chomp
Range chomp(Range str)
Range chomp(Range str, const(C2)[] delimiter)

If str ends with delimiter, then str is returned without delimiter on its end. If it str does not end with delimiter, then it is returned unchanged.

chompPrefix
Range chompPrefix(Range str, const(C2)[] delimiter)

If str starts with delimiter, then the part of str following delimiter is returned. If str does not start with

chop
Range chop(Range str)

Returns str without its last character, if there is one. If str ends with "\r\n", then both are removed. If str is empty, then it is returned unchanged.

column
size_t column(Range str, size_t tabsize)

Compute column number at the end of the printed form of the string, assuming the string starts in the leftmost column, which is numbered starting from 0.

detab
auto detab(Range s, size_t tabSize)

Replace each tab character in s with the number of spaces necessary to align the following character at the next tab stop.

detabber
auto detabber(Range r, size_t tabSize)

Replace each tab character in r with the number of spaces necessary to align the following character at the next tab stop.

entab
auto entab(Range s, size_t tabSize)

Replaces spaces in s with the optimal number of tabs. All spaces and tabs at the end of a line are removed.

entabber
auto entabber(Range r, size_t tabSize)

Replaces spaces in range r with the optimal number of tabs. All spaces and tabs at the end of a line are removed.

fromStringz
inout(Char)[] fromStringz(inout(Char)* cString)
inout(Char)[] fromStringz(inout(Char)[] cString)
indexOf
ptrdiff_t indexOf(Range s, dchar c, CaseSensitive cs)
ptrdiff_t indexOf(const(C)[] s, dchar c, CaseSensitive cs)
ptrdiff_t indexOf(Range s, dchar c, size_t startIdx, CaseSensitive cs)
ptrdiff_t indexOf(const(C)[] s, dchar c, size_t startIdx, CaseSensitive cs)

Searches for character in range.

indexOf
ptrdiff_t indexOf(Range s, const(Char)[] sub)
ptrdiff_t indexOf(Range s, const(Char)[] sub, CaseSensitive cs)
ptrdiff_t indexOf(const(Char1)[] s, const(Char2)[] sub, size_t startIdx)
ptrdiff_t indexOf(const(Char1)[] s, const(Char2)[] sub, size_t startIdx, CaseSensitive cs)

Searches for substring in s.

indexOfAny
ptrdiff_t indexOfAny(const(Char)[] haystack, const(Char2)[] needles, CaseSensitive cs)
ptrdiff_t indexOfAny(const(Char)[] haystack, const(Char2)[] needles, size_t startIdx, CaseSensitive cs)

Returns the index of the first occurrence of any of the elements in needles in haystack. If no element of needles is found, then -1 is returned. The startIdx slices haystack in the following way haystack[startIdx .. $]. startIdx represents a codeunit index in haystack. If the sequence ending at startIdx does not represent a well formed codepoint, then a std.utf.UTFException may be thrown.

indexOfNeither
ptrdiff_t indexOfNeither(const(Char)[] haystack, const(Char2)[] needles, CaseSensitive cs)
ptrdiff_t indexOfNeither(const(Char)[] haystack, const(Char2)[] needles, size_t startIdx, CaseSensitive cs)

Returns the index of the first occurrence of any character not an elements in needles in haystack. If all element of haystack are element of needles -1 is returned.

isNumeric
bool isNumeric(S s, bool bAllowSep)

Takes a string s and determines if it represents a number. This function also takes an optional parameter, bAllowSep, which will accept the separator characters ',' and '__' within the string. But these characters should be stripped from the string before using any of the conversion functions like to!int(), to!float(), and etc else an error will occur.

lastIndexOf
ptrdiff_t lastIndexOf(const(Char)[] s, dchar c, CaseSensitive cs)
ptrdiff_t lastIndexOf(const(Char)[] s, dchar c, size_t startIdx, CaseSensitive cs)
lastIndexOf
ptrdiff_t lastIndexOf(const(Char1)[] s, const(Char2)[] sub, CaseSensitive cs)
ptrdiff_t lastIndexOf(const(Char1)[] s, const(Char2)[] sub, size_t startIdx, CaseSensitive cs)
lastIndexOfAny
ptrdiff_t lastIndexOfAny(const(Char)[] haystack, const(Char2)[] needles, CaseSensitive cs)
ptrdiff_t lastIndexOfAny(const(Char)[] haystack, const(Char2)[] needles, size_t stopIdx, CaseSensitive cs)

Returns the index of the last occurrence of any of the elements in needles in haystack. If no element of needles is found, then -1 is returned. The stopIdx slices haystack in the following way s[0 .. stopIdx]. stopIdx represents a codeunit index in haystack. If the sequence ending at startIdx does not represent a well formed codepoint, then a std.utf.UTFException may be thrown.

lastIndexOfNeither
ptrdiff_t lastIndexOfNeither(const(Char)[] haystack, const(Char2)[] needles, CaseSensitive cs)
ptrdiff_t lastIndexOfNeither(const(Char)[] haystack, const(Char2)[] needles, size_t stopIdx, CaseSensitive cs)

Returns the last index of the first occurence of any character that is not an elements in needles in haystack. If all element of haystack are element of needles -1 is returned.

leftJustifier
auto leftJustifier(Range r, size_t width, dchar fillChar)

Left justify s in a field width characters wide. fillChar is the character that will be used to fill up the space in the field that s doesn't fill.

leftJustify
S leftJustify(S s, size_t width, dchar fillChar)

Left justify s in a field width characters wide. fillChar is the character that will be used to fill up the space in the field that s doesn't fill.

lineSplitter
auto lineSplitter(Range r)
auto lineSplitter(C[] r)

Split an array or slicable range of characters into a range of lines using '\r', '\n', '\v', '\f', "\r\n", std.uni.lineSep, std.uni.paraSep and '\u0085' (NEL) as delimiters. If keepTerm is set to Yes.keepTerminator, then the delimiter is included in the slices returned.

makeTrans
string makeTrans(const(char)[] from, const(char)[] to)

Do same thing as makeTransTable but allocate the translation table on the GC heap.

makeTransTable
char[256] makeTransTable(const(char)[] from, const(char)[] to)

Construct 256 character translation table, where characters in from[] are replaced by corresponding characters in to[].

outdent
S outdent(S str)

Removes one level of indentation from a multi-line string.

outdent
S[] outdent(S[] lines)

Removes one level of indentation from an array of single-line strings.

representation
auto representation(Char[] s)

Returns the representation of a string, which has the same type as the string except the character type is replaced by ubyte, ushort, or uint depending on the character width.

rightJustifier
auto rightJustifier(Range r, size_t width, dchar fillChar)

Right justify s in a field width characters wide. fillChar is the character that will be used to fill up the space in the field that s doesn't fill.

rightJustify
S rightJustify(S s, size_t width, dchar fillChar)

Right justify s in a field width characters wide. fillChar is the character that will be used to fill up the space in the field that s doesn't fill.

soundex
char[] soundex(const(char)[] str, char[] buffer)

Like soundexer, but with different parameters and return value.

soundexer
char[4] soundexer(Range str)

Soundex algorithm.

splitLines
C[][] splitLines(C[] s, KeepTerminator keepTerm)

Split s into an array of lines according to the unicode standard using '\r', '\n', "\r\n", std.uni.lineSep, std.uni.paraSep, U+0085 (NEL), '\v' and '\f' as delimiters. If keepTerm is set to KeepTerminator.yes, then the delimiter is included in the strings returned.

strip
auto strip(Range str)
auto strip(Range str, const(Char)[] chars)
auto strip(Range str, const(Char)[] leftChars, const(Char)[] rightChars)

Strips both leading and trailing whitespace (as defined by std.uni.isWhite) or as specified in the second argument.

stripLeft
auto stripLeft(Range input)
auto stripLeft(Range input, const(Char)[] chars)

Strips leading whitespace (as defined by std.uni.isWhite) or as specified in the second argument.

stripRight
auto stripRight(Range str)
auto stripRight(Range str, const(Char)[] chars)

Strips trailing whitespace (as defined by std.uni.isWhite) or as specified in the second argument.

succ
S succ(S s)

Return string that is the 'successor' to s[]. If the rightmost character is a-zA-Z0-9, it is incremented within its case or digits. If it generates a carry, the process is repeated with the one to its immediate left.

toStringz
immutable(char)* toStringz(const(char)[] s)
tr
C1[] tr(C1[] str, const(C2)[] from, const(C3)[] to, const(C4)[] modifiers)

Replaces the characters in str which are in from with the the corresponding characters in to and returns the resulting string.

translate
C1[] translate(C1[] str, dchar[dchar] transTable, const(C2)[] toRemove)
C1[] translate(C1[] str, S[dchar] transTable, const(C2)[] toRemove)

Replaces the characters in str which are keys in transTable with their corresponding values in transTable. transTable is an AA where its keys are dchar and its values are either dchar or some type of string. Also, if toRemove is given, the characters in it are removed from str prior to translation. str itself is unaltered. A copy with the changes is returned.

translate
void translate(const(C1)[] str, dchar[dchar] transTable, const(C2)[] toRemove, Buffer buffer)
void translate(C1[] str, S[dchar] transTable, const(C2)[] toRemove, Buffer buffer)

This is an overload of translate which takes an existing buffer to write the contents to.

translate
C[] translate(const(char)[] str, const(char)[] transTable, const(char)[] toRemove)

This is an ASCII-only overload of _translate. It will not work with Unicode. It exists as an optimization for the cases where Unicode processing is not necessary.

translate
void translate(const(char)[] str, const(char)[] transTable, const(char)[] toRemove, Buffer buffer)

This is an ASCII-only overload of translate which takes an existing buffer to write the contents to.

wrap
S wrap(S s, size_t columns, S firstindent, S indent, size_t tabsize)

Wrap text into a paragraph.

See Also

    Meta

    Authors

    Walter Bright, Andrei Alexandrescu, Jonathan M Davis, and David L. 'SpottedTiger' Davis