stl_uninitialized.h

stl_uninitialized.h

/*
 *
 * Copyright (c) 1994
 * Hewlett-Packard Company
 *
 * Permission to use, copy, modify, distribute and sell this software
 * and its documentation for any purpose is hereby granted without fee,
 * provided that the above copyright notice appear in all copies and
 * that both that copyright notice and this permission notice appear
 * in supporting documentation.  Hewlett-Packard Company makes no
 * representations about the suitability of this software for any
 * purpose.  It is provided "as is" without express or implied warranty.
 *
 *
 * Copyright (c) 1996,1997
 * Silicon Graphics Computer Systems, Inc.
 *
 * Permission to use, copy, modify, distribute and sell this software
 * and its documentation for any purpose is hereby granted without fee,
 * provided that the above copyright notice appear in all copies and
 * that both that copyright notice and this permission notice appear
 * in supporting documentation.  Silicon Graphics makes no
 * representations about the suitability of this software for any
 * purpose.  It is provided "as is" without express or implied warranty.
  */

/*  NOTE: This is an internal header file, included by other STL headers.
 *   You should not attempt to use it directly.
  */

#ifndef __SGI_STL_INTERNAL_UNINITIALIZED_H
#define __SGI_STL_INTERNAL_UNINITIALIZED_H

__STL_BEGIN_NAMESPACE

//  uninitialized_copy : 
//  注意了解模板编程的思路。
//  利用 __VALUE_TYPE 取出型别定义
//  再次利用 __type_traits 取得类型特征
//  据类型特征直接转到特例化的模板函数。
//  优点：
//  避免在运行时判断数值的型别，在编译期就可以确定数值的最优处理方案。



//  Valid if copy construction is equivalent to assignment, and if the
//   destructor is trivial.
template < class _InputIter,  class _ForwardIter>
inline _ForwardIter 
__uninitialized_copy_aux(_InputIter __first, _InputIter __last,
                         _ForwardIter __result,
                         __true_type)  //  __true_type 是型别，不是变量
{
     //  是常规类型，可以不一个个执行拷贝构造函数
   return copy(__first, __last, __result);
}

template < class _InputIter,  class _ForwardIter>
_ForwardIter 
__uninitialized_copy_aux(_InputIter __first, _InputIter __last,
                         _ForwardIter __result,
                         __false_type)
{
     //  这是非标准的型别，我们需要执行它的拷贝构造函式来构建
  _ForwardIter __cur = __result;
  __STL_TRY {
     for ( ; __first != __last; ++__first, ++__cur)
         //  逐个构造数据， 这里用的是 _Construct 的 place new 访问方式。
      _Construct(&*__cur, *__first);
     return __cur;
  }
   //  在失败时，还需要清除构建的对象，这是由 STL 标准控制
  __STL_UNWIND(_Destroy(__result, __cur));
}

//  临时构建的模板函式，用来区分纯量型型别
template < class _InputIter,  class _ForwardIter,  class _Tp>
inline _ForwardIter
__uninitialized_copy(_InputIter __first, _InputIter __last,
                     _ForwardIter __result, _Tp*)
{
     //  利用 type_traits 分列出数据类型，是否是 POD
     //  什么是？ 
     //  POD 意指 Plain Old Data，也就是纯量型別（scalar types）或传统的 C struct 型別。
     //  PDO 具有更高效率的构造方式，即直接从内存复制，而不需要拷贝构造函数。
  typedef typename __type_traits<_Tp>::is_POD_type _Is_POD; 

   //  按照是否构造函数无关紧要，来拷贝数据
   return __uninitialized_copy_aux(__first, __last, __result, _Is_POD());
}

//  通用式，它根据 __VALUE_TYPE 取数值类型
template < class _InputIter,  class _ForwardIter>
inline _ForwardIter
  uninitialized_copy(_InputIter __first, _InputIter __last,
                     _ForwardIter __result)
{
   return __uninitialized_copy(__first, __last, __result,
                              __VALUE_TYPE(__result));
}

//  这是特例化的，征对 char 和 wchar_t 的特例
inline  char* uninitialized_copy( const  char* __first,  const  char* __last,
                                 char* __result) {
  memmove(__result, __first, __last - __first);
   return __result + (__last - __first);
}

