commit 75601d987e84e686d433b5f96f838e42165ea97c
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Tue May 7 22:33:01 2019 +0100
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.
@@ -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.
*/
@@ -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
@@ -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;
@@ -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" }
@@ -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" }