Differences

This shows you the differences between two versions of the page.

--- syntax:functions:keepchars [2016/06/20 11:38] – dmitry
+++ syntax:functions:keepchars [2021/08/14 22:13] (current) – [Examples] craigt
@@ Line 1: / Line 1: @@
-===== KeepChars(text, string) =====
+====== KeepChars(text, keep_string) ======
+Category:  Text function
-Keeps only particular characters in //text//, and removes the others.
+\\
+=====Description=====
+This function keeps only the characters given in //keep_string// and removes the others from //text//.
-^  Example  ^  Result  ^
+\\
-| keepchars('a1b2c3', 'abc')  | abc  |
+=====Arguments=====
+^Argument^Type^Description^
+|text|Text|The text value to search within for the //after_string// string.|
+|keep_string|Text (must //not// be empty)|A string of individual characters within //text// to keep, removing all other characters.|
+**Return value type:** Text
-=== See also ===
+\\
-  * [[syntax:functions:removechars]]
+=====Remarks=====
-  * [[syntax:functions:removetext]]
+This function is case sensitive.
+//text// and //keep_string// are implicitly converted to text values if required.
+The retained characters appear in the result in the order they appear in //text//.
+If none of the characters in //keep_string// are found, an (empty) value is returned.
+\\
+=====Examples=====
+  keepchars('a1b2c3', 'abc') //Returns 'abc'
+  keepchars('a1b2c3', 'cba') //Returns 'abc'
+  keepchars('3b2d1', '123') //Returns '321'
+  keepchars('Canada', 'acx') //Returns 'aaa'  ('C' not kept due to case mismatch; no 'x' in 'Canada')
+  keepchars('Canada', 'Ca') //Returns 'Caaa'
+  keepchars('Canada', 'zxw') //Returns (empty)  ('z', 'x', nor 'w' are found in 'Canada')
+\\
+===== See also =====
+  * [[syntax:functions:removechars|RemoveChars(text, remove_string)]]
+  * [[syntax:functions:removetext|RemoveText(text, remove_string)]]