inline wchar_t* 
uninitialized_copy( const wchar_t* __first,  const wchar_t* __last,
                   wchar_t* __result)
{
  memmove(__result, __first,  sizeof(wchar_t) * (__last - __first));
   return __result + (__last - __first);
}
 
// uninitialized_copy<__VALUE_TYPE> 
//     ---->     __uninitialized_copy<__type_traits> : is_POD_type
//
//                 ---->     __uninitialized_copy_aux<__false_type>
//                         __uninitialized_copy_aux<__false_type>
//                 
// uninitialized_copy<char>
// uninitialized_copy<wchar_t>





















//  uninitialized_copy_n (not part of the C++ standard)

template < class _InputIter,  class _Size,  class _ForwardIter>
pair<_InputIter, _ForwardIter>
__uninitialized_copy_n(_InputIter __first, _Size __count,
                       _ForwardIter __result,
                       input_iterator_tag)
{
  _ForwardIter __cur = __result;
  __STL_TRY {
     for ( ; __count > 0 ; --__count, ++__first, ++__cur) 
      _Construct(&*__cur, *__first);
     return pair<_InputIter, _ForwardIter>(__first, __cur);
  }
  __STL_UNWIND(_Destroy(__result, __cur));
}

template < class _RandomAccessIter,  class _Size,  class _ForwardIter>
inline pair<_RandomAccessIter, _ForwardIter>
__uninitialized_copy_n(_RandomAccessIter __first, _Size __count,
                       _ForwardIter __result,
                       random_access_iterator_tag) {
  _RandomAccessIter __last = __first + __count;
   return pair<_RandomAccessIter, _ForwardIter>(
                 __last,
                 uninitialized_copy(__first, __last, __result));
}

template < class _InputIter,  class _Size,  class _ForwardIter>
inline pair<_InputIter, _ForwardIter>
__uninitialized_copy_n(_InputIter __first, _Size __count,
                     _ForwardIter __result) {
   return __uninitialized_copy_n(__first, __count, __result,
                                __ITERATOR_CATEGORY(__first));
}

template < class _InputIter,  class _Size,  class _ForwardIter>
inline pair<_InputIter, _ForwardIter>
uninitialized_copy_n(_InputIter __first, _Size __count,
                     _ForwardIter __result) {
   return __uninitialized_copy_n(__first, __count, __result,
                                __ITERATOR_CATEGORY(__first));
}

















//  uninitialized_fill : 

//  这里是把一个集合的数据 [__first, __last) ，按 __x 值进行填充
//  这里的做法和 uninitialized_copy 一致

//  Valid if copy construction is equivalent to assignment, and if the
//  destructor is trivial.
template < class _ForwardIter,  class _Tp>
inline  void
__uninitialized_fill_aux(_ForwardIter __first, _ForwardIter __last, 
                          const _Tp& __x, __true_type)
{
  fill(__first, __last, __x);
}

template < class _ForwardIter,  class _Tp>
void
__uninitialized_fill_aux(_ForwardIter __first, _ForwardIter __last, 
                          const _Tp& __x, __false_type)
{
  _ForwardIter __cur = __first;
  __STL_TRY {
     for ( ; __cur != __last; ++__cur)
      _Construct(&*__cur, __x);  //  place new ，你懂的！ __x 是常量的引用传递
  }
  __STL_UNWIND(_Destroy(__first, __cur));  //  出事了？ STL 标准要求删除所有已构建的对象实例
}

template < class _ForwardIter,  class _Tp,  class _Tp1>
inline  void __uninitialized_fill(_ForwardIter __first, 
                                 _ForwardIter __last,  const _Tp& __x, _Tp1*)
{
  typedef typename __type_traits<_Tp1>::is_POD_type _Is_POD;

  __uninitialized_fill_aux(__first, __last, __x, _Is_POD());
}

template < class _ForwardIter,  class _Tp>
inline  void uninitialized_fill(_ForwardIter __first,
                               _ForwardIter __last, 
                                const _Tp& __x)
{
  __uninitialized_fill(__first, __last, __x, __VALUE_TYPE(__first));
}
















//  uninitialized_fill_n : 

//  这个模板填充一个集合，其成员从 [ __first, __first + n ) 
//  内容统一设置成 __x
//  实作技法同上

