mirror of
https://github.com/dlang/phobos.git
synced 2025-04-26 05:00:35 +03:00
overhaul documentation of std.string indexOf-like functions (#8560)
This commit is contained in:
wolframw
GitHub
parent
2852e84aa9
commit
54cfc22c73
1 changed files with 131 additions and 97 deletions
228
std/string.d
228
std/string.d
|
|
@ -457,26 +457,26 @@ pure nothrow @system unittest // https://issues.dlang.org/show_bug.cgi?id=15136
|
|||
alias CaseSensitive = Flag!"caseSensitive";
|
||||
|
||||
/++
|
||||
Searches for character in range.
|
||||
Searches for a character in a string or range.
|
||||
|
||||
Params:
|
||||
s = string or InputRange of characters to search in correct UTF format
|
||||
c = character to search for
|
||||
startIdx = starting index to a well-formed code point
|
||||
cs = `Yes.caseSensitive` or `No.caseSensitive`
|
||||
s = string or InputRange of characters to search for `c` in
|
||||
c = character to search for in `s`
|
||||
startIdx = index to a well-formed code point in `s` to start
|
||||
searching from; defaults to 0
|
||||
cs = specifies whether comparisons are case-sensitive
|
||||
(`Yes.caseSensitive`) or not (`No.caseSensitive`).
|
||||
|
||||
Returns:
|
||||
the index of the first occurrence of `c` in `s` with
|
||||
respect to the start index `startIdx`. If `c`
|
||||
is not found, then `-1` is returned.
|
||||
If `c` is found the value of the returned index is at least
|
||||
`startIdx`.
|
||||
If the parameters are not valid UTF, the result will still
|
||||
be in the range [-1 .. s.length], but will not be reliable otherwise.
|
||||
If `c` is found in `s`, then the index of its first occurrence is
|
||||
returned. If `c` is not found or `startIdx` is greater than or equal to
|
||||
`s.length`, then -1 is returned. If the parameters are not valid UTF,
|
||||
the result will still be either -1 or in the range [`startIdx` ..
|
||||
`s.length`], but will not be reliable otherwise.
|
||||
|
||||
Throws:
|
||||
If the sequence starting at `startIdx` does not represent a well
|
||||
formed codepoint, then a $(REF UTFException, std,utf) may be thrown.
|
||||
If the sequence starting at `startIdx` does not represent a well-formed
|
||||
code point, then a $(REF UTFException, std,utf) may be thrown.
|
||||
|
||||
See_Also: $(REF countUntil, std,algorithm,searching)
|
||||
+/
|
||||
|
|
@ -901,30 +901,30 @@ private template _indexOfStr(CaseSensitive cs)
|
|||
}
|
||||
|
||||
/++
|
||||
Searches for substring in `s`.
|
||||
Searches for a substring in a string or range.
|
||||
|
||||
Params:
|
||||
s = string or ForwardRange of characters to search in correct UTF format
|
||||
sub = substring to search for
|
||||
startIdx = the index into s to start searching from
|
||||
cs = `Yes.caseSensitive` (default) or `No.caseSensitive`
|
||||
s = string or ForwardRange of characters to search for `sub` in
|
||||
sub = substring to search for in `s`
|
||||
startIdx = index to a well-formed code point in `s` to start
|
||||
searching from; defaults to 0
|
||||
cs = specifies whether comparisons are case-sensitive
|
||||
(`Yes.caseSensitive`) or not (`No.caseSensitive`)
|
||||
|
||||
Returns:
|
||||
the index of the first occurrence of `sub` in `s` with
|
||||
respect to the start index `startIdx`. If `sub` is not found,
|
||||
then `-1` is returned.
|
||||
If the arguments are not valid UTF, the result will still
|
||||
be in the range [-1 .. s.length], but will not be reliable otherwise.
|
||||
If `sub` is found the value of the returned index is at least
|
||||
`startIdx`.
|
||||
The index of the first occurrence of `sub` in `s`. If `sub` is not found
|
||||
or `startIdx` is greater than or equal to `s.length`, then -1 is
|
||||
returned. If the arguments are not valid UTF, the result will still be
|
||||
either -1 or in the range [`startIdx` .. `s.length`], but will not be
|
||||
reliable otherwise.
|
||||
|
||||
Throws:
|
||||
If the sequence starting at `startIdx` does not represent a well
|
||||
formed codepoint, then a $(REF UTFException, std,utf) may be thrown.
|
||||
If the sequence starting at `startIdx` does not represent a well-formed
|
||||
code point, then a $(REF UTFException, std,utf) may be thrown.
|
||||
|
||||
Bugs:
|
||||
Does not work with case insensitive strings where the mapping of
|
||||
tolower and toupper is not 1:1.
|
||||
Does not work with case-insensitive strings where the mapping of
|
||||
$(REF toLower, std,uni) and $(REF toUpper, std,uni) is not 1:1.
|
||||
+/
|
||||
ptrdiff_t indexOf(Range, Char)(Range s, const(Char)[] sub)
|
||||
if (isForwardRange!Range && isSomeChar!(ElementEncodingType!Range) &&
|
||||
|
|
@ -1156,23 +1156,26 @@ unittest
|
|||
}
|
||||
|
||||
/++
|
||||
Searches for the last occurrence of a character in a string.
|
||||
|
||||
Params:
|
||||
s = string to search
|
||||
c = character to search for
|
||||
startIdx = the index into s to start searching from
|
||||
cs = `Yes.caseSensitive` or `No.caseSensitive`
|
||||
s = string to search for `c` in
|
||||
c = character to search for in `s`
|
||||
startIdx = index of a well-formed code point in `s` to start searching
|
||||
from; defaults to 0
|
||||
cs = specifies whether comparisons are case-sensitive
|
||||
(`Yes.caseSensitive`) or not (`No.caseSensitive`)
|
||||
|
||||
Returns:
|
||||
The index of the last occurrence of `c` in `s`. If `c` is not
|
||||
found, then `-1` is returned. The `startIdx` slices `s` in
|
||||
the following way $(D s[0 .. startIdx]). `startIdx` represents a
|
||||
codeunit index in `s`.
|
||||
If `c` is found in `s`, then the index of its last occurrence is
|
||||
returned. If `c` is not found or `startIdx` is greater than or equal to
|
||||
`s.length`, then -1 is returned. If the parameters are not valid UTF,
|
||||
the result will still be either -1 or in the range [`startIdx` ..
|
||||
`s.length`], but will not be reliable otherwise.
|
||||
|
||||
Throws:
|
||||
If the sequence ending at `startIdx` does not represent a well
|
||||
formed codepoint, then a $(REF UTFException, std,utf) may be thrown.
|
||||
|
||||
`cs` indicates whether the comparisons are case sensitive.
|
||||
If the sequence ending at `startIdx` does not represent a well-formed
|
||||
code point, then a $(REF UTFException, std,utf) may be thrown.
|
||||
+/
|
||||
ptrdiff_t lastIndexOf(Char)(const(Char)[] s, in dchar c,
|
||||
in CaseSensitive cs = Yes.caseSensitive) @safe pure
|
||||
|
|
@ -1345,23 +1348,30 @@ if (isSomeChar!Char)
|
|||
}
|
||||
|
||||
/++
|
||||
Searches for the last occurrence of a substring in a string.
|
||||
|
||||
Params:
|
||||
s = string to search
|
||||
sub = substring to search for
|
||||
startIdx = the index into s to start searching from
|
||||
cs = `Yes.caseSensitive` or `No.caseSensitive`
|
||||
s = string to search for `sub` in
|
||||
sub = substring to search for in `s`
|
||||
startIdx = index to a well-formed code point in `s` to start
|
||||
searching from; defaults to 0
|
||||
cs = specifies whether comparisons are case-sensitive
|
||||
(`Yes.caseSensitive`) or not (`No.caseSensitive`)
|
||||
|
||||
Returns:
|
||||
the index of the last occurrence of `sub` in `s`. If `sub` is
|
||||
not found, then `-1` is returned. The `startIdx` slices `s`
|
||||
in the following way $(D s[0 .. startIdx]). `startIdx` represents a
|
||||
codeunit index in `s`.
|
||||
The index of the last occurrence of `sub` in `s`. If `sub` is not found
|
||||
or `startIdx` is greater than or equal to `s.length`, then -1 is
|
||||
returned. If the parameters are not valid UTF, the result will still be
|
||||
either -1 or in the range [`startIdx` .. `s.length`], but will not be
|
||||
reliable otherwise.
|
||||
|
||||
Throws:
|
||||
If the sequence ending at `startIdx` does not represent a well
|
||||
formed codepoint, then a $(REF UTFException, std,utf) may be thrown.
|
||||
If the sequence starting at `startIdx` does not represent a well-formed
|
||||
code point, then a $(REF UTFException, std,utf) may be thrown.
|
||||
|
||||
`cs` indicates whether the comparisons are case sensitive.
|
||||
Bugs:
|
||||
Does not work with case-insensitive strings where the mapping of
|
||||
$(REF toLower, std,uni) and $(REF toUpper, std,uni) is not 1:1.
|
||||
+/
|
||||
ptrdiff_t lastIndexOf(Char1, Char2)(const(Char1)[] s, const(Char2)[] sub,
|
||||
in CaseSensitive cs = Yes.caseSensitive) @safe pure
|
||||
|
|
@ -1747,21 +1757,28 @@ if (isSomeChar!Char && isSomeChar!Char2)
|
|||
}
|
||||
|
||||
/**
|
||||
Returns the index of the first occurrence of any of the elements in $(D
|
||||
needles) in `haystack`. If no element of `needles` is found,
|
||||
then `-1` is returned. The `startIdx` slices `haystack` in the
|
||||
following way $(D haystack[startIdx .. $]). `startIdx` represents a
|
||||
codeunit index in `haystack`. If the sequence ending at `startIdx`
|
||||
does not represent a well formed codepoint, then a $(REF UTFException, std,utf)
|
||||
may be thrown.
|
||||
Searches the string `haystack` for one of the characters in `needles`
|
||||
starting at index `startIdx`. If `startIdx` is not given, it defaults to 0.
|
||||
|
||||
Params:
|
||||
haystack = String to search for needles in.
|
||||
needles = Strings to search for in haystack.
|
||||
startIdx = slices haystack like this $(D haystack[startIdx .. $]). If
|
||||
the startIdx is greater than or equal to the length of haystack the
|
||||
functions returns `-1`.
|
||||
cs = Indicates whether the comparisons are case sensitive.
|
||||
haystack = string to search for needles in
|
||||
needles = characters to search for in `haystack`
|
||||
startIdx = index of a well-formed code point in `haystack` to start
|
||||
searching from; defaults to 0
|
||||
cs = specifies whether comparisons are case-sensitive
|
||||
(`Yes.caseSensitive`) or not (`No.caseSensitive`)
|
||||
|
||||
Returns:
|
||||
The index of the first occurrence of any of the elements of `needles` in
|
||||
`haystack`. If no element of `needles` is found or `startIdx` is greater
|
||||
than or equal to `haystack.length`, then -1 is returned. If the
|
||||
parameters are not valid UTF, the result will still be either -1 or in
|
||||
the range [`startIdx` .. `haystack.length`], but will not be reliable
|
||||
otherwise.
|
||||
|
||||
Throws:
|
||||
If the sequence starting at `startIdx` does not represent a well-formed
|
||||
code point, then a $(REF UTFException, std,utf) may be thrown.
|
||||
*/
|
||||
ptrdiff_t indexOfAny(Char,Char2)(const(Char)[] haystack, const(Char2)[] needles,
|
||||
in CaseSensitive cs = Yes.caseSensitive) @safe pure
|
||||
|
|
@ -1914,21 +1931,23 @@ if (isSomeChar!Char && isSomeChar!Char2)
|
|||
}
|
||||
|
||||
/**
|
||||
Returns the index of the last occurrence of any of the elements in $(D
|
||||
needles) in `haystack`. If no element of `needles` is found,
|
||||
then `-1` is returned. The `stopIdx` slices `haystack` in the
|
||||
following way $(D 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 $(REF UTFException, std,utf) may be
|
||||
thrown.
|
||||
Searches `haystack` for the last occurrence of any of the
|
||||
characters in `needles`.
|
||||
|
||||
Params:
|
||||
haystack = String to search for needles in.
|
||||
needles = Strings to search for in haystack.
|
||||
stopIdx = slices haystack like this $(D haystack[0 .. stopIdx]). If
|
||||
the stopIdx is greater than or equal to the length of haystack the
|
||||
functions returns `-1`.
|
||||
cs = Indicates whether the comparisons are case sensitive.
|
||||
haystack = string to search needles in
|
||||
needles = characters to search for in `haystack`
|
||||
stopIdx = index in `haystack` to stop searching at (exclusive); defaults
|
||||
to `haystack.length`
|
||||
cs = specifies whether comparisons are case-sensitive
|
||||
(`Yes.caseSensitive`) or not (`No.caseSensitive`)
|
||||
|
||||
Returns:
|
||||
The index of the last occurrence of any of the characters of `needles`
|
||||
in `haystack`. If no character of `needles` is found or `stopIdx` is 0,
|
||||
then -1 is returned. If the parameters are not valid UTF, the result
|
||||
will still be in the range [-1 .. `stopIdx`], but will not be reliable
|
||||
otherwise.
|
||||
*/
|
||||
ptrdiff_t lastIndexOfAny(Char,Char2)(const(Char)[] haystack,
|
||||
const(Char2)[] needles, in CaseSensitive cs = Yes.caseSensitive)
|
||||
|
|
@ -2097,17 +2116,27 @@ if (isSomeChar!Char && isSomeChar!Char2)
|
|||
}
|
||||
|
||||
/**
|
||||
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.
|
||||
Searches `haystack` for a character not in `needles`.
|
||||
|
||||
Params:
|
||||
haystack = String to search for needles in.
|
||||
needles = Strings to search for in haystack.
|
||||
startIdx = slices haystack like this $(D haystack[startIdx .. $]). If
|
||||
the startIdx is greater than or equal to the length of haystack the
|
||||
functions returns `-1`.
|
||||
cs = Indicates whether the comparisons are case sensitive.
|
||||
haystack = string to search for needles in
|
||||
needles = characters to search for in `haystack`
|
||||
startIdx = index of a well-formed code point in `haystack` to start
|
||||
searching from; defaults to 0
|
||||
cs = specifies whether comparisons are case-sensitive
|
||||
(`Yes.caseSensitive`) or not (`No.caseSensitive`)
|
||||
|
||||
Returns:
|
||||
The index of the first character in `haystack` that is not an element of
|
||||
`needles`. If all characters of `haystack` are elements of `needles` or
|
||||
`startIdx` is greater than or equal to `haystack.length`, then -1 is
|
||||
returned. If the parameters are not valid UTF, the result will still be
|
||||
either -1 or in the range [`startIdx` .. `haystack.length`], but will
|
||||
not be reliable otherwise.
|
||||
|
||||
Throws:
|
||||
If the sequence starting at `startIdx` does not represent a well-formed
|
||||
code point, then a $(REF UTFException, std,utf) may be thrown.
|
||||
*/
|
||||
ptrdiff_t indexOfNeither(Char,Char2)(const(Char)[] haystack,
|
||||
const(Char2)[] needles, in CaseSensitive cs = Yes.caseSensitive)
|
||||
|
|
@ -2257,17 +2286,22 @@ if (isSomeChar!Char && isSomeChar!Char2)
|
|||
}
|
||||
|
||||
/**
|
||||
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.
|
||||
Searches for the last character in `haystack` that is not in `needles`.
|
||||
|
||||
Params:
|
||||
haystack = String to search for needles in.
|
||||
needles = Strings to search for in haystack.
|
||||
stopIdx = slices haystack like this $(D haystack[0 .. stopIdx]) If
|
||||
the stopIdx is greater than or equal to the length of haystack the
|
||||
functions returns `-1`.
|
||||
cs = Indicates whether the comparisons are case sensitive.
|
||||
haystack = string to search for needles in
|
||||
needles = characters to search for in `haystack`
|
||||
stopIdx = index in `haystack` to stop searching at (exclusive);
|
||||
defaults to `haystack.length`
|
||||
cs = specifies whether comparisons are case-sensitive
|
||||
(`Yes.caseSensitive`) or not (`No.caseSensitive`)
|
||||
|
||||
Returns:
|
||||
The index of the last character in `haystack` that is not an element of
|
||||
`needles`. If all characters of `haystack` are in `needles` or `stopIdx`
|
||||
is 0, then -1 is returned. If the parameters are not valid UTF, the
|
||||
result will still be in the range [-1 .. `stopIdx`], but will not be
|
||||
reliable otherwise.
|
||||
*/
|
||||
ptrdiff_t lastIndexOfNeither(Char,Char2)(const(Char)[] haystack,
|
||||
const(Char2)[] needles, in CaseSensitive cs = Yes.caseSensitive)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue