-<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="throw">Throw Only std::string</a></div>
-<div class="doc_text">
- <p>If an error occurs that lib/System cannot handle, the only action taken by
- lib/System is to throw an instance of std:string. The contents of the string
- must explain both what happened and the context in which it happened. The
- format of the string should be a (possibly empty) list of contexts each
- terminated with a : and a space, followed by the error message, optionally
- followed by a reason, and optionally followed by a suggestion.</p>
- <p>For example, failure to open a file named "foo" could result in a message
- like:</p>
- <ul><li>foo: Unable to open file because it doesn't exist."</li></ul>
- <p>The "foo:" part is the context. The "Unable to open file" part is the error
- message. The "because it doesn't exist." part is the reason. This message has
- no suggestion. Where possible, the implementation of lib/System should use
- operating system specific facilities for converting the error code returned by
- a system call into an error message. This will help to make the error message
- more familiar to users of that type of operating system.</p>
- <p>Note that this requirement precludes the throwing of any other exceptions.
- For example, various C++ standard library functions can cause exceptions to be
- thrown (e.g. out of memory situation). In all cases, if there is a possibility
- that non-string exceptions could be thrown, the lib/System library must ensure
- that the exceptions are translated to std::string form.</p>
-</div>
-