From 059f7c0a82d60a0ac1ece50961362ee4b00c0983 Mon Sep 17 00:00:00 2001 From: gammasoft71 Date: Fri, 4 Oct 2024 20:24:58 +0200 Subject: [PATCH] update excepion documentation --- .../How-tos/create_user_defined_exceptions.md | 1 + ...ions_with_localized_exception_messages .md | 39 ------------------- ...tions_with_localized_exception_messages.md | 13 +++++++ .../How-tos/exceptions_try_catch.md | 34 +++++++++++++++- .../exceptions_use_specific_exceptions.md | 1 + .../How-tos/explicitly_throw_exception.md | 1 + 6 files changed, 49 insertions(+), 40 deletions(-) delete mode 100644 docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions_with_localized_exception_messages .md create mode 100644 docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions_with_localized_exception_messages.md diff --git a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions.md b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions.md index 59635e86fdf7..250440ba22f9 100644 --- a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions.md +++ b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions.md @@ -31,6 +31,7 @@ public: # See also ​ +* [Exceptions](/docs/documentation/Guides/xtd.core/Exceptions/overview) * [Guides](/docs/documentation/Guides) * [Documentation](/docs/documentation) diff --git a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions_with_localized_exception_messages .md b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions_with_localized_exception_messages .md deleted file mode 100644 index 4ac85f4da3c6..000000000000 --- a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions_with_localized_exception_messages .md +++ /dev/null @@ -1,39 +0,0 @@ -# How to create user-defined exception with localized exception messages (xtd.core) - -xtd provides a hierarchy of exception classes ultimately derived from the Exception base class. -However, if none of the predefined exceptions meet your needs, you can create your own exception class by deriving from the [xtd::exception](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1exception.html) class. - -When creating your own exceptions, end the class name of the user-defined exception with the word "_exception", and implement the three common constructors, as shown in the following example. -The example defines a new exception class named `employee_list_not_found_exception`. The class is derived from the [xtd::exception](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1exception.html) base class and includes three constructors. - -```cpp -#include - -using xtd; - -class employee_list_not_found_exception : public exception { -public: - employee_list_not_found_exception(const xtd::diagnostics::stack_frame& stack_frame = xtd::diagnostics::stack_frame::empty()) : exception {"The employee list does not exist."_t, stack_frame} { - } - - employee_list_not_found_exception(const string& message, const xtd::diagnostics::stack_frame& stack_frame = xtd::diagnostics::stack_frame::empty()) : exception {message, stack_frame} { - } - - template - employee_list_not_found_exception(const string& message, const exception_t& inner, const xtd::diagnostics::stack_frame& stack_frame = xtd::diagnostics::stack_frame::empty()) : exception(message, inner, stack_frame) { - } -}; -``` - -> [!NOTE] -> In situations where you're using remoting, you must ensure that the metadata for any user-defined exceptions is available at the server (callee) and to the client (the proxy object or caller). -> For more information, see [Best practices for exceptions](/docs/documentation/Guides/xtd.core/Exceptions/exceptions_best_practices). - -# See also -​ -* [Guides](/docs/documentation/Guides) -* [Documentation](/docs/documentation) - -© 2024 Gammasoft. - -[//]: # (https://learn.microsoft.com/en-us/dotnet/standard/exceptions/how-to-create-localized-exception-messages) diff --git a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions_with_localized_exception_messages.md b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions_with_localized_exception_messages.md new file mode 100644 index 000000000000..d900ccac7e45 --- /dev/null +++ b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/create_user_defined_exceptions_with_localized_exception_messages.md @@ -0,0 +1,13 @@ +# How to create user-defined exception with localized exception messages (xtd.core) + +Coming soon... + +# See also +​ +* [Exceptions](/docs/documentation/Guides/xtd.core/Exceptions/overview) +* [Guides](/docs/documentation/Guides) +* [Documentation](/docs/documentation) + +© 2024 Gammasoft. + +[//]: # (https://learn.microsoft.com/en-us/dotnet/standard/exceptions/how-to-create-localized-exception-messages) diff --git a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/exceptions_try_catch.md b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/exceptions_try_catch.md index e43882776c66..4734d25e2c7d 100644 --- a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/exceptions_try_catch.md +++ b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/exceptions_try_catch.md @@ -1,9 +1,41 @@ # How to use the try/catch block to catch exceptions (xtd.core) -Coming soon... +Place any code statements that might raise or throw an exception in a `try` block, and place statements used to handle the exception or exceptions in one or more `catch` blocks below the `try` block. +Each `catch` block includes the exception type and can contain additional statements needed to handle that exception type. + +In the following example, a [stream_reader](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1io_1_1stream__reader.html) opens a file called *data.txt* and retrieves a line from the file. +Since the code might throw any of three exceptions, it's placed in a `try` block. +Three `catch` blocks catch the exceptions and handle them by displaying the results to the console. + +```cpp +#include + +using namespace xtd; +using namespace xtd::io; + +class process_file { +public: + static void main() { + try { + block_scope_ (auto sr = stream_reader {"data.txt"}) { + console::write_line("The first line of this file is {}", sr.read_line()); + } + } catch (const file_not_found_exception& e) { + console::write_line("The file was not found: '{}'", e); + } catch (const directory_not_found_exception& e) { + console::write_line("The directory was not found: '{}'", e); + } catch (const io_exception& e) { + console::write_line("The file could not be opened: '{}'", e); + } + } +}; + +startup_(process_file::main); +``` # See also ​ +* [Exceptions](/docs/documentation/Guides/xtd.core/Exceptions/overview) * [Guides](/docs/documentation/Guides) * [Documentation](/docs/documentation) diff --git a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/exceptions_use_specific_exceptions.md b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/exceptions_use_specific_exceptions.md index 2fc6426def00..971466801473 100644 --- a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/exceptions_use_specific_exceptions.md +++ b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/exceptions_use_specific_exceptions.md @@ -4,6 +4,7 @@ Coming soon... # See also ​ +* [Exceptions](/docs/documentation/Guides/xtd.core/Exceptions/overview) * [Guides](/docs/documentation/Guides) * [Documentation](/docs/documentation) diff --git a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/explicitly_throw_exception.md b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/explicitly_throw_exception.md index c117c4041787..572b80a7b9a4 100644 --- a/docs/documentation/Guides/xtd.core/Exceptions/How-tos/explicitly_throw_exception.md +++ b/docs/documentation/Guides/xtd.core/Exceptions/How-tos/explicitly_throw_exception.md @@ -4,6 +4,7 @@ Coming soon... # See also ​ +* [Exceptions](/docs/documentation/Guides/xtd.core/Exceptions/overview) * [Guides](/docs/documentation/Guides) * [Documentation](/docs/documentation)