Improve API docs for <chrono> and <ratio>

* doc/doxygen/doxygroups.cc (std::literals): Add documentation for
	inline namespace.
	* include/std/chrono: Improve docs.
	* include/std/ratio: Do not document implementation details.
	* testsuite/20_util/ratio/cons/cons_overflow_neg.cc: Adjust dg-error
	line numbers.
	* testsuite/20_util/ratio/operations/ops_overflow_neg.cc: Likewise.

From-SVN: r270988
This commit is contained in:
Jonathan Wakely 2019-05-07 23:46:53 +01:00 committed by Jonathan Wakely
parent f61a12b395
commit c34d3fd306
6 changed files with 139 additions and 10 deletions

View File

@ -1,5 +1,13 @@
2019-05-07 Jonathan Wakely <jwakely@redhat.com>
* doc/doxygen/doxygroups.cc (std::literals): Add documentation for
inline namespace.
* include/std/chrono: Improve docs.
* include/std/ratio: Do not document implementation details.
* testsuite/20_util/ratio/cons/cons_overflow_neg.cc: Adjust dg-error
line numbers.
* testsuite/20_util/ratio/operations/ops_overflow_neg.cc: Likewise.
PR libstdc++/89102
* doc/xml/manual/intro.xml: Document DR 2408 and 2465 changes.
* include/std/chrono (__duration_common_type_wrapper): Replace with ...

View File

@ -19,6 +19,9 @@
/** @namespace std
* @brief ISO C++ entities toplevel namespace is std.
*/
/** @namespace std
* @brief ISO C++ inline namespace for literal suffixes.
*/
/** @namespace std::__detail
* @brief Implementation details not part of the namespace std interface.
*/

View File

