[thirdparty/gcc.git] / libstdc++-v3 / include / debug / helper_functions.h

// Debugging support implementation -*- C++ -*-

// Copyright (C) 2003-2025 Free Software Foundation, Inc.
//
// This file is part of the GNU ISO C++ Library.  This library is free
// software; you can redistribute it and/or modify it under the
// terms of the GNU General Public License as published by the
// Free Software Foundation; either version 3, or (at your option)
// any later version.

// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.

// Under Section 7 of GPL version 3, you are granted additional
// permissions described in the GCC Runtime Library Exception, version
// 3.1, as published by the Free Software Foundation.

// You should have received a copy of the GNU General Public License and
// a copy of the GCC Runtime Library Exception along with this program;
// see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
// <http://www.gnu.org/licenses/>.

/** @file debug/helper_functions.h
 *  This file is a GNU debug extension to the Standard C++ Library.
 */

#ifndef _GLIBCXX_DEBUG_HELPER_FUNCTIONS_H
#define _GLIBCXX_DEBUG_HELPER_FUNCTIONS_H 1

#include <bits/move.h>				// for __addressof
#include <bits/stl_iterator_base_types.h>	// for iterator_traits,
						// categories and _Iter_base
#include <bits/cpp_type_traits.h>		// for __is_integer

#include <bits/stl_pair.h>			// for pair

namespace __gnu_debug
{
  template<typename _Iterator, typename _Sequence, typename _Category>
    class _Safe_iterator;

#if __cplusplus >= 201103L
  template<typename _Iterator, typename _Sequence>
    class _Safe_local_iterator;
#endif

  /** The precision to which we can calculate the distance between
   *  two iterators.
   */
  enum _Distance_precision
    {
      __dp_none,		// Not even an iterator type
      __dp_equality,		//< Can compare iterator equality, only
      __dp_sign,		//< Can determine equality and ordering
      __dp_sign_max_size,	//< __dp_sign and gives max range size
      __dp_exact		//< Can determine distance precisely
    };

  template<typename _Iterator,
	   typename = typename std::__is_integer<_Iterator>::__type>
    struct _Distance_traits
    {
    private:
      typedef
	typename std::iterator_traits<_Iterator>::difference_type _ItDiffType;

      template<typename _DiffType, typename = _DiffType> // PR c++/85282
	struct _DiffTraits
	{ typedef _DiffType __type; };

      template<typename _DiffType>
	struct _DiffTraits<_DiffType, void>
	{ typedef std::ptrdiff_t __type; };

      typedef typename _DiffTraits<_ItDiffType>::__type _DiffType;

    public:
      typedef std::pair<_DiffType, _Distance_precision> __type;
    };

  template<typename _Integral>
    struct _Distance_traits<_Integral, std::__true_type>
    { typedef std::pair<std::ptrdiff_t, _Distance_precision> __type; };

  /** Determine the distance between two iterators with some known
   *	precision.
  */
  template<typename _Iterator>
    _GLIBCXX_CONSTEXPR
    inline typename _Distance_traits<_Iterator>::__type
    __get_distance(_Iterator __lhs, _Iterator __rhs,
		   std::random_access_iterator_tag)
    { return std::make_pair(__rhs - __lhs, __dp_exact); }

  template<typename _Iterator>
    _GLIBCXX14_CONSTEXPR
    inline typename _Distance_traits<_Iterator>::__type
    __get_distance(_Iterator __lhs, _Iterator __rhs,
		   std::input_iterator_tag)
    {
      if (__lhs == __rhs)
	return std::make_pair(0, __dp_exact);

      return std::make_pair(1, __dp_equality);
    }

  template<typename _Iterator>
    _GLIBCXX_CONSTEXPR
    inline typename _Distance_traits<_Iterator>::__type
    __get_distance(_Iterator __lhs, _Iterator __rhs)
    {
      return __gnu_debug::__get_distance(__lhs, __rhs,
					 std::__iterator_category(__lhs));
    }

  // An arbitrary iterator pointer is not singular.
  inline bool
  __check_singular_aux(const void*) { return false; }

