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:

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.

Copyright

License

Boost License 1.0.

Authors

Walter Bright, Andrei Alexandrescu, Jonathan M Davis,

and David L. 'SpottedTiger' Davis

Source: std/string.d

tmpl _indexOfStr

alias CaseSensitive KeepTerminator

struct LineSplitter

class StringException

fn _indexOf abbrev assumeUTF capitalize center centerJustifier chomp chompPrefix chop column detab detabber entab entabber fromStringz indexOf indexOfAny indexOfAnyNeitherImpl indexOfNeither isNumeric lastIndexOf lastIndexOfAny lastIndexOfNeither leftJustifier leftJustify lineSplitter makeTrans makeTransTable outdent representation rightJustifier rightJustify soundex soundexer splitLines strip stripLeft stripRight succ toStringz tr translate translateImpl wrap

Types 4

classStringException : Exception

Exception thrown on errors in std.string functions.

aliasCaseSensitive = Flag!"caseSensitive"

Flag indicating whether a search is case-sensitive.

aliasKeepTerminator = Flag!"keepTerminator"

Split s into an array of lines according to the unicode standard using '\r', '\n', "\r\n", lineSep,

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.

Does not throw on invalid UTF; such is simply passed unchanged to the output.

Allocates memory; use lineSplitter for an alternative that does not.

Adheres to Unicode 7.0.

Parameters

`s`	a string of `chars`, `wchars`, or `dchars`, or any custom type that casts to a `string` type
`keepTerm`	whether delimiter is included or not in the results

Returns

array of strings, each element is a line that is a slice of s

Functions 90

fninout(Char)[] fromStringz(Char)(return scope inout(Char) * cString) if (isSomeChar!Char) @nogc @system pure nothrowParams: cString = A null-terminated c-style string.

fninout(Char)[] fromStringz(Char)(return scope inout(Char)[] cString) if (isSomeChar!Char) @nogc @safe pure nothrowditto

fnimmutable(char) * toStringz(scope const(char)[] s) @trusted pure nothrowParams: s = A D-style string.

ptrdiff_t indexOf(Range)(Range s,  dchar  c,  CaseSensitive cs =  Yes.caseSensitive) if (isInputRange!Range &&  isSomeChar!(ElementType!Range)  && !isSomeString!Range)

Searches for a character in a string or range.

fnptrdiff_t indexOf(C)(scope const(C)[] s, dchar c, CaseSensitive cs = Yes.caseSensitive) if (isSomeChar!C)Ditto

ptrdiff_t indexOf(Range)(Range s,  dchar  c,  size_t startIdx,  CaseSensitive cs =  Yes.caseSensitive) if (isInputRange!Range &&  isSomeChar!(ElementType!Range)  && !isSomeString!Range)

Ditto

ptrdiff_t indexOf(C)(scope  const(C)[]  s,  dchar  c,  size_t startIdx,  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!C)

Ditto

private fn

ptrdiff_t _indexOf(Range)(Range s,  dchar  c,  CaseSensitive cs =  Yes.caseSensitive) if (isInputRange!Range &&  isSomeChar!(ElementType!Range))

private fn

ptrdiff_t _indexOf(Range)(Range s,  dchar  c,  size_t startIdx,  CaseSensitive cs =  Yes.caseSensitive) if (isInputRange!Range &&  isSomeChar!(ElementType!Range))

ptrdiff_t indexOf(Range,  Char)(Range s,  const(Char)[]  sub) if (isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
     isSomeChar!Char)

Searches for a substring in a string or range.

ptrdiff_t indexOf(Range,  Char)(Range s,  const(Char)[]  sub,  in  CaseSensitive cs) if (isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
     isSomeChar!Char)

Ditto

ptrdiff_t indexOf(Char1,  Char2)(const(Char1)[]  s,  const(Char2)[]  sub,
         in  size_t startIdx) if (isSomeChar!Char1 &&  isSomeChar!Char2)

@safeDitto

