From patchwork Fri Dec 9 00:36:02 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 31561 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:adf:f944:0:0:0:0:0 with SMTP id q4csp501387wrr; Thu, 8 Dec 2022 16:38:01 -0800 (PST) X-Google-Smtp-Source: AA0mqf6su2whnhvHuRQynvdzDL+Sqzb+a/LUR5upwbdOHsgJTK5hqLEo8l5GGN5Tq34fcDf1WmIp X-Received: by 2002:a17:907:3ac2:b0:7c1:765:9cfc with SMTP id fi2-20020a1709073ac200b007c107659cfcmr2316872ejc.34.1670546281291; Thu, 08 Dec 2022 16:38:01 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1670546281; cv=none; d=google.com; s=arc-20160816; b=j77LtELZsmqcazuGG9ISlfGzq+tBwBNkt+KLAqlUI0kuH+IwO0J3ph1tKI6SZfSvgM NWzZSffRbww71OMoh4/aOgWAkaX8EoIyk6EUxZYyGKGH24O+nm10wxqecU4TrcZ9XI9R LUKyzk8TViz+xoVCN3OGBbXjPUTOkwj4E14u+yVTxuS34mdC+4adi/6CZY4lmfoByWLS tdoHz0FyWJW8pSYZ0ix4ir0A4dW+L34MenR0JTQOl7rWZ3J62gmvFprN1mtW++WbZA8P qUhPGxA6W1smHKLRvqjm1C/X62C3SLnPuRq2TX6kYAn6o9y7Kha3wtxTgP8F7bOfaW4i 0qhg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:reply-to:from:list-subscribe:list-help:list-post :list-archive:list-unsubscribe:list-id:precedence :content-transfer-encoding:mime-version:message-id:date:subject:to :dmarc-filter:delivered-to:dkim-signature:dkim-filter; bh=Bdp65PZr487Q+jSItWNGAul3VW19FhSYBGZZlUmlxPA=; b=Qw+rnY50gIz1F7CK2awX9GG4gzrBom5I6s6oKy9FZjzhS0TY5HRuVCPrEZLpJuM59H MTsaJ5Gi1k6aUp4fWulOKY2xfEBflw/Y2pkKKEWJ6DPHnA6uMEmANV4rYNwJ0i7dzwsi i3cwdzVtF1sxN7Vs4vSD/iCY4L440Lj1ytqJSR95KECAtaA+XNllAfY9lXBjGJNAS4zb nanNvEu+tCr+CxTeidnegp6KjQ1rE9HXDDxGbl/td0GvWL4SRA1jCcLYEX1447oGhwOf ZUzl1+uXaKJSVR83kj7w91dbWZfZB237/lK9NUE6USqTUj5tDLUKkf5oOGdzlt0fwo9P kk1w== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=SXdQJnjJ; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 8.43.85.97 as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from sourceware.org (server2.sourceware.org. [8.43.85.97]) by mx.google.com with ESMTPS id sb23-20020a1709076d9700b0073d8830e4c7si1253136ejc.954.2022.12.08.16.38.01 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 08 Dec 2022 16:38:01 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 8.43.85.97 as permitted sender) client-ip=8.43.85.97; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=SXdQJnjJ; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 8.43.85.97 as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 8251738B0BD5 for ; Fri, 9 Dec 2022 00:37:01 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 8251738B0BD5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1670546221; bh=Bdp65PZr487Q+jSItWNGAul3VW19FhSYBGZZlUmlxPA=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:From; b=SXdQJnjJCDxvP8pFkFVDrd+YqjhatG2GvfYm3deXlODCkAsIv8fx2aJQrCSAUo1ay n6OGWFvrcTzmHzhMiPYqyKsGa3EmhOwIZrQDEyb+YMsJjotjxBGIaYAGzF9yNbQ1mO n/uMEqt3wg5vOy+f1txn2+9j6c+Kkx2UhZdmtQ0Q= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org 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 8F8B138AEB64 for ; Fri, 9 Dec 2022 00:36:09 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 8F8B138AEB64 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) 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 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=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org Sender: "Gcc-patches" X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1751694737492370686?= X-GMAIL-MSGID: =?utf-8?q?1751694737492370686?= 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>>