  // Defined in <debug/safe_base.h>
  bool
  __check_singular_aux(const class _Safe_iterator_base*);

  // We may have an iterator that derives from _Safe_iterator_base but isn't
  // a _Safe_iterator.
  template<typename _Iterator>
    _GLIBCXX_CONSTEXPR
    inline bool
    __check_singular(_Iterator const& __x)
    {
      return ! std::__is_constant_evaluated()
	       && __gnu_debug::__check_singular_aux(std::__addressof(__x));
    }

  /** Non-NULL pointers are nonsingular. */
  template<typename _Tp>
    _GLIBCXX_CONSTEXPR
    inline bool
    __check_singular(_Tp* const& __ptr)
    { return __ptr == 0; }

  /** We say that integral types for a valid range, and defer to other
   *  routines to realize what to do with integral types instead of
   *  iterators.
  */
  template<typename _Integral>
    _GLIBCXX_CONSTEXPR
    inline bool
    __valid_range_aux(_Integral, _Integral, std::__true_type)
    { return true; }

  template<typename _Integral>
    _GLIBCXX20_CONSTEXPR
    inline bool
    __valid_range_aux(_Integral, _Integral,
		      typename _Distance_traits<_Integral>::__type& __dist,
		      std::__true_type)
    {
      __dist = std::make_pair(0, __dp_none);
      return true;
    }

  template<typename _InputIterator>
    _GLIBCXX_CONSTEXPR
    inline bool
    __valid_range_aux(_InputIterator __first, _InputIterator __last,
		      std::input_iterator_tag)
    {
      // FIXME: The checks for singular iterators fail during constant eval
      // due to PR c++/85944. e.g. PR libstdc++/109517 and PR libstdc++/109976.
      if (std::__is_constant_evaluated())
	return true;

      return __first == __last
	|| (!__gnu_debug::__check_singular(__first)
	      && !__gnu_debug::__check_singular(__last));
    }

  template<typename _InputIterator>
    _GLIBCXX_CONSTEXPR
    inline bool
    __valid_range_aux(_InputIterator __first, _InputIterator __last,
		      std::random_access_iterator_tag)
    {
      return __gnu_debug::__valid_range_aux(__first, __last,
					    std::input_iterator_tag())
	&& __first <= __last;
    }

  /** We have iterators, so figure out what kind of iterators they are
   *  to see if we can check the range ahead of time.
  */
  template<typename _InputIterator>
    _GLIBCXX_CONSTEXPR
    inline bool
    __valid_range_aux(_InputIterator __first, _InputIterator __last,
		      std::__false_type)
    {
      return __gnu_debug::__valid_range_aux(__first, __last,
					    std::__iterator_category(__first));
    }

  template<typename _InputIterator>
    _GLIBCXX20_CONSTEXPR
    inline bool
    __valid_range_aux(_InputIterator __first, _InputIterator __last,
		      typename _Distance_traits<_InputIterator>::__type& __dist,
		      std::__false_type)
    {
      if (!__gnu_debug::__valid_range_aux(__first, __last,
					  std::input_iterator_tag()))
	return false;

      __dist = __gnu_debug::__get_distance(__first, __last);
      switch (__dist.second)
	{
	case __dp_none:
	  break;
	case __dp_equality:
	  if (__dist.first == 0)
	    return true;
	  break;
	case __dp_sign:
	case __dp_sign_max_size:
	case __dp_exact:
	  return __dist.first >= 0;
	}

      // Can't tell so assume it is fine.
      return true;
    }

  /** Don't know what these iterators are, or if they are even
   *  iterators (we may get an integral type for InputIterator), so
   *  see if they are integral and pass them on to the next phase
   *  otherwise.
  */
  template<typename _InputIterator>
    _GLIBCXX20_CONSTEXPR
    inline bool
    __valid_range(_InputIterator __first, _InputIterator __last,
		  typename _Distance_traits<_InputIterator>::__type& __dist)
    {
      typedef typename std::__is_integer<_InputIterator>::__type _Integral;
      return __gnu_debug::__valid_range_aux(__first, __last, __dist,
					    _Integral());
    }

