:py:mod:`core.utils.string`
===========================

.. py:module:: core.utils.string

.. autoapi-nested-parse::

   ViUR utility functions regarding string processing.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   core.utils.string.random
   core.utils.string.escape
   core.utils.string.unescape
   core.utils.string.is_prefix



Attributes
~~~~~~~~~~

.. autoapisummary::

   core.utils.string.__STRING_ESCAPE_MAPPING
   core.utils.string.__STRING_ESCAPE_TRANSTAB
   core.utils.string.__STRING_UNESCAPE_MAPPING


.. py:function:: random(length = 13)

   Return a string containing random characters of given *length*.
   It's safe to use this string in URLs or HTML.
   Because we use the secrets module it could be used for security purposes as well

   :param length: The desired length of the generated string.

   :returns: A string with random characters of the given length.


.. py:data:: __STRING_ESCAPE_MAPPING

   

.. py:data:: __STRING_ESCAPE_TRANSTAB

   

.. py:data:: __STRING_UNESCAPE_MAPPING

   

.. py:function:: escape(val, max_length = 254, maxLength = None)

   Quotes special characters from a string and removes "\\0".
   It shall be used to prevent XSS injections in data.

   :param val: The value to be escaped.
   :param max_length: Cut-off after max_length characters. None or 0 means "unlimited".

   :returns: The quoted string.


.. py:function:: unescape(val)

   Unquotes characters formerly escaped by `escape`.

   :param val: The value to be unescaped.
   :param max_length: Optional cut-off after max_length characters.             A value of None or 0 means "unlimited".

   :returns: The unquoted string.


.. py:function:: is_prefix(name, prefix, delimiter = '.')

   Utility function to check if a given name matches a prefix,
   which defines a specialization, delimited by `delimiter`.

   In ViUR, modules, bones, renders, etc. provide a kind or handler
   to classify or subclassify the specific object. To securitly
   check for a specific type, it is either required to ask for the
   exact type or if its prefixed by a path delimited normally by
   dots.

   Example:

   .. code-block:: python
       handler = "tree.file.special"
       utils.string.is_prefix(handler, "tree")  # True
       utils.string.is_prefix(handler, "tree.node")  # False
       utils.string.is_prefix(handler, "tree.file")  # True
       utils.string.is_prefix(handler, "tree.file.special")  # True