ptrdiff_t indexOf(Char1,  Char2)(const(Char1)[]  s,  const(Char2)[]  sub,
         in  size_t startIdx,  in  CaseSensitive cs) if (isSomeChar!Char1 &&  isSomeChar!Char2)

@safeDitto

ptrdiff_t indexOf(Range,  Char)(auto  ref  Range s,  const(Char)[]  sub) if (!(isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
     isSomeChar!Char)  &&
     is(StringTypeOf!Range))

ptrdiff_t indexOf(Range,  Char)(auto  ref  Range s,  const(Char)[]  sub,
         in  CaseSensitive cs) if (!(isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
     isSomeChar!Char)  &&
     is(StringTypeOf!Range))

ptrdiff_t lastIndexOf(Char)(const(Char)[]  s,  in  dchar  c,
         in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char)

@safe pureSearches for the last occurrence of a character in a string.

ptrdiff_t lastIndexOf(Char)(const(Char)[]  s,  in  dchar  c,  in  size_t startIdx,
         in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char)

@safe pureDitto

ptrdiff_t lastIndexOf(Char1,  Char2)(const(Char1)[]  s,  const(Char2)[]  sub,
         in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char1 &&  isSomeChar!Char2)

@safe pureSearches for the last occurrence of a substring in a string.

ptrdiff_t lastIndexOf(Char1,  Char2)(const(Char1)[]  s,  const(Char2)[]  sub,
         in  size_t startIdx,  in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char1 &&  isSomeChar!Char2)

@safe pureDitto

private fn

ptrdiff_t indexOfAnyNeitherImpl(bool  forward,  bool  any,  Char,  Char2)(
         const(Char)[]  haystack,  const(Char2)[]  needles,
         in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char &&  isSomeChar!Char2)

@safe pure

ptrdiff_t indexOfAny(Char, Char2)(const(Char)[]  haystack,  const(Char2)[]  needles,
         in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char &&  isSomeChar!Char2)

@safe pureSearches the string `haystack` for one of the characters in `needles` starting at index `startIdx`. If `startIdx` is not given, it defaults to 0.

ptrdiff_t indexOfAny(Char, Char2)(const(Char)[]  haystack,  const(Char2)[]  needles,
         in  size_t startIdx,  in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char &&  isSomeChar!Char2)

@safe pureDitto

ptrdiff_t lastIndexOfAny(Char, Char2)(const(Char)[]  haystack,
         const(Char2)[]  needles,  in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char &&  isSomeChar!Char2)

@safe pureSearches `haystack` for the last occurrence of any of the characters in `needles`.

ptrdiff_t lastIndexOfAny(Char, Char2)(const(Char)[]  haystack,
         const(Char2)[]  needles,  in  size_t stopIdx,
         in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char &&  isSomeChar!Char2)

@safe pureDitto

ptrdiff_t indexOfNeither(Char, Char2)(const(Char)[]  haystack,
         const(Char2)[]  needles,  in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char &&  isSomeChar!Char2)

@safe pureSearches `haystack` for a character not in `needles`.

ptrdiff_t indexOfNeither(Char, Char2)(const(Char)[]  haystack,
         const(Char2)[]  needles,  in  size_t startIdx,
         in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char &&  isSomeChar!Char2)

@safe pureDitto

ptrdiff_t lastIndexOfNeither(Char, Char2)(const(Char)[]  haystack,
         const(Char2)[]  needles,  in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char &&  isSomeChar!Char2)

@safe pureSearches for the last character in `haystack` that is not in `needles`.

ptrdiff_t lastIndexOfNeither(Char, Char2)(const(Char)[]  haystack,
         const(Char2)[]  needles,  in  size_t stopIdx,
         in  CaseSensitive cs =  Yes.caseSensitive) if (isSomeChar!Char &&  isSomeChar!Char2)

@safe pureDitto

fnauto representation(Char)(Char[] s) if (isSomeChar!Char) @safe pure nothrow @nogcReturns 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.