  template<typename _Iterator, typename _Sequence, typename _Category>
    bool
    __valid_range(const _Safe_iterator<_Iterator, _Sequence, _Category>&,
		  const _Safe_iterator<_Iterator, _Sequence, _Category>&,
		  typename _Distance_traits<_Iterator>::__type&);

#if __cplusplus >= 201103L
  template<typename _Iterator,typename _Sequence>
    bool
    __valid_range(const _Safe_local_iterator<_Iterator, _Sequence>&,
		  const _Safe_local_iterator<_Iterator, _Sequence>&,
		  typename _Distance_traits<_Iterator>::__type&);
#endif

  template<typename _InputIterator>
    _GLIBCXX14_CONSTEXPR
    inline bool
    __valid_range(_InputIterator __first, _InputIterator __last)
    {
      typedef typename std::__is_integer<_InputIterator>::__type _Integral;
      return __gnu_debug::__valid_range_aux(__first, __last, _Integral());
    }

  template<typename _Iterator, typename _Sequence, typename _Category>
    bool
    __valid_range(const _Safe_iterator<_Iterator, _Sequence, _Category>&,
		  const _Safe_iterator<_Iterator, _Sequence, _Category>&);

#if __cplusplus >= 201103L
  template<typename _Iterator, typename _Sequence>
    bool
    __valid_range(const _Safe_local_iterator<_Iterator, _Sequence>&,
		  const _Safe_local_iterator<_Iterator, _Sequence>&);
#endif

  // Fallback method, always ok.
  template<typename _InputIterator, typename _Size>
    _GLIBCXX_CONSTEXPR
    inline bool
    __can_advance(_InputIterator, _Size)
    { return true; }

  template<typename _Iterator, typename _Sequence, typename _Category,
	   typename _Size>
    bool
    __can_advance(const _Safe_iterator<_Iterator, _Sequence, _Category>&,
		  _Size);

  template<typename _InputIterator, typename _Diff>
    _GLIBCXX_CONSTEXPR
    inline bool
    __can_advance(_InputIterator, const std::pair<_Diff, _Distance_precision>&, int)
    { return true; }

  template<typename _Iterator, typename _Sequence, typename _Category,
	   typename _Diff>
    bool
    __can_advance(const _Safe_iterator<_Iterator, _Sequence, _Category>&,
		  const std::pair<_Diff, _Distance_precision>&, int);

  /** Helper function to extract base iterator of random access safe iterator
   *  in order to reduce performance impact of debug mode.  Limited to random
   *  access iterator because it is the only category for which it is possible
   *  to check for correct iterators order in the __valid_range function
   *  thanks to the < operator.
   */
  template<typename _Iterator>
    _GLIBCXX_CONSTEXPR
    inline _Iterator
    __base(_Iterator __it)
    { return __it; }

#if __cplusplus < 201103L
  template<typename _Iterator>
    struct _Unsafe_type
    { typedef _Iterator _Type; };
#endif

  /* Remove debug mode safe iterator layer, if any. */
  template<typename _Iterator>
    _GLIBCXX_CONSTEXPR
    inline _Iterator
    __unsafe(_Iterator __it)
    { return __it; }
}

