From a520b91f2db44d907ae132bdf3418ad003504ae4 Mon Sep 17 00:00:00 2001 From: "H. S. Teoh" Date: Sat, 29 Aug 2015 17:27:24 -0700 Subject: [PATCH 1/4] Add Params: and Returns: to fromStringz and toStringz. --- std/string.d | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/std/string.d b/std/string.d index e3afa7d12..d46443266 100644 --- a/std/string.d +++ b/std/string.d @@ -195,8 +195,11 @@ class StringException : Exception /++ - Returns a D-style array of $(D char) given a zero-terminated C-style string. - The returned array will retain the same type qualifiers as the input. + Params: + cString = A null-terminated c-style string. + + Returns: A D-style array of $(D char) referencing the same string. The + returned array will retain the same type qualifiers as the input. $(RED Important Note:) The returned array is a slice of the original buffer. The original data is not changed and not copied. @@ -215,15 +218,19 @@ inout(char)[] fromStringz(inout(char)* cString) @nogc @system pure nothrow { } /++ - Returns a C-style zero-terminated string equivalent to $(D s). $(D s) - must not contain embedded $(D '\0')'s as any C function will treat the first - $(D '\0') that it sees as the end of the string. If $(D s.empty) is + Params: + s = A D-style string. + + Returns: A C-style null-terminated string equivalent to $(D s). $(D s) + must not contain embedded $(D '\0')'s as any C function will treat the + first $(D '\0') that it sees as the end of the string. If $(D s.empty) is $(D true), then a string containing only $(D '\0') is returned. $(RED Important Note:) When passing a $(D char*) to a C function, and the C - function keeps it around for any reason, make sure that you keep a reference - to it in your D code. Otherwise, it may go away during a garbage collection - cycle and cause a nasty bug when the C code tries to use it. + function keeps it around for any reason, make sure that you keep a + reference to it in your D code. Otherwise, it may become invalid during a + garbage collection cycle and cause a nasty bug when the C code tries to use + it. +/ immutable(char)* toStringz(const(char)[] s) @trusted pure nothrow in From 46cb33d4bfa8edb936adcbb8af622bbd5a65ad31 Mon Sep 17 00:00:00 2001 From: "H. S. Teoh" Date: Sat, 29 Aug 2015 17:30:31 -0700 Subject: [PATCH 2/4] Add Params:, Returns:, to std.string.indexOf(). --- std/string.d | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/std/string.d b/std/string.d index d46443266..c3f7059eb 100644 --- a/std/string.d +++ b/std/string.d @@ -789,7 +789,13 @@ unittest } /++ - Returns the index of the first occurrence of $(D sub) in $(D s) with + 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 = CaseSensitive.yes or CaseSensitive.no + + Returns: The index of the first occurrence of $(D sub) in $(D s) with respect to the start index $(D startIdx). If $(D sub) is not found, then $(D -1) is returned. If $(D sub) is found the value of the returned index is at least $(D startIdx). $(D startIdx) represents a codeunit index in From f9fd7e6362ede8fbf58b0d8b4c6310793bd0e5bb Mon Sep 17 00:00:00 2001 From: "H. S. Teoh" Date: Sat, 29 Aug 2015 17:46:53 -0700 Subject: [PATCH 3/4] Add Params: and Returns: to lastIndexOf overloads. --- std/string.d | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/std/string.d b/std/string.d index c3f7059eb..8bdddea8c 100644 --- a/std/string.d +++ b/std/string.d @@ -790,7 +790,7 @@ unittest /++ Params: - s = string or ForwardRange of characters to search in correct UTF format + s = string to search sub = substring to search for startIdx = the index into s to start searching from cs = CaseSensitive.yes or CaseSensitive.no @@ -879,7 +879,12 @@ ptrdiff_t indexOf(Char1, Char2)(const(Char1)[] s, const(Char2)[] sub, } /++ - Returns the index of the last occurrence of $(D c) in $(D s). If $(D c) + Params: + s = string to search + c = character to search for + cs = CaseSensitive.yes or CaseSensitive.no + + Returns: The index of the last occurrence of $(D c) in $(D s). If $(D c) is not found, then $(D -1) is returned. $(D cs) indicates whether the comparisons are case sensitive. @@ -987,7 +992,13 @@ ptrdiff_t lastIndexOf(Char)(const(Char)[] s, in dchar c, } /++ - Returns the index of the last occurrence of $(D c) in $(D s). If $(D c) is + Params: + s = string to search + c = character to search for + startIdx = the index into s to start searching from + cs = CaseSensitive.yes or CaseSensitive.no + + Returns: The index of the last occurrence of $(D c) in $(D s). If $(D c) is not found, then $(D -1) is returned. The $(D startIdx) slices $(D s) in the following way $(D s[0 .. startIdx]). $(D startIdx) represents a codeunit index in $(D s). If the sequence ending at $(D startIdx) does not @@ -1043,7 +1054,12 @@ ptrdiff_t lastIndexOf(Char)(const(Char)[] s, in dchar c, in size_t startIdx, } /++ - Returns the index of the last occurrence of $(D sub) in $(D s). If $(D sub) + Params: + s = string to search + sub = substring to search for + cs = CaseSensitive.yes or CaseSensitive.no + + Returns: the index of the last occurrence of $(D sub) in $(D s). If $(D sub) is not found, then $(D -1) is returned. $(D cs) indicates whether the comparisons are case sensitive. @@ -1204,7 +1220,13 @@ ptrdiff_t lastIndexOf(Char1, Char2)(const(Char1)[] s, const(Char2)[] sub, } /++ - Returns the index of the last occurrence of $(D sub) in $(D s). If $(D sub) + Params: + s = string to search + sub = substring to search for + startIdx = the index into s to start searching from + cs = CaseSensitive.yes or CaseSensitive.no + + Returns: the index of the last occurrence of $(D sub) in $(D s). If $(D sub) is not found, then $(D -1) is returned. The $(D startIdx) slices $(D s) in the following way $(D s[0 .. startIdx]). $(D startIdx) represents a codeunit index in $(D s). If the sequence ending at $(D startIdx) does not From ebe9f5824fb2cb6f078f727feaf8a4eaeb9777c9 Mon Sep 17 00:00:00 2001 From: "H. S. Teoh" Date: Sat, 29 Aug 2015 17:50:16 -0700 Subject: [PATCH 4/4] Add Params: and Returns: for std.string.center. --- std/string.d | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/std/string.d b/std/string.d index 8bdddea8c..ae841cb7a 100644 --- a/std/string.d +++ b/std/string.d @@ -3644,6 +3644,16 @@ unittest Center $(D s) in a field $(D width) characters wide. $(D fillChar) is the character that will be used to fill up the space in the field that $(D s) doesn't fill. + + Params: + s = The string to center + width = Width of the field to center `s` in + fillChar = The character to use for filling excess space in the field + + Returns: + The resulting _center-justified string. The returned string is + GC-allocated. To avoid GC allocation, use $(LREF centerJustifier) + instead. +/ S center(S)(S s, size_t width, dchar fillChar = ' ') if (isSomeString!S)