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

.. py:module:: core.bones.string


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

Classes
~~~~~~~

.. autoapisummary::

   core.bones.string.StringBone




Attributes
~~~~~~~~~~

.. autoapisummary::

   core.bones.string.DB_TYPE_INDEXED


.. py:data:: DB_TYPE_INDEXED
   :type: TypeAlias

   

.. py:class:: StringBone(*, caseSensitive = True, max_length = 254, min_length = None, natural_sorting = False, **kwargs)


   Bases: :py:obj:`viur.core.bones.base.BaseBone`

   The "StringBone" represents a data field that contains text values.

   Initializes a new StringBone.

   :param caseSensitive: When filtering for values in this bone, should it be case-sensitive?
   :param max_length: The maximum length allowed for values of this bone. Set to None for no limitation.
   :param min_length: The minimum length allowed for values of this bone. Set to None for no limitation.
   :param natural_sorting: Allows a more natural sorting
       than the default sorting on the plain values.
       This uses the .sort_idx property.
       `True` enables sorting according to DIN 5007 Variant 2.
       With passing a `callable`, a custom transformer method can be set
       that creates the value for the index property.
   :param kwargs: Inherited arguments from the BaseBone.

   .. py:attribute:: type
      :value: 'str'

      

   .. py:method:: type_coerce_single_value(value)

      Convert a value to a string (if not already)

      Converts a value that is not a string into a string
      if a meaningful conversion is possible (simple data types only).


   .. py:method:: singleValueSerialize(value, skel, name, parentIndexed)

      Serializes a single value of this data field for storage in the database.

      :param value: The value to serialize.
          It should be a str value, if not it is forced with :meth:`type_coerce_single_value`.
      :param skel: The skeleton instance that this data field belongs to.
      :param name: The name of this data field.
      :param parentIndexed: A boolean value indicating whether the parent object has an index on
          this data field or not.
      :return: The serialized value.


   .. py:method:: singleValueUnserialize(value)

      Unserializes a single value of this data field from the database.

      :param value: The serialized value to unserialize.
      :return: The unserialized value.


   .. py:method:: getEmptyValue()

      Returns the empty value for this data field.

      :return: An empty string.


   .. py:method:: isEmpty(value)

      Determines whether a value for this data field is empty or not.

      :param value: The value to check for emptiness.
      :return: A boolean value indicating whether the value is empty or not.


   .. py:method:: isInvalid(value)

      Returns None if the value would be valid for
      this bone, an error-message otherwise.


   .. py:method:: singleValueFromClient(value, skel, bone_name, client_data)

      Returns None and the escaped value if the value would be valid for
      this bone, otherwise the empty value and an error-message.


   .. py:method:: buildDBFilter(name, skel, dbFilter, rawFilter, prefix = None)

      Builds and returns a database filter for this data field based on the provided raw filter data.

      :param name: The name of this data field.
      :param skel: The skeleton instance that this data field belongs to.
      :param dbFilter: The database filter to add query clauses to.
      :param rawFilter: A dictionary containing the raw filter data for this data field.
      :param prefix: An optional prefix to add to the query clause.
      :return: The database filter with the added query clauses.


   .. py:method:: buildDBSort(name, skel, dbFilter, rawFilter)

      Build a DB sort based on the specified name and a raw filter.

      :param name: The name of the attribute to sort by.
      :param skel: A SkeletonInstance object.
      :param dbFilter: A Query object representing the current DB filter.
      :param rawFilter: A dictionary containing the raw filter.
      :return: The Query object with the specified sort applied.


   .. py:method:: natural_sorting(value)

      Implements a default natural sorting transformer.

      The sorting is according to DIN 5007 Variant 2
      and sets ö and oe, etc. equal.


   .. py:method:: getSearchTags(skel, name)

      Returns a set of lowercased words that represent searchable tags for the given bone.

      :param skel: The skeleton instance being searched.
      :param name: The name of the bone to generate tags for.

      :return: A set of lowercased words representing searchable tags.


   .. py:method:: getUniquePropertyIndexValues(skel, name)

      Returns a list of unique index values for a given property name.

      :param skel: The skeleton instance.
      :param name: The name of the property.
      :return: A list of unique index values for the property.
      :raises NotImplementedError: If the StringBone has languages and the implementation
          for this case is not yet defined.


   .. py:method:: refresh(skel, bone_name)

      Refresh all values we might have cached from other entities.


   .. py:method:: structure()

      Describes the bone and its settings as an JSON-serializable dict.
      This function has to be implemented for subsequent, specialized bone types.