#endif
Commit	Line	Data
	1	// Debugging support implementation -- C++ --
	2
	3	// Copyright (C) 2003-2025 Free Software Foundation, Inc.
	4	//
	5	// This file is part of the GNU ISO C++ Library. This library is free
	6	// software; you can redistribute it and/or modify it under the
	7	// terms of the GNU General Public License as published by the
	8	// Free Software Foundation; either version 3, or (at your option)
	9	// any later version.
	10
	11	// This library is distributed in the hope that it will be useful,
	12	// but WITHOUT ANY WARRANTY; without even the implied warranty of
	13	// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	14	// GNU General Public License for more details.
	15
	16	// Under Section 7 of GPL version 3, you are granted additional
	17	// permissions described in the GCC Runtime Library Exception, version
	18	// 3.1, as published by the Free Software Foundation.
	19
	20	// You should have received a copy of the GNU General Public License and
	21	// a copy of the GCC Runtime Library Exception along with this program;
	22	// see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
	23	// <http://www.gnu.org/licenses/>.
	24
	25	/** @file debug/helper_functions.h
	26	* This file is a GNU debug extension to the Standard C++ Library.
	27	*/
	28
	29	#ifndef _GLIBCXX_DEBUG_HELPER_FUNCTIONS_H
	30	#define _GLIBCXX_DEBUG_HELPER_FUNCTIONS_H 1
	31
	32	#include <bits/move.h> // for __addressof
	33	#include <bits/stl_iterator_base_types.h> // for iterator_traits,
	34	// categories and _Iter_base
	35	#include <bits/cpp_type_traits.h> // for __is_integer
	36
	37	#include <bits/stl_pair.h> // for pair
	38
	39	namespace __gnu_debug
	40	{
	41	template<typename _Iterator, typename _Sequence, typename _Category>
	42	class _Safe_iterator;
	43
	44	#if __cplusplus >= 201103L
	45	template<typename _Iterator, typename _Sequence>
	46	class _Safe_local_iterator;
	47	#endif
	48
	49	/** The precision to which we can calculate the distance between
	50	* two iterators.
	51	*/
	52	enum _Distance_precision
	53	{
	54	__dp_none, // Not even an iterator type
	55	__dp_equality, //< Can compare iterator equality, only
	56	__dp_sign, //< Can determine equality and ordering
	57	__dp_sign_max_size, //< __dp_sign and gives max range size
	58	__dp_exact //< Can determine distance precisely
	59	};
	60
	61	template<typename _Iterator,
	62	typename = typename std::__is_integer<_Iterator>::__type>
	63	struct _Distance_traits
	64	{
	65	private:
	66	typedef
	67	typename std::iterator_traits<_Iterator>::difference_type _ItDiffType;
	68
	69	template<typename _DiffType, typename = _DiffType> // PR c++/85282
	70	struct _DiffTraits
	71	{ typedef _DiffType __type; };
	72
	73	template<typename _DiffType>
	74	struct _DiffTraits<_DiffType, void>
	75	{ typedef std::ptrdiff_t __type; };
	76
	77	typedef typename _DiffTraits<_ItDiffType>::__type _DiffType;
	78
	79	public:
	80	typedef std::pair<_DiffType, _Distance_precision> __type;
	81	};
	82
	83	template<typename _Integral>
	84	struct _Distance_traits<_Integral, std::__true_type>
	85	{ typedef std::pair<std::ptrdiff_t, _Distance_precision> __type; };
	86
	87	/** Determine the distance between two iterators with some known
	88	* precision.
	89	*/
	90	template<typename _Iterator>
	91	_GLIBCXX_CONSTEXPR
	92	inline typename _Distance_traits<_Iterator>::__type
	93	__get_distance(_Iterator __lhs, _Iterator __rhs,
	94	std::random_access_iterator_tag)
	95	{ return std::make_pair(__rhs - __lhs, __dp_exact); }
	96
	97	template<typename _Iterator>
	98	_GLIBCXX14_CONSTEXPR
	99	inline typename _Distance_traits<_Iterator>::__type
	100	__get_distance(_Iterator __lhs, _Iterator __rhs,
	101	std::input_iterator_tag)
	102	{
	103	if (__lhs == __rhs)
	104	return std::make_pair(0, __dp_exact);
	105
	106	return std::make_pair(1, __dp_equality);
	107	}
	108
	109	template<typename _Iterator>
	110	_GLIBCXX_CONSTEXPR
	111	inline typename _Distance_traits<_Iterator>::__type
	112	__get_distance(_Iterator __lhs, _Iterator __rhs)
	113	{
	114	return __gnu_debug::__get_distance(__lhs, __rhs,
	115	std::__iterator_category(__lhs));
	116	}
	117
	118	// An arbitrary iterator pointer is not singular.
	119	inline bool
	120	__check_singular_aux(const void*) { return false; }
	121
	122	// Defined in <debug/safe_base.h>
	123	bool
	124	__check_singular_aux(const class _Safe_iterator_base*);
	125
	126	// We may have an iterator that derives from _Safe_iterator_base but isn't
	127	// a _Safe_iterator.
	128	template<typename _Iterator>
	129	_GLIBCXX_CONSTEXPR
	130	inline bool
	131	__check_singular(_Iterator const& __x)
	132	{
	133	return ! std::__is_constant_evaluated()
	134	&& __gnu_debug::__check_singular_aux(std::__addressof(__x));
	135	}
	136
	137	/** Non-NULL pointers are nonsingular. */
	138	template<typename _Tp>
	139	_GLIBCXX_CONSTEXPR
	140	inline bool
	141	__check_singular(_Tp* const& __ptr)
	142	{ return __ptr == 0; }
	143
	144	/** We say that integral types for a valid range, and defer to other
	145	* routines to realize what to do with integral types instead of
	146	* iterators.
	147	*/
	148	template<typename _Integral>
	149	_GLIBCXX_CONSTEXPR
	150	inline bool
	151	__valid_range_aux(_Integral, _Integral, std::__true_type)
	152	{ return true; }
	153
	154	template<typename _Integral>
	155	_GLIBCXX20_CONSTEXPR
	156	inline bool
	157	__valid_range_aux(_Integral, _Integral,
	158	typename _Distance_traits<_Integral>::__type& __dist,
	159	std::__true_type)
	160	{
	161	__dist = std::make_pair(0, __dp_none);
	162	return true;
	163	}
	164
	165	template<typename _InputIterator>
	166	_GLIBCXX_CONSTEXPR
	167	inline bool
	168	__valid_range_aux(_InputIterator __first, _InputIterator __last,
	169	std::input_iterator_tag)
	170	{
	171	// FIXME: The checks for singular iterators fail during constant eval
	172	// due to PR c++/85944. e.g. PR libstdc++/109517 and PR libstdc++/109976.
	173	if (std::__is_constant_evaluated())
	174	return true;
	175
	176	return __first == __last
	177	\|\| (!__gnu_debug::__check_singular(__first)
	178	&& !__gnu_debug::__check_singular(__last));
	179	}
	180
	181	template<typename _InputIterator>
	182	_GLIBCXX_CONSTEXPR
	183	inline bool
	184	__valid_range_aux(_InputIterator __first, _InputIterator __last,
	185	std::random_access_iterator_tag)
	186	{
	187	return __gnu_debug::__valid_range_aux(__first, __last,
	188	std::input_iterator_tag())
	189	&& __first <= __last;
	190	}
	191
	192	/** We have iterators, so figure out what kind of iterators they are
	193	* to see if we can check the range ahead of time.
	194	*/
	195	template<typename _InputIterator>
	196	_GLIBCXX_CONSTEXPR
	197	inline bool
	198	__valid_range_aux(_InputIterator __first, _InputIterator __last,
	199	std::__false_type)
	200	{
	201	return __gnu_debug::__valid_range_aux(__first, __last,
	202	std::__iterator_category(__first));
	203	}
	204
	205	template<typename _InputIterator>
	206	_GLIBCXX20_CONSTEXPR
	207	inline bool
	208	__valid_range_aux(_InputIterator __first, _InputIterator __last,
	209	typename _Distance_traits<_InputIterator>::__type& __dist,
	210	std::__false_type)
	211	{
	212	if (!__gnu_debug::__valid_range_aux(__first, __last,
	213	std::input_iterator_tag()))
	214	return false;
	215
	216	__dist = __gnu_debug::__get_distance(__first, __last);
	217	switch (__dist.second)
	218	{
	219	case __dp_none:
	220	break;
	221	case __dp_equality:
	222	if (__dist.first == 0)
	223	return true;
	224	break;
	225	case __dp_sign:
	226	case __dp_sign_max_size:
	227	case __dp_exact:
	228	return __dist.first >= 0;
	229	}
	230
	231	// Can't tell so assume it is fine.
	232	return true;
	233	}
	234
	235	/** Don't know what these iterators are, or if they are even
	236	* iterators (we may get an integral type for InputIterator), so
	237	* see if they are integral and pass them on to the next phase
	238	* otherwise.
	239	*/
	240	template<typename _InputIterator>
	241	_GLIBCXX20_CONSTEXPR
	242	inline bool
	243	__valid_range(_InputIterator __first, _InputIterator __last,
	244	typename _Distance_traits<_InputIterator>::__type& __dist)
	245	{
	246	typedef typename std::__is_integer<_InputIterator>::__type _Integral;
	247	return __gnu_debug::__valid_range_aux(__first, __last, __dist,
	248	_Integral());
	249	}
	250
	251	template<typename _Iterator, typename _Sequence, typename _Category>
	252	bool
	253	__valid_range(const _Safe_iterator<_Iterator, _Sequence, _Category>&,
	254	const _Safe_iterator<_Iterator, _Sequence, _Category>&,
	255	typename _Distance_traits<_Iterator>::__type&);
	256
	257	#if __cplusplus >= 201103L
	258	template<typename _Iterator,typename _Sequence>
	259	bool
	260	__valid_range(const _Safe_local_iterator<_Iterator, _Sequence>&,
	261	const _Safe_local_iterator<_Iterator, _Sequence>&,
	262	typename _Distance_traits<_Iterator>::__type&);
	263	#endif
	264
	265	template<typename _InputIterator>
	266	_GLIBCXX14_CONSTEXPR
	267	inline bool
	268	__valid_range(_InputIterator __first, _InputIterator __last)
	269	{
	270	typedef typename std::__is_integer<_InputIterator>::__type _Integral;
	271	return __gnu_debug::__valid_range_aux(__first, __last, _Integral());
	272	}
	273
	274	template<typename _Iterator, typename _Sequence, typename _Category>
	275	bool
	276	__valid_range(const _Safe_iterator<_Iterator, _Sequence, _Category>&,
	277	const _Safe_iterator<_Iterator, _Sequence, _Category>&);
	278
	279	#if __cplusplus >= 201103L
	280	template<typename _Iterator, typename _Sequence>
	281	bool
	282	__valid_range(const _Safe_local_iterator<_Iterator, _Sequence>&,
	283	const _Safe_local_iterator<_Iterator, _Sequence>&);
	284	#endif
	285
	286	// Fallback method, always ok.
	287	template<typename _InputIterator, typename _Size>
	288	_GLIBCXX_CONSTEXPR
	289	inline bool
	290	__can_advance(_InputIterator, _Size)
	291	{ return true; }
	292
	293	template<typename _Iterator, typename _Sequence, typename _Category,
	294	typename _Size>
	295	bool
	296	__can_advance(const _Safe_iterator<_Iterator, _Sequence, _Category>&,
	297	_Size);
	298
	299	template<typename _InputIterator, typename _Diff>
	300	_GLIBCXX_CONSTEXPR
	301	inline bool
	302	__can_advance(_InputIterator, const std::pair<_Diff, _Distance_precision>&, int)
	303	{ return true; }
	304
	305	template<typename _Iterator, typename _Sequence, typename _Category,
	306	typename _Diff>
	307	bool
	308	__can_advance(const _Safe_iterator<_Iterator, _Sequence, _Category>&,
	309	const std::pair<_Diff, _Distance_precision>&, int);
	310
	311	/** Helper function to extract base iterator of random access safe iterator
	312	* in order to reduce performance impact of debug mode. Limited to random
	313	* access iterator because it is the only category for which it is possible
	314	* to check for correct iterators order in the __valid_range function
	315	* thanks to the < operator.
	316	*/
	317	template<typename _Iterator>
	318	_GLIBCXX_CONSTEXPR
	319	inline _Iterator
	320	__base(_Iterator __it)
	321	{ return __it; }
	322
	323	#if __cplusplus < 201103L
	324	template<typename _Iterator>
	325	struct _Unsafe_type
	326	{ typedef _Iterator _Type; };
	327	#endif
	328
	329	/* Remove debug mode safe iterator layer, if any. */
	330	template<typename _Iterator>
	331	_GLIBCXX_CONSTEXPR
	332	inline _Iterator
	333	__unsafe(_Iterator __it)
	334	{ return __it; }
	335	}
	336
	337	#endif