diff --git a/std/string.d b/std/string.d index 21e1ca356..bcc9d7c13 100644 --- a/std/string.d +++ b/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)