.. include:: ../../global.rst

.. _`string handles`:

String Handles
==============

String handles use memory as their backing store otherwise they are
one implementation of :ref:`handles <handle type>`.

You can write to a string until you run out of memory in the same way
you can write to a file until you run of space in the file system.

You can only have input or output string handles, not a mixed form.

An output string handle requires an extra step,
:samp:`get-output-string {string-handle}` to retrieve the string in
the string handle.  Compare this with having to, say, :program:`cat` a
file to retrieve its contents after having written to it.



String Handle Predicates
------------------------


.. _`string-handle?`:

.. idio:function:: string-handle? o


   test if `o` is a string handle			
   						
   :param o: object to test			
   :return: ``#t`` if `o` is a string handle, ``#f`` otherwise	


.. _`input-string-handle?`:

.. idio:function:: input-string-handle? o


   test if `o` is a input string handle		
   						
   :param o: object to test			
   :return: ``#t`` if `o` is a input string handle, ``#f`` otherwise	


.. _`output-string-handle?`:

.. idio:function:: output-string-handle? o


   test if `o` is a output string handle			
   						
   :param o: object to test			
   :return: ``#t`` if `o` is a output string handle, ``#f`` otherwise	


String Handle Constructors
--------------------------


.. _`open-input-string`:

.. idio:function:: open-input-string str


   create an input string handle from `str`	
   						
   :param str: contents of input string handle	
   :type str: string				
   :return: input string handle			
   :rtype: handle					


.. _`open-output-string`:

.. idio:function:: open-output-string


   create an output string handle			
   						
   :return: output string handle			
   :rtype: handle					


String Handle Functions
-----------------------


.. _`get-output-string`:

.. idio:function:: get-output-string sh


   return the accumulated string in output string handle `sh`	
   						
   :param sh: output string handle			
   :type sh: output string handle			
   :return: accumulated string			
   :rtype: string					




.. include:: ../../commit.rst