From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id A255438AABBE for ; Fri, 9 Dec 2022 00:36:07 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org A255438AABBE Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1670546167; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Bdp65PZr487Q+jSItWNGAul3VW19FhSYBGZZlUmlxPA=; b=K+/RJnRkzFAcDX+MntLdIbx/6jVfg8j3PV3p0n1FSfiynl/Jgdl3gg+zwOpHsN5E4jE1PA /i3su8hnrqcPoSuKoAn6kgZuGGsCY475rJb0gnj59R+GffcXJGko9G60ANhyHSVtwMDJc2 CPB6qnpuPQ1OSII+rI5BW+gaR//cuAE= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-558-2tTurioHMXW5G94AiwseyQ-1; Thu, 08 Dec 2022 19:36:06 -0500 X-MC-Unique: 2tTurioHMXW5G94AiwseyQ-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id ED9118582B9; Fri, 9 Dec 2022 00:36:05 +0000 (UTC) Received: from localhost (unknown [10.33.36.3]) by smtp.corp.redhat.com (Postfix) with ESMTP id B494A2024CC0; Fri, 9 Dec 2022 00:36:05 +0000 (UTC) From: Jonathan Wakely To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed] libstdc++: Add [[nodiscard]] to chrono conversion functions Date: Fri, 9 Dec 2022 00:36:02 +0000 Message-Id: <20221209003602.443084-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.4 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-11.8 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_NONE,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: Tested x86_64-linux. Pushed to trunk. -- >8 -- Also add doxygen comments. libstdc++-v3/ChangeLog: * include/bits/chrono.h (duration_cast, floor, round, abs, ceil) (time_point_cast): Add [[nodiscard]] attribute and doxygen comments. (treat_as_floating_point): Add doxygen commen. --- libstdc++-v3/include/bits/chrono.h | 139 +++++++++++++++++++++++++---- 1 file changed, 123 insertions(+), 16 deletions(-) diff --git a/libstdc++-v3/include/bits/chrono.h b/libstdc++-v3/include/bits/chrono.h index 496e9485a73..22c0be3fbe6 100644 --- a/libstdc++-v3/include/bits/chrono.h +++ b/libstdc++-v3/include/bits/chrono.h @@ -246,8 +246,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /// @endcond - /// duration_cast + /** Convert a `duration` to type `ToDur`. + * + * If the duration cannot be represented accurately in the result type, + * returns the result of integer truncation (i.e., rounded towards zero). + * + * @tparam _ToDur The result type must be a `duration`. + * @param __d A duration. + * @return The value of `__d` converted to type `_ToDur`. + * @since C++11 + */ template + _GLIBCXX_NODISCARD constexpr __enable_if_is_duration<_ToDur> duration_cast(const duration<_Rep, _Period>& __d) { @@ -260,7 +270,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return __dc::__cast(__d); } - /// treat_as_floating_point + /** Trait indicating whether to treat a type as a floating-point type. + * + * The chrono library uses this trait to tell whether a `duration` can + * represent fractional values of the given precision, or only integral + * values. + * + * You should specialize this trait for your own numeric types that are + * used with `duration` and can represent non-integral values. + * + * @since C++11 + */ template struct treat_as_floating_point : is_floating_point<_Rep> @@ -320,8 +340,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #if __cplusplus >= 201703L # define __cpp_lib_chrono 201611L + /** Convert a `duration` to type `ToDur` and round down. + * + * If the duration cannot be represented exactly in the result type, + * returns the closest value that is less than the argument. + * + * @tparam _ToDur The result type must be a `duration`. + * @param __d A duration. + * @return The value of `__d` converted to type `_ToDur`. + * @since C++17 + */ template - constexpr __enable_if_is_duration<_ToDur> + [[nodiscard]] constexpr __enable_if_is_duration<_ToDur> floor(const duration<_Rep, _Period>& __d) { auto __to = chrono::duration_cast<_ToDur>(__d); @@ -330,8 +360,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return __to; } + /** Convert a `duration` to type `ToDur` and round up. + * + * If the duration cannot be represented exactly in the result type, + * returns the closest value that is greater than the argument. + * + * @tparam _ToDur The result type must be a `duration`. + * @param __d A duration. + * @return The value of `__d` converted to type `_ToDur`. + * @since C++17 + */ template - constexpr __enable_if_is_duration<_ToDur> + [[nodiscard]] constexpr __enable_if_is_duration<_ToDur> ceil(const duration<_Rep, _Period>& __d) { auto __to = chrono::duration_cast<_ToDur>(__d); @@ -340,8 +380,20 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return __to; } + /** Convert a `duration` to type `ToDur` and round to the closest value. + * + * If the duration cannot be represented exactly in the result type, + * returns the closest value, rounding ties to even. + * + * @tparam _ToDur The result type must be a `duration` with a + * non-floating-point `rep` type. + * @param __d A duration. + * @return The value of `__d` converted to type `_ToDur`. + * @since C++17 + */ template - constexpr enable_if_t< + [[nodiscard]] constexpr + enable_if_t< __and_<__is_duration<_ToDur>, __not_>>::value, _ToDur> @@ -352,18 +404,24 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION auto __diff0 = __d - __t0; auto __diff1 = __t1 - __d; if (__diff0 == __diff1) - { + { if (__t0.count() & 1) - return __t1; + return __t1; return __t0; - } + } else if (__diff0 < __diff1) - return __t0; + return __t0; return __t1; } + /** The absolute (non-negative) value of a duration. + * + * @param __d A duration with a signed `rep` type. + * @return A duration of the same type as the argument, with value |d|. + * @since C++17 + */ template - constexpr + [[nodiscard]] constexpr enable_if_t::is_signed, duration<_Rep, _Period>> abs(duration<_Rep, _Period> __d) { @@ -925,10 +983,21 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION duration __d; }; - /// time_point_cast + /** Convert a `time_point` to use `duration` type `ToDur`. + * + * The result is the same time point as measured by the same clock, but + * using the specified `duration` to represent the time. + * If the time point cannot be represented accurately in the result type, + * returns the result of integer truncation (i.e., rounded towards zero). + * + * @tparam _ToDur The `duration` type to use for the result. + * @param __t A time point. + * @return The value of `__t` converted to use type `_ToDur`. + * @since C++11 + */ template - constexpr typename enable_if<__is_duration<_ToDur>::value, - time_point<_Clock, _ToDur>>::type + _GLIBCXX_NODISCARD constexpr + __enable_if_t<__is_duration<_ToDur>::value, time_point<_Clock, _ToDur>> time_point_cast(const time_point<_Clock, _Dur>& __t) { typedef time_point<_Clock, _ToDur> __time_point; @@ -936,8 +1005,20 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } #if __cplusplus > 201402L + /** Convert a `time_point` to type `ToDur` and round down. + * + * The result is the same time point as measured by the same clock, but + * using the specified `duration` to represent the time. + * If the time point cannot be represented exactly in the result type, + * returns the closest value that is less than the argument. + * + * @tparam _ToDur The `duration` type to use for the result. + * @param __t A time point. + * @return The value of `__d` converted to type `_ToDur`. + * @since C++17 + */ template - constexpr + [[nodiscard]] constexpr enable_if_t<__is_duration<_ToDur>::value, time_point<_Clock, _ToDur>> floor(const time_point<_Clock, _Dur>& __tp) { @@ -945,8 +1026,20 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION chrono::floor<_ToDur>(__tp.time_since_epoch())}; } + /** Convert a `time_point` to type `ToDur` and round up. + * + * The result is the same time point as measured by the same clock, but + * using the specified `duration` to represent the time. + * If the time point cannot be represented exactly in the result type, + * returns the closest value that is greater than the argument. + * + * @tparam _ToDur The `duration` type to use for the result. + * @param __t A time point. + * @return The value of `__d` converted to type `_ToDur`. + * @since C++17 + */ template - constexpr + [[nodiscard]] constexpr enable_if_t<__is_duration<_ToDur>::value, time_point<_Clock, _ToDur>> ceil(const time_point<_Clock, _Dur>& __tp) { @@ -954,8 +1047,22 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION chrono::ceil<_ToDur>(__tp.time_since_epoch())}; } + /** Convert a `time_point` to type `ToDur` and round to the closest value. + * + * The result is the same time point as measured by the same clock, but + * using the specified `duration` to represent the time. + * If the time point cannot be represented exactly in the result type, + * returns the closest value, rounding ties to even. + * + * @tparam _ToDur The `duration` type to use for the result, + * which must have a non-floating-point `rep` type. + * @param __t A time point. + * @return The value of `__d` converted to type `_ToDur`. + * @since C++17 + */ template - constexpr enable_if_t< + [[nodiscard]] constexpr + enable_if_t< __and_<__is_duration<_ToDur>, __not_>>::value, time_point<_Clock, _ToDur>> -- 2.38.1