Remove leading '*' from assumeUnique examples

That breaks `dlang.org/tools/dspec_tester.d` test extraction.
No other changes.
This commit is contained in:
Nick Treleaven 2022-10-17 13:29:14 +01:00 committed by The Dlang Bot
parent f0c5941be3
commit acde2b81cb

View file

@ -799,108 +799,107 @@ enum emptyExceptionMsg = "<Empty Exception Message>";
} }
/** /**
* Casts a mutable array to an immutable array in an idiomatic Casts a mutable array to an immutable array in an idiomatic
* manner. Technically, `assumeUnique` just inserts a cast, manner. Technically, `assumeUnique` just inserts a cast,
* but its name documents assumptions on the part of the but its name documents assumptions on the part of the
* caller. `assumeUnique(arr)` should only be called when caller. `assumeUnique(arr)` should only be called when
* there are no more active mutable aliases to elements of $(D there are no more active mutable aliases to elements of $(D
* arr). To strengthen this assumption, `assumeUnique(arr)` arr). To strengthen this assumption, `assumeUnique(arr)`
* also clears `arr` before returning. Essentially $(D also clears `arr` before returning. Essentially $(D
* assumeUnique(arr)) indicates commitment from the caller that there assumeUnique(arr)) indicates commitment from the caller that there
* is no more mutable access to any of `arr`'s elements is no more mutable access to any of `arr`'s elements
* (transitively), and that all future accesses will be done through (transitively), and that all future accesses will be done through
* the immutable array returned by `assumeUnique`. the immutable array returned by `assumeUnique`.
*
* Typically, `assumeUnique` is used to return arrays from Typically, `assumeUnique` is used to return arrays from
* functions that have allocated and built them. functions that have allocated and built them.
*
* Params: Params:
* array = The array to cast to immutable. array = The array to cast to immutable.
*
* Returns: The immutable array. Returns: The immutable array.
*
* Example: Example:
*
* $(RUNNABLE_EXAMPLE $(RUNNABLE_EXAMPLE
* ---- ----
* string letters() string letters()
* { {
* char[] result = new char['z' - 'a' + 1]; char[] result = new char['z' - 'a' + 1];
* foreach (i, ref e; result) foreach (i, ref e; result)
* { {
* e = cast(char)('a' + i); e = cast(char)('a' + i);
* } }
* return assumeUnique(result); return assumeUnique(result);
* } }
* ---- ----
* ) )
*
* The use in the example above is correct because `result` The use in the example above is correct because `result`
* was private to `letters` and is inaccessible in writing was private to `letters` and is inaccessible in writing
* after the function returns. The following example shows an after the function returns. The following example shows an
* incorrect use of `assumeUnique`. incorrect use of `assumeUnique`.
*
* Bad: Bad:
*
* $(RUNNABLE_EXAMPLE $(RUNNABLE_EXAMPLE
* ---- ----
* private char[] buffer; private char[] buffer;
* string letters(char first, char last) string letters(char first, char last)
* { {
* if (first >= last) return null; // fine if (first >= last) return null; // fine
* auto sneaky = buffer; auto sneaky = buffer;
* sneaky.length = last - first + 1; sneaky.length = last - first + 1;
* foreach (i, ref e; sneaky) foreach (i, ref e; sneaky)
* { {
* e = cast(char)('a' + i); e = cast(char)('a' + i);
* } }
* return assumeUnique(sneaky); // BAD return assumeUnique(sneaky); // BAD
* } }
* ---- ----
* ) )
*
* The example above wreaks havoc on client code because it is The example above wreaks havoc on client code because it is
* modifying arrays that callers considered immutable. To obtain an modifying arrays that callers considered immutable. To obtain an
* immutable array from the writable array `buffer`, replace immutable array from the writable array `buffer`, replace
* the last line with: the last line with:
*
* ---- ----
* return to!(string)(sneaky); // not that sneaky anymore return to!(string)(sneaky); // not that sneaky anymore
* ---- ----
*
* The call will duplicate the array appropriately. The call will duplicate the array appropriately.
*
* Note that checking for uniqueness during compilation is Note that checking for uniqueness during compilation is
* possible in certain cases, especially when a function is possible in certain cases, especially when a function is
* marked as a pure function. The following example does not marked as a pure function. The following example does not
* need to call assumeUnique because the compiler can infer the need to call assumeUnique because the compiler can infer the
* uniqueness of the array in the pure function: uniqueness of the array in the pure function:
*
* $(RUNNABLE_EXAMPLE $(RUNNABLE_EXAMPLE
* ---- ----
* string letters() pure string letters() pure
* { {
* char[] result = new char['z' - 'a' + 1]; char[] result = new char['z' - 'a' + 1];
* foreach (i, ref e; result) foreach (i, ref e; result)
* { {
* e = cast(char)('a' + i); e = cast(char)('a' + i);
* } }
* return result; return result;
* } }
* ---- ----
* ) )
*
* For more on infering uniqueness see the $(B unique) and For more on infering uniqueness see the $(B unique) and
* $(B lent) keywords in the $(B lent) keywords in the
* $(HTTP www.cs.cmu.edu/~aldrich/papers/aldrich-dissertation.pdf, ArchJava) $(HTTP www.cs.cmu.edu/~aldrich/papers/aldrich-dissertation.pdf, ArchJava)
* language. language.
*
* The downside of using `assumeUnique`'s The downside of using `assumeUnique`'s
* convention-based usage is that at this time there is no convention-based usage is that at this time there is no
* formal checking of the correctness of the assumption; formal checking of the correctness of the assumption;
* on the upside, the idiomatic use of `assumeUnique` is on the upside, the idiomatic use of `assumeUnique` is
* simple and rare enough to be tolerable. simple and rare enough to be tolerable.
*
*/ */
immutable(T)[] assumeUnique(T)(T[] array) pure nothrow immutable(T)[] assumeUnique(T)(T[] array) pure nothrow
{ {