.. index:: py::builtins::list::insert

.. _doxycast_pypp_classpy_1_1builtins_1_1list_1a3d351bbcbfb550954b3602b36251032d:

.. _py-builtins-list-insert:

*py::builtins::list::*\ insert
==============================

.. code-block:: cpp

     void insert(std::size_t index, const_reference element);        // 1

     void insert(std::size_t index, value_type&& element);           // 2

     template <class input_it>
     void insert(std::size_t index, input_it first, input_it last);  // 3

1.   Inserts given element at given index.

2.   Same as (1).

3.   Inserts given element range at given index.


Parameters
----------

``element``: The element to insert.

``first``: Iterator to the first element to insert.

``last``: Iterator to one past the last element to insert.


Complexity
----------

1.   Constant plus linear in the distance between ``index`` and
     the end if the insertion causes the memory to be
     reallocated, constant plus linear in the size of the list
     otherwise.

2.   Same as (1).

3.   Linear in the distance between ``first`` and ``last`` plus
     linear in the distance between ``index`` and the end.


Example
-------

.. code-block:: cpp

     #include <pypp/builtins/list.hpp>
     #include <pypp/builtins/print.hpp>

     int main()
     {
         py::list<int> list = {1, 3, 5};

         py::print(list);

         list.insert(0, 0);
         list.insert(2, 2);
         list.insert(-1, 4); // insert with negative index

         py::print(list);
     }

**Output**:

.. code-block:: text

     {1, 3, 5}
     {0, 1, 2, 3, 4, 5}