func_strings.c

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2005-2006, Digium, Inc.
 * Portions Copyright (C) 2005, Tilghman Lesher.  All rights reserved.
 * Portions Copyright (C) 2005, Anthony Minessale II
 * Portions Copyright (C) 2021, 2022, Naveen Albert
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 *
 * \brief String manipulation dialplan functions
 *
 * \author Tilghman Lesher
 * \author Anthony Minessale II
 * \author Naveen Albert
 * \ingroup functions
 */

/*** MODULEINFO
	<support_level>core</support_level>
 ***/

#include "asterisk.h"

#include <regex.h>
#include <ctype.h>

#include "asterisk/module.h"
#include "asterisk/channel.h"
#include "asterisk/pbx.h"
#include "asterisk/utils.h"
#include "asterisk/app.h"
#include "asterisk/localtime.h"
#include "asterisk/test.h"

AST_THREADSTORAGE(result_buf);
AST_THREADSTORAGE(tmp_buf);

/*** DOCUMENTATION
	<function name="FIELDQTY" language="en_US">
		<synopsis>
			Count the fields with an arbitrary delimiter
		</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="delim" required="true" />
		</syntax>
		<description>
			<para>The delimiter may be specified as a special or extended ASCII character, by encoding it.  The characters
			<literal>\n</literal>, <literal>\r</literal>, and <literal>\t</literal> are all recognized as the newline,
			carriage return, and tab characters, respectively.  Also, octal and hexadecimal specifications are recognized
			by the patterns <literal>\0nnn</literal> and <literal>\xHH</literal>, respectively.  For example, if you wanted
			to encode a comma as the delimiter, you could use either <literal>\054</literal> or <literal>\x2C</literal>.</para>
			<example title="Prints 3">
			exten => s,1,Set(example=ex-amp-le)
				same => n,NoOp(${FIELDQTY(example,-)})
			</example>
		</description>
	</function>
	<function name="FIELDNUM" language="en_US">
		<synopsis>
			Return the 1-based offset of a field in a list
		</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="delim" required="true" />
			<parameter name="value" required="true" />
		</syntax>
		<description>
			<para>Search the variable named <replaceable>varname</replaceable> for the string <replaceable>value</replaceable>
			delimited by <replaceable>delim</replaceable> and return a 1-based offset as to its location. If not found
			or an error occured, return <literal>0</literal>.</para>
			<para>The delimiter may be specified as a special or extended ASCII character, by encoding it.  The characters
			<literal>\n</literal>, <literal>\r</literal>, and <literal>\t</literal> are all recognized as the newline,
			carriage return, and tab characters, respectively.  Also, octal and hexadecimal specifications are recognized
			by the patterns <literal>\0nnn</literal> and <literal>\xHH</literal>, respectively.  For example, if you wanted
			to encode a comma as the delimiter, you could use either <literal>\054</literal> or <literal>\x2C</literal>.</para>
			<example title="Prints 2">
			exten => s,1,Set(example=ex-amp-le)
				same => n,NoOp(${FIELDNUM(example,-,amp)})
			</example>
		</description>
	</function>
	<function name="LISTFILTER" language="en_US">
		<synopsis>Remove an item from a list, by name.</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="delim" required="true" default="," />
			<parameter name="value" required="true" />
		</syntax>
		<description>
			<para>Remove <replaceable>value</replaceable> from the list contained in the <replaceable>varname</replaceable>
			variable, where the list delimiter is specified by the <replaceable>delim</replaceable> parameter.  This is
			very useful for removing a single channel name from a list of channels, for example.</para>
		</description>
	</function>
	<function name="FILTER" language="en_US">
		<synopsis>
			Filter the string to include only the allowed characters
		</synopsis>
		<syntax>
			<parameter name="allowed-chars" required="true" />
			<parameter name="string" required="true" />
		</syntax>
		<description>
			<para>Permits all characters listed in <replaceable>allowed-chars</replaceable>,
			filtering all others outs. In addition to literally listing the characters,
			you may also use ranges of characters (delimited by a <literal>-</literal></para>
			<para>Hexadecimal characters started with a <literal>\x</literal>(i.e. \x20)</para>
			<para>Octal characters started with a <literal>\0</literal> (i.e. \040)</para>
			<para>Also <literal>\t</literal>,<literal>\n</literal> and <literal>\r</literal> are recognized.</para>
			<note><para>If you want the <literal>-</literal> character it needs to be prefixed with a
			<literal>\</literal></para></note>
		</description>
	</function>
	<function name="REPLACE" language="en_US">
		<synopsis>
			Replace a set of characters in a given string with another character.
		</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="find-chars" required="true" />
			<parameter name="replace-char" required="false" />
		</syntax>
		<description>
			<para>Iterates through a string replacing all the <replaceable>find-chars</replaceable> with
			<replaceable>replace-char</replaceable>.  <replaceable>replace-char</replaceable> may be either
			empty or contain one character.  If empty, all <replaceable>find-chars</replaceable> will be
			deleted from the output.</para>
			<note><para>The replacement only occurs in the output.  The original variable is not
			altered.</para></note>
		</description>
	</function>
	<function name="STRREPLACE" language="en_US">
		<synopsis>
			Replace instances of a substring within a string with another string.
		</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="find-string" required="true" />
			<parameter name="replace-string" required="false" />
			<parameter name="max-replacements" required="false" />
		</syntax>
		<description>
			<para>Searches for all instances of the <replaceable>find-string</replaceable> in provided variable and
			replaces them with <replaceable>replace-string</replaceable>.  If <replaceable>replace-string</replaceable>
			is an empty string, this will effectively delete that substring.  If <replaceable>max-replacements</replaceable>
			is specified, this function will stop after performing replacements <replaceable>max-replacements</replaceable> times.</para>
			<note><para>The replacement only occurs in the output.  The original variable is not altered.</para></note>
		</description>
	</function>
	<function name="STRBETWEEN" language="en_US">
		<since>
			<version>16.21.0</version>
			<version>18.7.0</version>
			<version>19.0.0</version>
		</since>
		<synopsis>
			Inserts a substring between each character in a string.
		</synopsis>
		<syntax>
			<parameter name="varname" required="true" />
			<parameter name="insert-string" required="true" />
		</syntax>
		<description>
			<para>Inserts a substring <replaceable>find-string</replaceable> between each character in
			<replaceable>varname</replaceable>.</para>
			<note><para>The replacement only occurs in the output.  The original variable is not altered.</para></note>
			<example title="Add half-second pause between dialed digits">
				same => n,Set(digits=5551212)
				same => n,SendDTMF(${STRBETWEEN(digits,w)) ; this will send 5w5w5w1w2w1w2
			</example>
		</description>
	</function>
	<function name="TRIM" language="en_US">
		<synopsis>
			Trim leading and trailing whitespace in a string
		</synopsis>
		<syntax>
			<parameter name="string" required="true" />
		</syntax>
		<description>
			<para>Replaces all leading and trailing whitespace in the provided string.</para>
		</description>
		<see-also>
			<ref type="function">LTRIM</ref>
			<ref type="function">RTRIM</ref>
		</see-also>
	</function>