.. _macro-string-functions: String functions ---------------- .. _20.1.1|EKB-4160: .. _21.1|EKB-8033: .. _19.3.4-PB4|EKB-8965: .. index:: Macro function;fn.is_string * *fn.is_string* : Return true or false if the parameter is a string or not. .. index:: Macro function;fn.index * *fn.index* : Return the i'th item of an iterable, such as a list or string. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+--------------------------+ | Example | Output | +===========================================+==========================+ | :: | :: | | | | | {{ fn.index 'foo bar baz',5 }} | 'b' | | | | +-------------------------------------------+--------------------------+ .. index:: Macro function;fn.mask * *fn.mask* : Return a mask of (length + modifier) instances of char. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+--------------------------+ | Example | Output | +===========================================+==========================+ | :: | :: | | | | | {{ fn.mask X,2,3 }} | XXXXXX | | | | +-------------------------------------------+--------------------------+ .. index:: Macro function;fn.length * *fn.length* : Return the length of a string. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+--------------------------+ | Example | Output | +===========================================+==========================+ | :: | :: | | | | | {{ fn.length This is a valid string }} | 22 | +-------------------------------------------+--------------------------+ .. index:: Macro function;fn.split * *fn.split* : Split a string by delimiter, returning a list. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+--------------------------+ | Example | Output | +===========================================+==========================+ | :: | :: | | | | | {# fn.split foo:bar:baz,: #} | ['foo', 'bar', 'baz'] | +-------------------------------------------+--------------------------+ .. index:: Macro function;fn.join * *fn.join* : Join a string by delimiter. If no delimiter is provided, the list is returned as a single string. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+--------------------------+ | Example | Output | +===========================================+==========================+ | :: | :: | | | | | {{ fn.join 1234,: }} | 1:2:3:4 | | | | | {{ fn.join 1234 }} | 1234 | +-------------------------------------------+--------------------------+ .. index:: Macro function;fn.title * *fn.title* : Return a string in title case. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+--------------------------+ | Example | Output | +===========================================+==========================+ | :: | :: | | | | | {{ fn.title 'foo bar baz' }} | 'Foo Bar Baz' | +-------------------------------------------+--------------------------+ .. index:: Macro function;fn.upper * *fn.upper* : Return an uppercase version of the input string. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+--------------------------+ | Example | Output | +===========================================+==========================+ | :: | :: | | | | | {{ fn.upper somevalue }} | SOMEVALUE | | | | +-------------------------------------------+--------------------------+ .. index:: Macro function;fn.lower * *fn.lower* : Return a lower case version of the input string. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------------------------------------+-------------------------------+ | Example | Output | +============================================================+===============================+ | :: | :: | | | | | {{ fn.lower SOMEVALUE }} | somevalue | | | | +------------------------------------------------------------+-------------------------------+ .. index:: Macro function;fn.contains * *fn.contains* : Return true or false if string is contained in another. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------------------------------------+-------------------------------+ | Example | Output | +============================================================+===============================+ | :: | :: | | | | | {{ fn.contains needle,haystack }} | false | | | | | {{ fn.contains hay,haystack }} | true | | | | | (( fn.contains Kit,1234 Kit Creek == True )) | true | +------------------------------------------------------------+-------------------------------+ .. index:: Macro function;fn.sub_string * *fn.sub_string* : Return the substring of a string from a start to an end position. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------------------------------------+-------------------------------+ | Example | Output | +============================================================+===============================+ | :: | :: | | | | | {{ fn.sub_string haystack,0,2 }} | hay | | | | | {{ fn.sub_string haystack,7,7 }} | k | +------------------------------------------------------------+-------------------------------+ .. index:: Macro function;fn.containsIgnoreCase * *fn.containsIgnoreCase* : Return true or false if string is contained in upper- or lower case. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------------------------------------+-------------------------------+ | Example | Output | +============================================================+===============================+ | :: | :: | | | | | {{ fn.containsIgnoreCase aaa,bbbaAaccc }} | true | | | | +------------------------------------------------------------+-------------------------------+ +----------------------------------------------------------+-----------------+ | Example | Output | +==========================================================+=================+ | Input | | | | | | :: | | | | | | {"input": {"UserName": "user@host.org"}} | | | | | | Function call | | | | | | :: | :: | | | | | ((fn.containsIgnoreCase Host,input.UserName == True)) | user@host.org | | <{{input.UserName}}><> | | | | | +----------------------------------------------------------+-----------------+ .. index:: Macro function;fn.containsStartsWith * *fn.containsStartsWith* : Return true or false if source string is the start of target string. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------------------------------------+-------------------------------+ | Example | Output | +============================================================+===============================+ | :: | :: | | | | | {{ fn.containsStartsWith aaa,aaaffccffdd }} | true | | | | +------------------------------------------------------------+-------------------------------+ .. index:: Macro function;fn.containsStartOf * *fn.containsStartOf* : Return true or false if start of source string is target string. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------------------------------------+-------------------------------+ | Example | Output | +============================================================+===============================+ | :: | :: | | | | | {{ fn.containsStartOf ffnnccgg,ffnn }} | true | | | | +------------------------------------------------------------+-------------------------------+ .. index:: Macro function;fn.regex_match * *fn.regex_match* : Return true or false if the regular expression matches the start of target string. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------+---------+ | Example | Output | +=====================================+=========+ | :: | :: | | | | | {{ fn.regex_match a,ab }} | true | | | | +-------------------------------------+---------+ | :: | :: | | | | | {{ fn.regex_match a$,ab }} | false | | | | +-------------------------------------+---------+ | :: | :: | | | | | {{ fn.regex_match \d+,abc555 }} | false | | | | +-------------------------------------+---------+ | :: | :: | | | | | {{ fn.regex_match \d+,555abc }} | true | | | | +-------------------------------------+---------+ .. index:: Macro function;fn.isexactly * *fn.isexactly* : Return true or false if source string is exactly the same as target string. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------------------------------------+-------------------------------+ | Example | Output | +============================================================+===============================+ | :: | :: | | | | | {{ fn.isexactly source1,source1 }} | true | | | | +------------------------------------------------------------+-------------------------------+ .. index:: Macro function;fn.replace * *fn.replace* : Replace target substring for source substring in source string. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------------------------------------+-------------------------------+ | Example | Output | +============================================================+===============================+ | Note: no spaces between commas. | | | | | | :: | :: | | | | | {{ fn.replace dddddAAAc,AAA,FFF }} | dddddFFFc | | | | +------------------------------------------------------------+-------------------------------+ .. index:: Macro function;fn.validate_name * *fn.validate_name* : Return true or false if the string as well as its stripped content (default white space removed) exists, i.e. is then more than 0 characters. .. tabularcolumns:: |p{10cm}|p{5cm}| +-----------------------------+---------+ | Example | Output | +=============================+=========+ | | | | :: | :: | | | | | {{ fn.validate_name }} | false | | | | | {{ fn.validate_name a }} | true | | | | +-----------------------------+---------+ .. index:: Macro function;fn.fix_non_ascii * *fn.fix_non_ascii* : Given a string containing non-ASCII characters, this function applies 3 steps of processing and returns a string with all non-ASCII characters mapped to ASCII characters. The first step can be controlled by the optional "from" and "to" characters parameter pair that return a string with "from" characters replaced with "to" characters. This allows for control over the replacement. The 3 steps are carried out in the following sequence: 1. Map characters in the given string by using the corresponding characters in the "*,*" string parameter pair. * If the parameters are not added, this step is skipped. * If it is required to have control over the mapping of non "accented" characters (see step 2), then this default mapping can be done by providing the "*,*" string parameter pair. 2. Map all "accented" (accent, circumflex, diaeresis, etc.) non-ASCII characters to ASCII characters. 3. Map all remaining non-ASCII characters with the underscore character: ``_``. For example: * string = ``Ŧest Nón Asciï`` * *,* = ``ï,G`` * result = ``_est Non AsciG`` step 1: from = ``ï`` is replaced with to = ``G``. step 2: accented ``ó`` is replaced with ``o`` step 3: ``Ŧ`` is a remaining non-ASCII character and replaced with ``_``. In the above example, the ``Ŧ`` is not an "accented" character and was therefore not mapped in step 2. If the preference is not to have the ``Ŧ`` character mapped to the underscore character, then this character could be included in the "*,*" string parameter pair. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------------------------------------+-------------------------------+ | Example | Output | +============================================================+===============================+ | :: | :: | | | | | | | | {{ fn.fix_non_ascii 'Têst Nón Asciïæ mapping',sæ,Ga }} | 'TeGt Non AGciia mapping' | | | | | {{ fn.fix_non_ascii 'Ŧest Nón Asciï' }} | '_est Non Ascii' | | | | +------------------------------------------------------------+-------------------------------+ .. index:: Macro function;fn.fix_username * *fn.fix_username* : Given a string of characters, return the string with a replacement character: ``-`` for any character *not* in the following range: ``a-zA-Z0-9._-``. A Unified CM Remote Destination name is an example where such a string is required. .. tabularcolumns:: |p{10cm}|p{5cm}| +-----------------------------------+-------------+ | Example | Output | +===================================+=============+ | | | | :: | :: | | | | | {{ fn.fix_username O'Reilly }} | O-Reilly | | | | +-----------------------------------+-------------+ .. index:: Macro function;fn.format_string_if_prefixed * *fn.format_string_if_prefixed* : Given 3 input parameters: * a string to format * a string of starting characters matching the string to format * a prefix string return a string with a prefix. If the string of starting characters is *not* present in the string to format, no prefix is added. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------+---------------------+ | Example | Output | +=====================================+=====================+ | | | | :: | :: | | | | | {{ fn.format_string_if_prefixed | AddPrefix-foobar | | "foobar", | | | "foo", | | | "AddPrefix-" }} | | | | | +-------------------------------------+---------------------+ .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------+---------------------+ | Example | Output | +=====================================+=====================+ | | | | :: | :: | | | | | {{ fn.format_string_if_prefixed | foobar | | "foobar", | | | "no", | | | "AddPrefix-" }} | | | | | +-------------------------------------+---------------------+ .. index:: Macro function;fn.format_if_prefixed * *fn.format_if_prefixed* : Given 3 input parameters: * a string to format *or* a list of strings * a string of starting characters of the string to format * a prefix string return a prefixed string or the list with a prefixed string. If the string of starting characters is *not* present in the string to format, no prefix is added. .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------+-------------------------+ | Example | Output | +==============================+=========================+ | | | | :: | :: | | | | | {{ fn.format_if_prefixed | AddPrefix-foobar | | "foobar", | | | "foo", | | | "AddPrefix-" }} | | | | | +------------------------------+-------------------------+ .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------+-------------------------+ | Example | Output | +==============================+=========================+ | | | | :: | :: | | | | | {{ fn.format_if_prefixed | ["AddPrefix-foobar", | | ["foobar","baz"], | "baz"] | | "foo", | | | "AddPrefix-" }} | | | | | +------------------------------+-------------------------+ .. tabularcolumns:: |p{10cm}|p{5cm}| +------------------------------+----------------------+ | Example | Output | +==============================+======================+ | | | | :: | :: | | | | | {{ fn.format_if_prefixed | ["foobar", "baz"] | | ["foobar","baz"], | | | "no", | | | "AddPrefix-" }} | | | | | +------------------------------+----------------------+ .. index:: Macro function;fn.add_backslash_to_plus * *fn.add_backslash_to_plus* : Given: * a string starting with a plus (``+``) or * a list of strings containing a string starting with a plus (``+``) return that string with a backslash prefix. .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+-------------------------+ | Example | Output | +===========================================+=========================+ | | | | :: | :: | | | | | {{ fn.add_backslash_to_plus "+123" }} | "\\+123" | | | | +-------------------------------------------+-------------------------+ .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+-------------------------+ | Example | Output | +===========================================+=========================+ | | | | :: | :: | | | | | {{ fn.add_backslash_to_plus | ["\\+foobar", "baz"] | | ["+foobar", "baz"] }} | | | | | +-------------------------------------------+-------------------------+