.. default-domain:: chpl

.. module:: LinkedLists
   :synopsis: This module provides a simple singly linked list.

LinkedLists
===========
**Usage**

.. code-block:: chapel

   use LinkedLists;


or

.. code-block:: chapel

   import LinkedLists;


This module provides a simple singly linked list.

.. note::

    This module is expected to change in the future.


.. record:: LinkedList : serializable

   
   A singly linked list.
   
   .. note::
   
       :proc:`~LinkedList.destroy` must be called to reclaim any memory used by the list.
   
   

   .. attribute:: type eltType

      
      The type of the data stored in every node.
      

   .. attribute:: var size: int

      
      The number of nodes in the list.
      

   .. itermethod:: iter these()

      
      Iterate over the list, yielding each element.
      
      :ytype: eltType
      

   .. method:: proc ref append(e: eltType)

      
      Append `e` to the list.
      

   .. method:: proc ref push_back(e: eltType)

      
      Synonym for append.
      

   .. method:: proc ref append(e: eltType, es: eltType ...?k)

      
      Append all of the supplied arguments to the list.
      

   .. method:: proc ref prepend(e: eltType)

      
      Prepend `e` to the list.
      

   .. method:: proc push_front(e: eltType)

      
      Synonym for prepend.
      

   .. method:: proc ref concat(l: LinkedList(eltType))

      
      Append all the elements in `l` to the end of the list.
      

   .. method:: proc ref remove(x: eltType)

      
      Remove the first encountered instance of `x` from the list.
      Does nothing if `x` is not present in the list.
      

   .. method:: proc ref pop_front(): eltType

      
      Remove the first element from the list and return it.
      It is an error to call this function on an empty list.
      

   .. method:: proc contains(const e: eltType): bool

      
      Returns true if this list contains an element equal to the value of
      e. Returns false otherwise.
      
      :arg e: The element search for
      :return: `true` if the `e` was found
      :rtype: `bool`
      

   .. method:: proc ref first() ref: eltType

      
      Returns a reference to the first item in the list
      
      .. warning::
        Calling this method on an empty list will cause the currently running
        program to halt. If the --fast flag is used, no safety checks will be
        performed
      
      :return: a reference to the first item in the list
      :rtype: `ref eltType`
      

   .. method:: proc ref last() ref: eltType

      
      Returns a reference to the last item in the list
      
      .. warning::
        Calling this method on an empty list will cause the currently running
        program to halt. If the --fast flag is used, no safety checks will be
        performed
      
      :return: a reference to the last item in the list
      :rtype: `ref eltType`
      

   .. method:: proc ref destroy()

      
      Delete every node in the list.
      

   .. method:: proc serialize(writer, ref serializer) throws

   .. method:: proc ref deserialize(reader: fileReader, ref deserializer) throws where reader.deserializerType == IO.defaultDeserializer

   .. method:: proc ref deserialize(reader: fileReader, ref deserializer) throws

.. function:: proc makeList(x ...?k)

   
   Initialize a new :record:`LinkedList` containing all of the supplied arguments.
   
   :arg x: Every argument must be of type `T`.
   :type x: `T`
   :rtype: LinkedList(T)