Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[std/exception] Tweak docs #8795

Merged
merged 2 commits into from Aug 12, 2023
Merged

[std/exception] Tweak docs #8795

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a2df1e6
[std/exception] Use PANEL macro to group paragraphs
ntrel Aug 11, 2023
d31490e
Tweak wording of assumeUnique
ntrel Aug 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
25 changes: 15 additions & 10 deletions std/exception.d
View file
Open in desktop
Expand Up @@ -416,13 +416,16 @@ void assertThrown(T : Throwable = Exception, E)
Returns: `value`, if `cast(bool) value` is true. Otherwise,
depending on the chosen overload, `new Exception(msg)`, `dg()` or `ex` is thrown.

Note:
`enforce` is used to throw exceptions and is therefore intended to
$(PANEL
$(NOTE `enforce` is used to throw exceptions and is therefore intended to
aid in error handling. It is $(I not) intended for verifying the logic
of your program. That is what `assert` is for. Also, do not use
of your program - that is what `assert` is for.)

Do not use
`enforce` inside of contracts (i.e. inside of `in` and `out`
blocks and `invariant`s), because contracts are compiled out when
compiling with $(I -release).
)

If a delegate is passed, the safety and purity of this function are inferred
from `Dg`'s safety and purity.
Expand Down Expand Up @@ -836,7 +839,7 @@ string letters()
)

The use in the example above is correct because `result`
was private to `letters` and is inaccessible in writing
was private to `letters` and the memory it referenced can no longer be written to
after the function returns. The following example shows an
incorrect use of `assumeUnique`.

Expand All @@ -859,22 +862,23 @@ string letters(char first, char last)
----
)

The example above wreaks havoc on client code because it is
modifying arrays that callers considered immutable. To obtain an
The example above wreaks havoc on client code because it modifies the
returned array that the previous caller 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.
The `to` call will duplicate the array appropriately.

Note that checking for uniqueness during compilation is
$(PANEL
$(NOTE 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
marked (or inferred) as `pure`. The following example does not
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
----
Expand All @@ -894,6 +898,7 @@ 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
Expand Down