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.

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.

cmp (from std.algorithm.comparison)
int cmp(R1 r1, R2 r2) via public import std.algorithm.comparison : cmp;

Performs a lexicographical comparison on two input ranges. Iterating r1 and r2 in lockstep, cmp compares each element e1 of r1 with the corresponding element e2 in r2. If one of the ranges has been finished, cmp returns a negative value if r1 has fewer elements than r2, a positive value if r1 has more elements than r2, and 0 if the ranges have the same number of elements.

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.

count (from std.algorithm.searching)
size_t count(R haystack) via public import std.algorithm.searching : startsWith, endsWith, count;

The first version counts the number of elements x in r for which pred(x, value) is true. pred defaults to equality. Performs O(haystack.length) evaluations of pred.

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.

endsWith (from std.algorithm.searching)
bool endsWith(R doesThisEnd) via public import std.algorithm.searching : startsWith, endsWith, count;

Checks if the given range ends with (one of) the given needle(s). The reciprocal of startsWith.

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.

format (from std.format)
typeof(fmt) format(Args args) via public import std.format : format, sformat;

Converts its arguments according to a format string into a string.

fromStringz
inout(Char)[] fromStringz(inout(Char)* cString)
inout(Char)[] fromStringz(inout(Char)[] cString)
icmp (from std.uni)
int icmp(const(dchar)[] str1, const(dchar)[] str2) via public import std.uni : icmp, toLower, toLowerInPlace, toUpper, toUpperInPlace;
Undocumented in source.
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.

join (from std.array)
ElementEncodingType!(ElementType!RoR)[] join(RoR ror) via public import std.array : join, replace, replaceInPlace, split, empty;

Eagerly concatenates all of the ranges in ror together (with the GC) into one array using sep as the separator if present.

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.

replace (from std.array)
T[] replace(T[] subject, size_t from, size_t to, Range stuff) via public import std.array : join, replace, replaceInPlace, split, empty;

Replaces elements from array with indices ranging from from (inclusive) to to (exclusive) with the range stuff.

replaceInPlace (from std.array)
void replaceInPlace(T[] array, size_t from, size_t to, Range stuff) via public import std.array : join, replace, replaceInPlace, split, empty;

Replaces elements from array with indices ranging from from (inclusive) to to (exclusive) with the range stuff. Expands or shrinks the array as needed.

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.

sformat (from std.format)
char[] sformat(char[] buf, Args args) via public import std.format : format, sformat;

Converts its arguments according to a format string into a buffer. The buffer has to be large enough to hold the formatted string.

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.

split (from std.array)
auto split(Range range) via public import std.array : join, replace, replaceInPlace, split, empty;

Eagerly splits range into an array, using sep as the delimiter.

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.

startsWith (from std.algorithm.searching)
bool startsWith(R doesThisStart) via public import std.algorithm.searching : startsWith, endsWith, count;

Checks whether the given input range starts with (one of) the given needle(s) or, if no needles are given, if its front element fulfils predicate pred.

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.

toLower (from std.uni)
dstring toLower(dstring s) via public import std.uni : icmp, toLower, toLowerInPlace, toUpper, toUpperInPlace;
Undocumented in source.
toLowerInPlace (from std.uni)
void toLowerInPlace(dchar[] s) via public import std.uni : icmp, toLower, toLowerInPlace, toUpper, toUpperInPlace;
Undocumented in source.
toStringz
immutable(char)* toStringz(const(char)[] s)
toUpper (from std.uni)
dstring toUpper(dstring s) via public import std.uni : icmp, toLower, toLowerInPlace, toUpper, toUpperInPlace;
Undocumented in source.
toUpperInPlace (from std.uni)
void toUpperInPlace(dchar[] s) via public import std.uni : icmp, toLower, toLowerInPlace, toUpper, toUpperInPlace;
Undocumented in source.
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.

Properties

empty (from std.array)
bool empty [@property getter] via public import std.array : join, replace, replaceInPlace, split, empty;

Implements the range interface primitive empty for types that obey hasLength property and for narrow strings. Due to the fact that nonmember functions can be called with the first argument using the dot notation, a.empty is equivalent to empty(a).

See Also

    Meta

    Authors

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