fnS capitalize(S)(S input) if (isSomeString!S) @trusted pureCapitalize the first character of `s` and convert the rest of `s` to lowercase.

fnauto capitalize(S)(auto ref S s) if (!isSomeString!S && is(StringTypeOf!S))

fnC[][] splitLines(C)(C[] s, KeepTerminator keepTerm = No.keepTerminator) if (isSomeChar!C) @safe pureditto

auto lineSplitter(KeepTerminator keepTerm =  No.keepTerminator,  Range)(Range r) if (hasSlicing!Range &&  hasLength!Range &&  isSomeChar!(ElementType!Range)  && !isSomeString!Range)

* Split an array or slicable range of characters into a range of lines using `'\r'`, `'\n'`, `'\v'`, `'\f'`, `"\r\n"`, lineSep, paraSep and `'\u0085'` (NEL) as delimiters. If `keepTerm` is set to ...

fnauto lineSplitter(KeepTerminator keepTerm = No.keepTerminator, C)(C[] r) if (isSomeChar!C)Ditto

auto stripLeft(Range)(Range input) if (isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
    !isInfinite!Range && !isConvertibleToString!Range)

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

fnauto stripLeft(Range)(auto ref Range str) if (isConvertibleToString!Range)

auto stripLeft(Range,  Char)(Range input,  const(Char)[]  chars) if (((isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range))  ||
      isConvertibleToString!Range)  &&  isSomeChar!Char)

Ditto

auto stripRight(Range)(Range str) if (isSomeString!Range ||
     isRandomAccessRange!Range &&  hasLength!Range &&  hasSlicing!Range &&
    !isConvertibleToString!Range &&
     isSomeChar!(ElementEncodingType!Range))

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

fnauto stripRight(Range)(auto ref Range str) if (isConvertibleToString!Range)

auto stripRight(Range,  Char)(Range str,  const(Char)[]  chars) if (((isBidirectionalRange!Range &&  isSomeChar!(ElementEncodingType!Range))  ||
      isConvertibleToString!Range)  &&  isSomeChar!Char)

Ditto

auto strip(Range)(Range str) if (isSomeString!Range ||
     isRandomAccessRange!Range &&  hasLength!Range &&  hasSlicing!Range &&
    !isConvertibleToString!Range &&
     isSomeChar!(ElementEncodingType!Range))

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

fnauto strip(Range)(auto ref Range str) if (isConvertibleToString!Range)

auto strip(Range,  Char)(Range str,  const(Char)[]  chars) if (((isBidirectionalRange!Range &&  isSomeChar!(ElementEncodingType!Range))  ||
      isConvertibleToString!Range)  &&  isSomeChar!Char)

Ditto

auto strip(Range,  Char)(Range str,  const(Char)[]  leftChars,  const(Char)[]  rightChars) if (((isBidirectionalRange!Range &&  isSomeChar!(ElementEncodingType!Range))  ||
      isConvertibleToString!Range)  &&  isSomeChar!Char)

Ditto

Range chomp(Range)(Range str) if ((isRandomAccessRange!Range &&  isSomeChar!(ElementEncodingType!Range)  ||
     isNarrowString!Range)  &&
    !isConvertibleToString!Range)

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.

Range chomp(Range,  C2)(Range str,  const(C2)[]  delimiter) if ((isBidirectionalRange!Range &&  isSomeChar!(ElementEncodingType!Range)  ||
     isNarrowString!Range)  &&
    !isConvertibleToString!Range &&
     isSomeChar!C2)

Ditto

fnStringTypeOf!Range chomp(Range)(auto ref Range str) if (isConvertibleToString!Range)

fnStringTypeOf!Range chomp(Range, C2)(auto ref Range str, const(C2)[] delimiter) if (isConvertibleToString!Range)

Range chompPrefix(Range,  C2)(Range str,  const(C2)[]  delimiter) if ((isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range)  ||
     isNarrowString!Range)  &&
    !isConvertibleToString!Range &&
     isSomeChar!C2)

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