@ -24,6 +24,7 @@
/** @file include/chrono
* This is a Standard C++ Library header.
* @ingroup chrono
*/
#ifndef _GLIBCXX_CHRONO
@ -67,6 +68,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.11.4.3 specialization of common_type (for duration, sfinae-friendly)
/// @cond undocumented
template<typename _CT, typename _Period1, typename _Period2, typename = void>
struct __duration_common_type
{ };
@ -90,6 +93,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
struct __duration_common_type<__failure_type, _Period1, _Period2>
{ typedef __failure_type type; };
/// @endcond
/// Specialization of common_type for chrono::duration types.
/// @relates duration
template<typename _Rep1, typename _Period1, typename _Rep2, typename _Period2>
struct common_type<chrono::duration<_Rep1, _Period1>,
chrono::duration<_Rep2, _Period2>>
@ -98,6 +105,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// 20.11.4.3 specialization of common_type (for time_point, sfinae-friendly)
/// @cond undocumented
template<typename _CT, typename _Clock, typename = void>
struct __timepoint_common_type
{ };
@ -108,14 +117,25 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
using type = chrono::time_point<_Clock, typename _CT::type>;
};
/// @endcond
/// Specialization of common_type for chrono::time_point types.
/// @relates time_point
template<typename _Clock, typename _Duration1, typename _Duration2>
struct common_type<chrono::time_point<_Clock, _Duration1>,
chrono::time_point<_Clock, _Duration2>>
: __timepoint_common_type<common_type<_Duration1, _Duration2>, _Clock>
{ };
// @} group chrono
namespace chrono
{
/// @addtogroup chrono
/// @{
/// @cond undocumented
// Primary template for duration_cast impl.
template<typename _ToDur, typename _CF, typename _CR,
bool _NumIsOne = false, bool _DenIsOne = false>
@ -188,6 +208,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
using __disable_if_is_duration
= typename enable_if<!__is_duration<_Tp>::value, _Tp>::type;
/// @endcond
/// duration_cast
template<typename _ToDur, typename _Rep, typename _Period>
constexpr __enable_if_is_duration<_ToDur>
@ -288,6 +310,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return numeric_limits<_Rep>::lowest(); }
};
/// @cond undocumented
template<typename _Tp>
struct __is_ratio
: std::false_type
@ -298,6 +322,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
: std::true_type
{ };
/// @endcond
/// duration
template<typename _Rep, typename _Period>
struct duration
@ -446,6 +472,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
rep __r;
};
/// @relates duration @{
/// The sum of two durations.
template<typename _Rep1, typename _Period1,
typename _Rep2, typename _Period2>
constexpr typename common_type<duration<_Rep1, _Period1>,
@ -459,6 +488,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __cd(__cd(__lhs).count() + __cd(__rhs).count());
}
/// The difference between two durations.
template<typename _Rep1, typename _Period1,
typename _Rep2, typename _Period2>
constexpr typename common_type<duration<_Rep1, _Period1>,
@ -472,6 +502,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __cd(__cd(__lhs).count() - __cd(__rhs).count());
}
/// @}
/// @cond undocumented
// SFINAE helper to obtain common_type<_Rep1, _Rep2> only if _Rep2
// is implicitly convertible to it.
// _GLIBCXX_RESOLVE_LIB_DEFECTS
@ -481,6 +515,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
using __common_rep_t = typename
enable_if<is_convertible<const _Rep2&, _CRep>::value, _CRep>::type;
/// @endcond
/// @relates duration @{
/// Multiply a duration by a scalar value.
template<typename _Rep1, typename _Period, typename _Rep2>
constexpr duration<__common_rep_t<_Rep1, _Rep2>, _Period>
operator*(const duration<_Rep1, _Period>& __d, const _Rep2& __s)
@ -490,6 +529,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __cd(__cd(__d).count() * __s);
}
/// Multiply a duration by a scalar value.
template<typename _Rep1, typename _Rep2, typename _Period>
constexpr duration<__common_rep_t<_Rep2, _Rep1>, _Period>
operator*(const _Rep1& __s, const duration<_Rep2, _Period>& __d)
@ -542,6 +582,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
// comparisons
template<typename _Rep1, typename _Period1,
typename _Rep2, typename _Period2>
constexpr bool
@ -594,6 +635,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
const duration<_Rep2, _Period2>& __rhs)
{ return !(__lhs < __rhs); }
/// @}
#ifdef _GLIBCXX_USE_C99_STDINT_TR1
# define _GLIBCXX_CHRONO_INT64_T int64_t
#elif defined __INT64_TYPE__
@ -721,6 +764,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
#endif // C++17
/// @relates time_point @{
/// Adjust a time point forwards by the given duration.
template<typename _Clock, typename _Dur1,
typename _Rep2, typename _Period2>
constexpr time_point<_Clock,
@ -734,6 +780,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __time_point(__lhs.time_since_epoch() + __rhs);
}
/// Adjust a time point forwards by the given duration.
template<typename _Rep1, typename _Period1,
typename _Clock, typename _Dur2>
constexpr time_point<_Clock,
@ -747,6 +794,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __time_point(__rhs.time_since_epoch() + __lhs);
}
/// Adjust a time point backwards by the given duration.
template<typename _Clock, typename _Dur1,
typename _Rep2, typename _Period2>
constexpr time_point<_Clock,
@ -760,6 +808,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __time_point(__lhs.time_since_epoch() -__rhs);
}
/// @}
/// @relates time_point @{
/// The difference between two time points (as a duration)
template<typename _Clock, typename _Dur1, typename _Dur2>
constexpr typename common_type<_Dur1, _Dur2>::type
operator-(const time_point<_Clock, _Dur1>& __lhs,
@ -802,6 +855,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
const time_point<_Clock, _Dur2>& __rhs)
{ return !(__lhs < __rhs); }
// @}
// Clocks.
@ -827,6 +881,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @brief System clock.
*
* Time returned represents wall time from the system-wide clock.
* @ingroup chrono
*/
struct system_clock
{
@ -866,6 +921,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @brief Monotonic clock
*
* Time returned has the property of only increasing at a uniform rate.
* @ingroup chrono
*/
struct steady_clock
{
@ -887,10 +943,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* This is the clock "with the shortest tick period." Alias to
* std::system_clock until higher-than-nanosecond definitions
* become feasible.
* @ingroup chrono
*/
using high_resolution_clock = system_clock;
} // end inline namespace _V2
// @}
} // namespace chrono
#if __cplusplus > 201103L
@ -899,10 +957,34 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
inline namespace literals
{
/** ISO C++ 2014 namespace for suffixes for duration literals.
*
* These suffixes can be used to create `chrono::duration` values with
* tick periods of hours, minutes, seconds, milliseconds, microseconds
* or nanoseconds. For example, `std::chrono::seconds(5)` can be written
* as `5s` after making the suffix visible in the current scope.
* The suffixes can be made visible by a using-directive or
* using-declaration such as:
* - `using namespace std::chrono_literals;`
* - `using namespace std::literals;`
* - `using namespace std::chrono;`
* - `using namespace std;`
* - `using std::chrono_literals::operator""s;`
*
* The result of these suffixes on an integer literal is one of the
* standard typedefs such as `std::chrono::hours`.
* The result on a floating-point literal is a duration type with the
* specified tick period and an unspecified floating-point representation,
* for example `1.5e2ms` might be equivalent to
* `chrono::duration<long double, chrono::milli>(1.5e2)`.
*
* @ingroup chrono
*/
inline namespace chrono_literals
{
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wliteral-suffix"
/// @cond undocumented
template<typename _Dur, char... _Digits>
constexpr _Dur __check_overflow()
{
@ -912,56 +994,69 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
"literal value cannot be represented by duration type");
return _Dur(__repval);
}
/// @endcond
/// Literal suffix for durations representing non-integer hours
constexpr chrono::duration<long double, ratio<3600,1>>
operator""h(long double __hours)
{ return chrono::duration<long double, ratio<3600,1>>{__hours}; }
/// Literal suffix for durations of type `std::chrono::hours`
template <char... _Digits>
constexpr chrono::hours
operator""h()
{ return __check_overflow<chrono::hours, _Digits...>(); }
/// Literal suffix for durations representing non-integer minutes
constexpr chrono::duration<long double, ratio<60,1>>
operator""min(long double __mins)
{ return chrono::duration<long double, ratio<60,1>>{__mins}; }
/// Literal suffix for durations of type `std::chrono::minutes`
template <char... _Digits>
constexpr chrono::minutes
operator""min()
{ return __check_overflow<chrono::minutes, _Digits...>(); }
/// Literal suffix for durations representing non-integer seconds
constexpr chrono::duration<long double>
operator""s(long double __secs)
{ return chrono::duration<long double>{__secs}; }
/// Literal suffix for durations of type `std::chrono::seconds`
template <char... _Digits>
constexpr chrono::seconds
operator""s()
{ return __check_overflow<chrono::seconds, _Digits...>(); }
/// Literal suffix for durations representing non-integer milliseconds
constexpr chrono::duration<long double, milli>
operator""ms(long double __msecs)
{ return chrono::duration<long double, milli>{__msecs}; }
/// Literal suffix for durations of type `std::chrono::milliseconds`
template <char... _Digits>
constexpr chrono::milliseconds
operator""ms()
{ return __check_overflow<chrono::milliseconds, _Digits...>(); }
/// Literal suffix for durations representing non-integer microseconds
constexpr chrono::duration<long double, micro>
operator""us(long double __usecs)
{ return chrono::duration<long double, micro>{__usecs}; }
/// Literal suffix for durations of type `std::chrono::microseconds`
template <char... _Digits>
constexpr chrono::microseconds
operator""us()
{ return __check_overflow<chrono::microseconds, _Digits...>(); }
/// Literal suffix for durations representing non-integer nanoseconds
constexpr chrono::duration<long double, nano>
operator""ns(long double __nsecs)
{ return chrono::duration<long double, nano>{__nsecs}; }
/// Literal suffix for durations of type `std::chrono::nanoseconds`
template <char... _Digits>
constexpr chrono::nanoseconds
operator""ns()
@ -978,8 +1073,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif // C++14
// @} group chrono
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace std

View File

@ -24,6 +24,7 @@
/** @file include/ratio
* This is a Standard C++ Library header.
* @ingroup ratio
*/
#ifndef _GLIBCXX_RATIO
@ -50,6 +51,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @{
*/
/// @cond undocumented
template<intmax_t _Pn>
struct __static_sign
: integral_constant<intmax_t, (_Pn < 0) ? -1 : 1>
@ -243,6 +246,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
static_assert(__rem < __d, "Internal library error");
};
/// @endcond
/**
* @brief Provides compile-time rational arithmetic.
*
@ -280,6 +285,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
template<intmax_t _Num, intmax_t _Den>
constexpr intmax_t ratio<_Num, _Den>::den;
/// @cond undocumented
template<typename _R1, typename _R2>
struct __ratio_multiply
{
@ -306,10 +313,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _R1, typename _R2>
constexpr intmax_t __ratio_multiply<_R1, _R2>::den;
/// @endcond
/// ratio_multiply
template<typename _R1, typename _R2>
using ratio_multiply = typename __ratio_multiply<_R1, _R2>::type;
/// @cond undocumented
template<typename _R1, typename _R2>
struct __ratio_divide
{
@ -329,6 +340,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _R1, typename _R2>
constexpr intmax_t __ratio_divide<_R1, _R2>::den;
/// @endcond
/// ratio_divide
template<typename _R1, typename _R2>
using ratio_divide = typename __ratio_divide<_R1, _R2>::type;
@ -345,6 +358,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
: integral_constant<bool, !ratio_equal<_R1, _R2>::value>
{ };
/// @cond undocumented
// Both numbers are positive.
template<typename _R1, typename _R2,
typename _Left = __big_mul<_R1::num,_R2::den>,
@ -375,6 +390,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
ratio<-_R1::num, _R1::den> >::type
{ };
/// @endcond
/// ratio_less
template<typename _R1, typename _R2>
struct ratio_less
@ -416,6 +433,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
= ratio_greater_equal<_R1, _R2>::value;
#endif // C++17
/// @cond undocumented
template<typename _R1, typename _R2,
bool = (_R1::num >= 0),
bool = (_R2::num >= 0),
@ -499,10 +518,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _R1, typename _R2>
constexpr intmax_t __ratio_add<_R1, _R2>::den;
/// @endcond
/// ratio_add
template<typename _R1, typename _R2>
using ratio_add = typename __ratio_add<_R1, _R2>::type;
/// @cond undocumented
template<typename _R1, typename _R2>
struct __ratio_subtract
{
@ -520,6 +543,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _R1, typename _R2>
constexpr intmax_t __ratio_subtract<_R1, _R2>::den;
/// @endcond
/// ratio_subtract
template<typename _R1, typename _R2>
using ratio_subtract = typename __ratio_subtract<_R1, _R2>::type;

View File

@ -45,7 +45,7 @@ test04()
std::ratio<1,0> r1 __attribute__((unused)); // { dg-error "required from here" }
}
// { dg-error "denominator cannot be zero" "" { target *-*-* } 263 }
// { dg-error "out of range" "" { target *-*-* } 264 }
// { dg-error "overflow in constant expression" "" { target *-*-* } 59 }
// { dg-error "denominator cannot be zero" "" { target *-*-* } 0 }
// { dg-error "out of range" "" { target *-*-* } 0 }
// { dg-error "overflow in constant expression" "" { target *-*-* } 0 }
// { dg-prune-output "not a member" }

View File

@ -41,10 +41,10 @@ test02()
// { dg-error "required from here" "" { target *-*-* } 28 }
// { dg-error "expected initializer" "" { target *-*-* } 35 }
// { dg-error "expected initializer" "" { target *-*-* } 37 }
// { dg-error "overflow in addition" "" { target *-*-* } 450 }
// { dg-error "overflow in multiplication" "" { target *-*-* } 95 }
// { dg-error "overflow in multiplication" "" { target *-*-* } 97 }
// { dg-error "overflow in multiplication" "" { target *-*-* } 99 }
// { dg-error "overflow in constant expression" "" { target *-*-* } 106 }
// { dg-error "overflow in addition" "" { target *-*-* } 0 }
// { dg-error "overflow in multiplication" "" { target *-*-* } 98 }
// { dg-error "overflow in multiplication" "" { target *-*-* } 100 }
// { dg-error "overflow in multiplication" "" { target *-*-* } 102 }
// { dg-error "overflow in constant expression" "" { target *-*-* } 0 }
// { dg-prune-output "out of range" }
// { dg-prune-output "not usable in a constant expression" }