Movatterモバイル変換

[0]ホーム
URL:

cppreference.com
Namespaces
Variants
    Actions

      C++ named requirements:SequenceContainer

      From cppreference.com
      <cpp‎ |named req
       
       
      C++ named requirements
       

      ASequenceContainer is aContainer that stores objects of the same type in a linear arrangement.

      Contents

      [edit]Requirements

      Given the following types and values:

      Type Definition
      C a sequence container class
      T the element type ofC
      A the allocator type ofC:
      R(since C++23) a type that modelscontainer-compatible-range <T>
      Args(since C++11) a template parameter pack
      IterC::iterator
      RefC::reference
      CRefC::const_reference
      Value Definition
      v a value of typeC
      cv a value of typeconst C
      i,jLegacyInputIterators such that[i, j) is avalid range and that the iterators refer to elements implicitly convertible toC::value_type
      rg(since C++23) a value of typeR
      il(since C++11) a value of typestd::initializer_list<C::value_type>
      n a value of typeC::size_type
      p a validconst iterator intov
      q avalid dereferenceable const iterator intov
      q1,q2 const iterators intov such that[q1, q2) is a valid range
      ta value(until C++11)anlvalue or const rvalue(since C++11) of typeC::value_type
      rv(since C++11) a non-const rvalue of typeC::value_type
      args(since C++11) a function parameter pack with the patternArg&&

      C satisfies the requirements ofSequenceContainer if all following conditions are satisfied:

      • C satisfies the requirements ofContainer.
      • The following statements and expressions are well-formed and have the specified semantics:
      Basic operations
      (required for all sequence containers in thestandard library exceptstd::array(since C++11))
      Statement    Semantics[1]
      C c(n, t);EffectConstructs the sequence container holdingn copies oft.
      Precondition

      T isCopyInsertable intoC.

      		(since C++11)
      Postcondition std::distance(c.begin(), c.end()) isn.
      C c(i, j);EffectConstructs the sequence container equal, element-wise, to the range[i, j).
      • Each iterator in the range[i, j) is dereferenced exactly once.
      Precondition

      T isEmplaceConstructible intoC from*i.

      		(since C++11)
      Postconditionstd::distance(c.begin(), c.end()) isstd::distance(i, j).
      Expression Type Semantics
      C(std::from_range, rg)
      (since C++23)      		CEffectConstructs the sequence container equal, element-wise, to the rangerg.
      • Each iterator in the rangerg is dereferenced exactly once.
      PreconditionT isEmplaceConstructible intoX from*ranges::begin(rg).
      Postconditionstd::distance(begin(), end()) isranges::distance(rg).
      C(il)
      (since C++11)      		CEquivalent toC(il.begin(), il.end()).
      v= il
      (since C++11)      		C&EffectAssigns the range represented byil intov.[2]
      Return value*this
      PreconditionT isCopyInsertable intoC andCopyAssignable.
      PostconditionExisting elements ofv are either destroyed or assigned to.
      v.emplace(p, args)
      (since C++11)      		Iter EffectInsert an object of typeT, constructed withstd::forward<Args>(args)... beforep.
      Return valueAn iterator that points to the new element constructed fromargs intov.
      PreconditionT isEmplaceConstructible intoC fromargs.
      v.insert(p, t)IterEffectInserts a copy oft beforep.
      Return valueAn iterator that points to the copy oft inserted intov.
      Precondition

      T isCopyInsertable intoC.

      		(since C++11)
      v.insert(p, rv)
      (since C++11)      		IterEffectInserts a copy ofrv beforep, possibly using move semantics.
      Return valueAn iterator that points to the copy ofrv inserted intov.
      PreconditionT isMoveInsertable intoC.
      v.insert(p, n, t)IterEffectInsertsn copies oft beforep.
      Return valueAn iterator that points to the copy of the first element inserted intov, orp ifn is​0​.
      Precondition

      T isCopyInsertable intoC andCopyAssignable.

      		(since C++11)
      v.insert(p, i, j)IterEffectInserts copies of elements in[i, j) beforep.
      • Each iterator in the range[i, j) is dereferenced exactly once.
      Return valueAn iterator that points to the copy of the first element inserted intov, orp ifi== j istrue.
      Precondition
      (since C++11)
      • i andj are not inv.
      v.insert_range(p, rg)
      (since C++23)      		IterEffectInserts copies of elements inrg beforep.
      • Each iterator in the rangerg is dereferenced exactly once.
      Return valueAn iterator that points to the copy of the first element inserted intov, orp ifrg is empty.
      Precondition
      v.insert(p, il)
      (since C++11)      		IterEquivalent tov.insert(p, il.begin(), il.end()).
      v.erase(q)IterEffectErases the element pointed to byq.
      Return valueAn iterator that points to the element immediately followingq prior to the element being erased, orv.end() if no such element exists.
      v.erase(q1, q2)IterEffectErases elements in[q1, q2).
      Return valueAn iterator that points to the element pointed to byq2 prior to any elements being erased, orv.end() if no such element exists.
      v.clear()voidEffectDestroys all elements inv.
      • Invalidates all references, pointers, and iterators referring to the elements ofv and may invalidate the past-the-end iterator.
      Postconditionv.empty() istrue.
      ComplexityLinear.
      v.assign(i, j)voidEffectReplaces elements inv with a copy of[i, j).
      • Invalidates all references, pointers and iterators referring to the elements ofv.
      • Each iterator in[i, j) is dereferenced exactly once.
      Precondition
      (since C++11)
      • i andj are not inv.
      v.assign_range(rg)
      (since C++23)      		voidEffectReplaces elements inv with a copy of each element inrg.
      • Ifstd::assignable_from
            <T&,ranges::range_reference_t<R>>         is not modeled, the program is ill-formed.
      • Invalidates all references, pointers and iterators referring to the elements ofv.
      • Each iterator in the rangerg is dereferenced exactly once.
      Precondition
      v.assign(il)
      (since C++11)      		voidEquivalent tov.assign(il.begin(), il.end()).
      v.assign(n, t)voidEffectReplaces elements inv withn copies oft.
      Precondition

      T isCopyInsertable intoC andCopyAssignable.

      		(since C++11)
          Extra operations[3]
      (only required for specified sequence containers, omittingstd::)
      Expression Type Semantics
      v.front()RefContainersbasic_string,array,vector,inplace_vector,deque,list,forward_list
      Return value*v.begin()
      cv.front()CRefContainersbasic_string,array,vector,inplace_vector,deque,list,forward_list
      Return value*cv.begin()
      v.back()RefContainersbasic_string,array,vector,inplace_vector,deque,list
      Equivalent toauto tmp= v.end();--tmp;return*tmp;[4].
      cv.back()CRefContainersbasic_string,array,vector,inplace_vector,deque,list
      Equivalent toauto tmp= cv.end();--tmp;return*tmp;[5].
      v.emplace_front(args)
      (since C++11)      		voidContainersdeque,list,forward_list
      EffectPrepends an object of typeT constructed withstd::forward<Args>(args)....
      Return valuev.front()
      PreconditionT isEmplaceConstructible intoC fromargs.
      v.emplace_back(args)
      (since C++11)      		voidContainersvector,inplace_vector,deque,list
      EffectAppends an object of typeT constructed withstd::forward<Args>(args)....
      Return valuev.back()
      PreconditionT isEmplaceConstructible intoC fromargs.
      v.push_front(t)voidContainersdeque,list,forward_list
      EffectPrepends a copy oft.
      Precondition

      T isCopyInsertable intoC.

      		(since C++11)
      v.push_front(rv)
      (since C++11)      		voidContainersdeque,list,forward_list
      EffectPrepends a copy ofrv, possibly using move semantics.
      PreconditionT isMoveInsertable intoC.
      v.prepend_range(rg)
      (since C++23)      		voidContainersdeque,list,forward_list
      EffectInserts[6] copies of elements inrg beforev.begin().
      • Each iterator in the rangerg is dereferenced exactly once.
      PreconditionT isEmplaceConstructible intoC from*ranges::begin(rg).
      v.push_back(t)voidContainersbasic_string,vector,inplace_vector,deque,list
      EffectAppends a copy oft.
      Precondition

      T isCopyInsertable intoC.

      		(since C++11)
      v.push_back(rv)
      (since C++11)      		voidContainersbasic_string,vector,inplace_vector,deque,list
      EffectAppends a copy ofrv, possibly using move semantics.
      PreconditionT isMoveInsertable intoC.
      v.append_range(rg)
      (since C++23)      		voidContainersvector,inplace_vector,deque,list
      EffectInserts[6] copies of elements inrg beforev.end().
      • Each iterator in the rangerg is dereferenced exactly once.
      PreconditionT isEmplaceConstructible intoC from*ranges::begin(rg).
      v.pop_front()voidContainersdeque,list,forward_list
      EffectDestroys the first element.
      Preconditiona.empty() isfalse.
      v.pop_back()voidContainersbasic_string,vector,inplace_vector,deque,list
      EffectDestroys the last element.
      Preconditiona.empty() isfalse.
      v[n]RefContainersbasic_string,array,vector,inplace_vector,deque
      Equivalent toreturn*(v.begin()+ n);.
      cv[n]CRefContainersbasic_string,array,vector,inplace_vector,deque
      Equivalent toreturn*(cv.begin()+ n);.
      v.at(n)RefContainersbasic_string,array,vector,inplace_vector,deque
      Return value*(v.begin()+ n)
      ExceptionsThrowsstd::out_of_range ifn>= v.size() istrue.
      cv.at(n)CRefContainersbasic_string,array,vector,inplace_vector,deque
      Return value*(cv.begin()+ n)
      ExceptionsThrowsstd::out_of_range ifn>= cv.size() istrue.
      Notes
      1. ↑For an expression whose effect is equivalent to some other operations, the conditions of the expressions inside those operations are inherited on top of the conditions listed in the table.
      2. ↑std::array supports assignment from abrace-enclosed initializer list, but not from anstd::initializer_list.
      3. ↑All operations below exceptprepend_range andappend_range(since C++23) take amortized constant time.
      4. ↑In C++98,tmp was declared to have typeC::iterator.
      5. ↑In C++98,tmp was declared to have typeC::const_iterator.
      6. ↑6.06.1Insertion order, relative to order of elements inrg, is non-reversing.

      Additionally, for every sequence container:

      • A constructor template that takes two input iterators and the member function template overloads ofinsert,append,assign,replace that take two input iterators do not participate in overload resolution if the corresponding template argument does not satisfyLegacyInputIterator.
      • A deduction guide that has either aLegacyInputIterator or anAllocator template parameter does not participate in overload resolution if the type that does not qualify as an input iterator or an allocator respectively is deduced for that parameter.
      		(since C++17)

      [edit]Standard library

      The following standard library string types and containers satisfy theSequenceContainer requirements:

      stores and manipulates sequences of characters
      (class template)[edit]
      (C++11)
      		 fixed-sized inplace contiguous array
      (class template)[edit]
      resizable contiguous array
      (class template)[edit]
      resizable, fixed capacity, inplace contiguous array
      (class template)[edit]
      double-ended queue
      (class template)[edit]
      singly-linked list
      (class template)[edit]
      doubly-linked list
      (class template)[edit]

      [edit]Usage notes

      ContainerProsCons
      std::vectorFast access, contiguous storageMostly inefficient insertions/deletions
      std::inplace_vectorFast access, inplace contiguous storageFixed capacity and mostly inefficient insertions/deletions
      std::arrayFast access, inplace contiguous storageFixed number of elements and no insertion/deletion
      std::dequeFast access, efficient insertion/deletion at the beginning/endInefficient insertion/deletion in the middle of the sequence
      std::list
      std::forward_list      		Efficient insertion/deletion in the middle of the sequenceAccess is mostly linear-time

      [edit]Defect reports

      The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

      DRApplied toBehavior as publishedCorrect behavior
      LWG 139C++98the optional operations were not required to
      be implemented for the designated containers      		required with amortized time
      LWG 149C++98v.insert(p, t) returnedIter while
      v.insert(p, n, t) andv.insert(p, n, t)
      returnedvoid      		they all returnIter
      LWG 151C++98q1 was required to be dereferenceable[1]it can be non-dereferenceable
      LWG 355C++98callingv.back() orv.pop_back() would
      execute--v.end(), which is dangerous[2]      		decrements a copy
      ofv.end() instead
      LWG 589C++98the elements thati andj refer to
      might not be convertible toC::value_type      		they are implicitly
      convertible toC::value_type
      LWG 2194C++11std::queue,std::priority_queue and
      std::stack were alsoSequenceContainers[3]      		they are notSequenceContainers
      LWG 2231C++11the complexity requirement ofv.clear()
      was mistakenly omitted in C++11      		complexity reaffirmed as linear
      LWG 3927C++98operator[] had no implicit requirementadded the implicit requirement
      1. ↑It is a defect because it makes the behavior ofv.erase(v.begin(), v.end()) undefined isv is an empty container.
      2. ↑If the type ofv.end() is a fundamental type,--v.end() is ill-formed. It is dangerous when the type ofv is templated, in this case this bug can be difficult to be found.
      3. ↑They were not documented asSequenceContainers in C++98.
      Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/named_req/SequenceContainer&oldid=182994"
      [8]ページ先頭
      ©2009-2025 Movatter.jp