StringTypeOf!Range chompPrefix(Range,  C2)(auto  ref  Range str,  const(C2)[]  delimiter) if (isConvertibleToString!Range)

Range chop(Range)(Range str) if ((isBidirectionalRange!Range &&  isSomeChar!(ElementEncodingType!Range)  ||
     isNarrowString!Range)  &&
    !isConvertibleToString!Range)

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.

fnStringTypeOf!Range chop(Range)(auto ref Range str) if (isConvertibleToString!Range)

fnS leftJustify(S)(S s, size_t width, dchar fillChar = ' ') if (isSomeString!S)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.

auto leftJustifier(Range)(Range r,  size_t width,  dchar  fillChar =  ' ') if (isInputRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
    !isConvertibleToString!Range)

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.

fnauto leftJustifier(Range)(auto ref Range r, size_t width, dchar fillChar = ' ') if (isConvertibleToString!Range)

fnS rightJustify(S)(S s, size_t width, dchar fillChar = ' ') if (isSomeString!S)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.

auto rightJustifier(Range)(Range r,  size_t width,  dchar  fillChar =  ' ') if (isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
    !isConvertibleToString!Range)

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.

fnauto rightJustifier(Range)(auto ref Range r, size_t width, dchar fillChar = ' ') if (isConvertibleToString!Range)

fnS center(S)(S s, size_t width, dchar fillChar = ' ') if (isSomeString!S)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.

auto centerJustifier(Range)(Range r,  size_t width,  dchar  fillChar =  ' ') if (isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
    !isConvertibleToString!Range)

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.

fnauto centerJustifier(Range)(auto ref Range r, size_t width, dchar fillChar = ' ') if (isConvertibleToString!Range)

auto detab(Range)(auto  ref  Range s,  size_t tabSize =  8) if ((isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range))
     ||  __traits(compiles,  StringTypeOf!Range))

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

auto detabber(Range)(Range r,  size_t tabSize =  8) if (isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
    !isConvertibleToString!Range)

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

fnauto detabber(Range)(auto ref Range r, size_t tabSize = 8) if (isConvertibleToString!Range)ditto

fnauto entab(Range)(Range s, size_t tabSize = 8) if (isForwardRange!Range && isSomeChar!(ElementEncodingType!Range))Replaces spaces in `s` with the optimal number of tabs. All spaces and tabs at the end of a line are removed.

auto entab(Range)(auto  ref  Range s,  size_t tabSize =  8) if (!(isForwardRange!Range &&  isSomeChar!(ElementEncodingType!Range))  &&
     is(StringTypeOf!Range))

fnauto entabber(Range)(Range r, size_t tabSize = 8) if (isForwardRange!Range && !isConvertibleToString!Range)Replaces spaces in range `r` with the optimal number of tabs. All spaces and tabs at the end of a line are removed.

fnauto entabber(Range)(auto ref Range r, size_t tabSize = 8) if (isConvertibleToString!Range)

C1[] translate(C1,  C2 =  immutable  char)(C1[]  str,
                                         in  dchar[dchar]  transTable,
                                         const(C2)[]  toRemove =  null) if (isSomeChar!C1 &&  isSomeChar!C2)

@safe pureReplaces 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` o...

C1[] translate(C1,  S,  C2 =  immutable  char)(C1[]  str,
                                            in  S[dchar]  transTable,
                                            const(C2)[]  toRemove =  null) if (isSomeChar!C1 &&  isSomeString!S &&  isSomeChar!C2)

@safe pureDitto

void translate(C1,  C2 =  immutable  char,  Buffer)(const(C1)[]  str,
                                         in  dchar[dchar]  transTable,
                                         const(C2)[]  toRemove,
                                         Buffer buffer) if (isSomeChar!C1 &&  isSomeChar!C2 &&  isOutputRange!(Buffer,  C1))

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

void translate(C1,  S,  C2 =  immutable  char,  Buffer)(C1[]  str,
                                                    in  S[dchar]  transTable,
                                                    const(C2)[]  toRemove,
                                                    Buffer buffer) if (isSomeChar!C1 &&  isSomeString!S &&  isSomeChar!C2 &&  isOutputRange!(Buffer,  S))

Ditto

private fn

void translateImpl(C1,  T,  C2,  Buffer)(const(C1)[]  str,
                                       scope  T transTable,
                                       const(C2)[]  toRemove,
                                       Buffer buffer)

C[] translate(C =  immutable  char)(scope  const(char)[]  str,  scope  const(char)[]  transTable,
               scope  const(char)[]  toRemove =  null) if (is(immutable  C ==  immutable  char))

@trusted pure nothrowThis 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.

fnstring makeTrans(scope const(char)[] from, scope const(char)[] to) @trusted pure nothrowDo same thing as makeTransTable but allocate the translation table on the GC heap.

fnchar[256] makeTransTable(scope const(char)[] from, scope const(char)[] to) @safe pure nothrow @nogcConstruct 256 character translation table, where characters in from[] are replaced by corresponding characters in to[].

void translate(C =  immutable  char,  Buffer)(scope  const(char)[]  str,  scope  const(char)[]  transTable,
         scope  const(char)[]  toRemove,  Buffer buffer) if (is(immutable  C ==  immutable  char)  &&  isOutputRange!(Buffer,  char))

@trusted pureThis is an ASCII-only overload of `translate` which takes an existing buffer to write the contents to.

fnS succ(S)(S s) if (isSomeString!S) @safe pureReturn 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 ...

C1[] tr(C1,  C2,  C3,  C4 =  immutable  char)(C1[]  str,  const(C2)[]  from,  const(C3)[]  to,  const(C4)[]  modifiers =  null)

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

bool isNumeric(S)(S s,  bool  bAllowSep =  false) if (isSomeString!S ||
    (isRandomAccessRange!S &&
     hasSlicing!S &&
     isSomeChar!(ElementType!S)  &&
    !isInfinite!S))

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 stri...

char[4] soundexer(Range)(Range str) if (isInputRange!Range &&  isSomeChar!(ElementEncodingType!Range)  &&
    !isConvertibleToString!Range)

Soundex algorithm.

fnchar[4] soundexer(Range)(auto ref Range str) if (isConvertibleToString!Range)ditto

fnchar[] soundex(scope const(char)[] str, return scope char[] buffer = null) @safe pure nothrowLike soundexer, but with different parameters and return value.

fnstring[string] abbrev(string[] values) @safe pureConstruct an associative array consisting of all abbreviations that uniquely map to the strings in values.

size_t column(Range)(Range str,  in  size_t tabsize =  8) if ((isInputRange!Range &&  isSomeChar!(ElementEncodingType!Range)  ||
     isNarrowString!Range)  &&
    !isConvertibleToString!Range)

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.

fnsize_t column(Range)(auto ref Range str, in size_t tabsize = 8) if (isConvertibleToString!Range)

S wrap(S)(S s,  in  size_t columns =  80,  S firstindent =  null,
 S indent =  null,  in  size_t tabsize =  8) if (isSomeString!S)

Wrap text into a paragraph.

fnS outdent(S)(S str) if (isSomeString!S) @safe pureRemoves one level of indentation from a multi-line string.

fnS[] outdent(S)(return scope S[] lines) if (isSomeString!S) @safe pureRemoves one level of indentation from an array of single-line strings.

auto assumeUTF(T)(T[]  arr) if (staticIndexOf!(immutable  T,  immutable  ubyte,  immutable  ushort,  immutable  uint) !=  - 1)

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

Templates 1

tmpl_indexOfStr(CaseSensitive cs)

Functions

ptrdiff_t _indexOfStr(Range, Char)(Range s, const(Char)[] sub) if (isForwardRange!Range && isSomeChar!(ElementEncodingType!Range) && isSomeChar!Char)

std.string

See Also

Copyright

License

Authors

Types 4

Parameters

Returns

See Also

Functions 90

Templates 1