//  Valid if copy construction is equivalent to assignment, and if the
//   destructor is trivial.
template < class _ForwardIter,  class _Size,  class _Tp>
inline _ForwardIter
__uninitialized_fill_n_aux(_ForwardIter __first, _Size __n,
                            const _Tp& __x, __true_type)
{
   return fill_n(__first, __n, __x);
}

template < class _ForwardIter,  class _Size,  class _Tp>
_ForwardIter
__uninitialized_fill_n_aux(_ForwardIter __first, _Size __n,
                            const _Tp& __x, __false_type)
{
  _ForwardIter __cur = __first;
  __STL_TRY {
     for ( ; __n > 0; --__n, ++__cur)
      _Construct(&*__cur, __x);
     return __cur;
  }
  __STL_UNWIND(_Destroy(__first, __cur));
}

template < class _ForwardIter,  class _Size,  class _Tp,  class _Tp1>
inline _ForwardIter 
__uninitialized_fill_n(_ForwardIter __first, _Size __n,  const _Tp& __x, _Tp1*)
{
  typedef typename __type_traits<_Tp1>::is_POD_type _Is_POD;
   return __uninitialized_fill_n_aux(__first, __n, __x, _Is_POD());
}

template < class _ForwardIter,  class _Size,  class _Tp>
inline _ForwardIter 
uninitialized_fill_n(_ForwardIter __first, _Size __n,  const _Tp& __x)
{
   return __uninitialized_fill_n(__first, __n, __x, __VALUE_TYPE(__first));
}
























//  Extensions: __uninitialized_copy_copy, __uninitialized_copy_fill, 
//  __uninitialized_fill_copy.


//  这个函数用来把 2 个 区间内的数据，拷贝到一个里边去。
//  它首先拷贝 [first1, last1)  部分，
//  再接着把 [first2, last2) 拷贝到了接下来的缓冲区
//  __uninitialized_copy_copy
//  Copies [first1, last1) into [result, result + (last1 - first1)), and
//   copies [first2, last2) into
//  原文这应该是写了错误的注释：  [result, result + (last1 - first1) + (last2 - first2)).
//  正确来说，它应该是  [result + (last1 - first1) , result + (last1 - first1) + (last2 - first2)).
//  或者  [ __mid , __mid + (last2 - first2)).

template < class _InputIter1,  class _InputIter2,  class _ForwardIter>
inline _ForwardIter
__uninitialized_copy_copy(_InputIter1 __first1, _InputIter1 __last1,
                          _InputIter2 __first2, _InputIter2 __last2,
                          _ForwardIter __result)
{
  _ForwardIter __mid = uninitialized_copy(__first1, __last1, __result);
  __STL_TRY {
     return uninitialized_copy(__first2, __last2, __mid);
  }
  __STL_UNWIND(_Destroy(__result, __mid));
}

//  __uninitialized_fill_copy
//  Fills [result, mid) with x, and copies [first, last) into
//   [mid, mid + (last - first)).
template < class _ForwardIter,  class _Tp,  class _InputIter>
inline _ForwardIter 
__uninitialized_fill_copy(_ForwardIter __result, _ForwardIter __mid,
                           const _Tp& __x,
                          _InputIter __first, _InputIter __last)
{
  uninitialized_fill(__result, __mid, __x);
  __STL_TRY {
     return uninitialized_copy(__first, __last, __mid);
  }
  __STL_UNWIND(_Destroy(__result, __mid));
}

//  __uninitialized_copy_fill
//  Copies [first1, last1) into [first2, first2 + (last1 - first1)), and
//   fills [first2 + (last1 - first1), last2) with x.
template < class _InputIter,  class _ForwardIter,  class _Tp>
inline  void
__uninitialized_copy_fill(_InputIter __first1, _InputIter __last1,
                          _ForwardIter __first2, _ForwardIter __last2,
                           const _Tp& __x)
{
  _ForwardIter __mid2 = uninitialized_copy(__first1, __last1, __first2);
  __STL_TRY {
    uninitialized_fill(__mid2, __last2, __x);
  }
  __STL_UNWIND(_Destroy(__first2, __mid2));
}













__STL_END_NAMESPACE

#endif /* __SGI_STL_INTERNAL_UNINITIALIZED_H */

//  Local Variables:
//  mode:C++
//  End: