String Functions ---------------- .. index:: Macro function;fn.index * *fn.index* : Return the i'th item of an iterable, such as a list or string. .. index:: Macro function;fn.mask * *fn.mask* : Return a mask of (length + modifier) instances of char. .. index:: Macro function;fn.length * *fn.length* : Return the length of a string. .. index:: Macro function;fn.split * *fn.split* : Split a string by delimiter, returning a list. .. 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. .. index:: Macro function;fn.title * *fn.title* : Return a string in title case. .. index:: Macro function;fn.upper * *fn.upper* : Return an uppercase version of the input string. .. index:: Macro function;fn.lower * *fn.lower* : Return a lower case version of the input string. .. index:: Macro function;fn.contains * *fn.contains* : Return true or false if string is contained in another. .. index:: Macro function;fn.sub_string * *fn.sub_string* : Return the substring of a string from a start to an end position. .. index:: Macro function;fn.containsIgnoreCase * *fn.containsIgnoreCase* : Return true or false if string is contained in upper- or lower case. .. index:: Macro function;fn.containsStartsWith * *fn.containsStartsWith* : Return true or false if source string is the start of target string. .. index:: Macro function;fn.containsStartOf * *fn.containsStartOf* : Return true or false if start of source string is target string. .. index:: Macro function;fn.isexactly * *fn.isexactly* : Return true or false if source string is exactly the same as target string. .. index:: Macro function;fn.replace * *fn.replace* : Replace target substring for source substring in source string. .. 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. Examples: .. tabularcolumns:: |p{10cm}|p{5cm}| +-------------------------------------------+--------------------------+ | Example | Output | +===========================================+==========================+ | :: | :: | | | | | {{ fn.index 'foo bar baz', 5 }} | 'b' | | | | +-------------------------------------------+--------------------------+ | :: | :: | | | | | {{ fn.mask X, 2, 3 }} | XXXXXX | | | | +-------------------------------------------+--------------------------+ | :: | :: | | | | | {{ fn.length This is a valid string }} | 22 | +-------------------------------------------+--------------------------+ | :: | :: | | | | | {# fn.split foo:bar:baz,: #} | ['foo', 'bar', 'baz'] | +-------------------------------------------+--------------------------+ | :: | :: | | | | | {{ fn.join 1234, : }} | 1:2:3:4 | | | | | {{ fn.join 1234 }} | 1234 | +-------------------------------------------+--------------------------+ | :: | :: | | | | | {{ fn.title 'foo bar baz' }} | 'Foo Bar Baz' | +-------------------------------------------+--------------------------+ | :: | :: | | | | | {{ fn.upper somevalue }} | SOMEVALUE | | | | +-------------------------------------------+--------------------------+ .. tabularcolumns:: |p{10cm}|p{5cm}| +--------------------------------------------------+--------------+ | Example | Output | +==================================================+==============+ | :: | :: | | | | | {{ fn.lower SOMEVALUE }} | somevalue | | | | +--------------------------------------------------+--------------+ | :: | :: | | | | | {{ fn.contains needle, haystack }} | false | | | | | {{ fn.contains hay, haystack }} | true | | | | | (( fn.contains Kit, 1234 Kit Creek == True )) | true | +--------------------------------------------------+--------------+ | :: | :: | | | | | {{ fn.sub_string haystack, 0, 2 }} | hay | | | | | {{ fn.sub_string haystack, 7, 7 }} | k | +--------------------------------------------------+--------------+ | :: | :: | | | | | {{ fn.containsIgnoreCase aaa, bbbaAaccc }} | true | | | | +--------------------------------------------------+--------------+ | :: | :: | | | | | {{ fn.containsStartsWith aaa, aaaffccffdd }} | true | | | | +--------------------------------------------------+--------------+ | :: | :: | | | | | {{ fn.containsStartOf ffnnccgg, ffnn }} | true | | | | +--------------------------------------------------+--------------+ | :: | :: | | | | | {{ fn.isexactly source1, source1 }} | true | | | | +--------------------------------------------------+--------------+ | Note: no spaces between commas. | | | | | | :: | :: | | | | | {{ fn.replace dddddAAAc,AAA,FFF }} | dddddFFFc | | | | +--------------------------------------------------+--------------+ | :: | :: | | | | | {{ 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 and a "from" and "to" characters parameter pair, return a string with "from" characters replaced with "to" characters. This allows for control over the replacement. 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. 2. Map all "accented" (accent, circumflex, diaeresis, etc.) non-ASCII characters to ASCII characters. 3. Map all remaining non-ASCII characters with ``_``. 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 `_`. .. 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 | | | | +-----------------------------------+-------------+