boost/url/error_types.hpp

0001 //
0002 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007 // Official repository: https://github.com/boostorg/url
0008 //
0009
0010 #ifndef BOOST_URL_ERROR_TYPES_HPP
0011 #define BOOST_URL_ERROR_TYPES_HPP
0012
0013 #include <boost/url/detail/config.hpp>
0014 #include <boost/system/error_code.hpp>
0015 #include <boost/system/system_error.hpp>
0016 #include <boost/system/result.hpp>
0017
0018 namespace boost {
0019 namespace urls {
0020
0021 #ifndef BOOST_URL_DOCS
0022 namespace error_types {
0023 #endif
0024
0025 /** The type of error category used by the library
0026
0027     @warning This alias is no longer supported and
0028     should not be used in new code. Please use
0029     `system::error_category` instead.
0030
0031     This alias is included for backwards
0032     compatibility with earlier versions of the
0033     library.
0034
0035     However, it will be removed in future releases,
0036     and using it in new code is not recommended.
0037
0038     Please use the updated version instead to
0039     ensure compatibility with future versions of
0040     the library.
0041
0042  */
0043 using error_category
0044     BOOST_URL_DEPRECATED("Use system::error_category instead") =
0045     boost::system::error_category;
0046
0047 /** The type of error code used by the library
0048
0049     @warning This alias is no longer supported and
0050     should not be used in new code. Please use
0051     `system::error_code` instead.
0052
0053     This alias is included for backwards
0054     compatibility with earlier versions of the
0055     library.
0056
0057     However, it will be removed in future releases,
0058     and using it in new code is not recommended.
0059
0060     Please use the updated version instead to
0061     ensure compatibility with future versions of
0062     the library.
0063
0064  */
0065 using error_code
0066     BOOST_URL_DEPRECATED("Use system::error_code instead") =
0067     boost::system::error_code;
0068
0069 /** The type of error condition used by the library
0070
0071     @warning This alias is no longer supported and
0072     should not be used in new code. Please use
0073     `system::error_condition` instead.
0074
0075     This alias is included for backwards
0076     compatibility with earlier versions of the
0077     library.
0078
0079     However, it will be removed in future releases,
0080     and using it in new code is not recommended.
0081
0082     Please use the updated version instead to
0083     ensure compatibility with future versions of
0084     the library.
0085
0086  */
0087 using error_condition
0088     BOOST_URL_DEPRECATED("Use system::error_condition instead") =
0089     boost::system::error_condition;
0090
0091 /** The type of system error thrown by the library
0092
0093     @warning This alias is no longer supported and
0094     should not be used in new code. Please use
0095     `system::system_error` instead.
0096
0097     This alias is included for backwards
0098     compatibility with earlier versions of the
0099     library.
0100
0101     However, it will be removed in future releases,
0102     and using it in new code is not recommended.
0103
0104     Please use the updated version instead to
0105     ensure compatibility with future versions of
0106     the library.
0107
0108  */
0109 using system_error
0110     BOOST_URL_DEPRECATED("Use system::system_error instead") =
0111     boost::system::system_error;
0112
0113 /** A function to return the generic error category used by the library
0114
0115     @warning This alias is no longer supported and
0116     should not be used in new code. Please use
0117     `core::string_view` instead.
0118
0119     This alias is included for backwards
0120     compatibility with earlier versions of the
0121     library.
0122
0123     However, it will be removed in future releases,
0124     and using it in new code is not recommended.
0125
0126     Please use the updated version instead to
0127     ensure compatibility with future versions of
0128     the library.
0129
0130  */
0131 #ifdef BOOST_URL_DOCS
0132 error_category const& generic_category();
0133 #else
0134
0135 /** A function to return the generic error category used by the library
0136
0137     @warning This alias is no longer supported and
0138     should not be used in new code. Please use
0139     `core::string_view` instead.
0140
0141     This alias is included for backwards
0142     compatibility with earlier versions of the
0143     library.
0144
0145     However, it will be removed in future releases,
0146     and using it in new code is not recommended.
0147
0148     Please use the updated version instead to
0149     ensure compatibility with future versions of
0150     the library.
0151
0152  */
0153 using boost::system::generic_category;
0154 #endif
0155
0156 /** A function to return the system error category used by the library
0157
0158     @warning This alias is no longer supported and
0159     should not be used in new code. Please use
0160     `core::string_view` instead.
0161
0162     This alias is included for backwards
0163     compatibility with earlier versions of the
0164     library.
0165
0166     However, it will be removed in future releases,
0167     and using it in new code is not recommended.
0168
0169     Please use the updated version instead to
0170     ensure compatibility with future versions of
0171     the library.
0172
0173  */
0174 #ifdef BOOST_URL_DOCS
0175 error_category const& system_category();
0176 #else
0177
0178 /** A function to return the system error category used by the library
0179
0180     @warning This alias is no longer supported and
0181     should not be used in new code. Please use
0182     `core::string_view` instead.
0183
0184     This alias is included for backwards
0185     compatibility with earlier versions of the
0186     library.
0187
0188     However, it will be removed in future releases,
0189     and using it in new code is not recommended.
0190
0191     Please use the updated version instead to
0192     ensure compatibility with future versions of
0193     the library.
0194
0195  */
0196 using boost::system::system_category;
0197 #endif
0198
0199 /** The set of constants used for cross-platform error codes
0200
0201     @warning This alias is no longer supported and
0202     should not be used in new code. Please use
0203     `core::string_view` instead.
0204
0205     This alias is included for backwards
0206     compatibility with earlier versions of the
0207     library.
0208
0209     However, it will be removed in future releases,
0210     and using it in new code is not recommended.
0211
0212     Please use the updated version instead to
0213     ensure compatibility with future versions of
0214     the library.
0215
0216  */
0217 namespace errc = boost::system::errc;
0218
0219 /** The type of result returned by library functions
0220
0221     @warning This alias is no longer supported and
0222     should not be used in new code. Please use
0223     `system::result` instead.
0224
0225     This alias is included for backwards
0226     compatibility with earlier versions of the
0227     library.
0228
0229     However, it will be removed in future releases,
0230     and using it in new code is not recommended.
0231
0232     Please use the updated version instead to
0233     ensure compatibility with future versions of
0234     the library.
0235
0236     @details This is an alias template used as the return type
0237     for functions that can either return a container,
0238     or fail with an error code. This is a brief
0239     synopsis of the type:
0240
0241     @par Declaration
0242     @code
0243     template< class T >
0244     class result
0245     {
0246     public:
0247         //
0248         // Return true if the result contains an error
0249         //
0250         constexpr bool has_error() const noexcept;
0251
0252         //
0253         // Return the error
0254         //
0255         constexpr system::error_code error() const noexcept;
0256
0257         //
0258         // Return true if the result contains a value
0259         //
0260         constexpr bool has_value() const noexcept;
0261         constexpr explicit operator bool() const noexcept;
0262
0263         //
0264         // Return the value, or throw an exception
0265         //
0266         constexpr T& value();
0267         constexpr T const& value() const;
0268
0269         // Return the value.
0270         // Precondition: has_value()==true
0271         //
0272         constexpr T& operator*() noexcept;
0273         constexpr T* operator->() noexcept;
0274         constexpr T const& operator*() const noexcept;
0275         constexpr T const* operator->() const noexcept;
0276
0277         ...more
0278     @endcode
0279
0280     @par Usage
0281     Given the function @ref parse_uri with this signature:
0282     @code
0283     system::result< url_view > parse_uri( core::string_view s ) noexcept;
0284     @endcode
0285
0286     The following statement captures the value in a
0287     variable upon success, otherwise throws:
0288     @code
0289     url_view u = parse_uri( "http://example.com/path/to/file.txt" ).value();
0290     @endcode
0291
0292     This statement captures the result in a local
0293     variable and inspects the error condition:
0294     @code
0295     system::result< url_view > rv = parse_uri( "http://example.com/path/to/file.txt" );
0296
0297     if(! rv )
0298         std::cout << rv.error();
0299     else
0300         std::cout << *rv;
0301     @endcode
0302
0303     @tparam T The type of value held by the result.
0304
0305     @see
0306         @li <a href="https://boost.org/libs/system/doc/html/system.html#ref_resultt_e"
0307             >`boost::system::result`</a>
0308
0309 */
0310 template<class T>
0311 using result
0312     BOOST_URL_DEPRECATED("Use system::result<T> instead") =
0313     boost::system::result<T, system::error_code>;
0314
0315 #ifndef BOOST_URL_DOCS
0316 } // error_types
0317
0318 using namespace error_types;
0319 #endif
0320
0321 } // urls
0322 } // boost
0323
0324 #endif