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