Differences

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

--- syntax:functions:keepbefore [2015/04/03 18:27] – elenap
+++ syntax:functions:keepbefore [2021/08/14 22:09] (current) – [Examples] craigt
@@ Line 1: / Line 1: @@
-====== KeepBefore(text, string) ======
-Returns characters before the first occurrence of specific //string// in //text//. Parameter //string// must not be empty.
-This function is case-sensitive.
-^  Example  ^  Result  ^
+====== KeepBefore(text, before_string) ======
-|  KeepBefore( '5pm', 'pm' )  |  '5'  |
+Category:  Text function
-|  keepbefore('October 2015','2015')  |  'October '  |
-=== See also ===
+\\
-  * [[syntax:functions:keepafter]]
+=====Description=====
-  * [[syntax:functions:removestart]]
+This function returns characters before the first occurrence of //before_string// in //text//, if found.  If //before_string// is not found within //text// and "empty" value is returned.
+\\
+=====Alternative syntax=====
+This function can take an optional third numeric parameter to define the instance of //before_string// used in the search.  If //instance_num// is negative, the match starts from the end of //text//.
+  KeepBefore(text, before_string, instance_num)
+\\
+=====Arguments=====
+^Argument^Type^Description^
+|text|Text|The text value to search within for the //after_string// string.|
+|before_string|Text (must //not// be empty)|The text string to search for within //text//.  The characters before this string are returned.|
+|instance_num<sup>*</sup>|Number (non-zero integer)|The occurrence of //before_string// to use as the delimiter to return the text following.|
+<sup>*</sup>Optional argument.
+**Return value type:** Text
+\\
+=====Remarks=====
+This function is case sensitive.
+//text// and //before_string// are implicitly converted to text values if required.
+\\
+=====Examples=====
+  keepbefore('5pm', 'pm') //Returns '5'
+  keepbefore('October 2015', '2015') //Returns 'October '  (Note the space after 'October' is retained)
+  keepbefore('a/a/b/b/c/d', 'b/') //Returns 'a/a/'  (Second argument can be multiple characters)
+  keepbefore('a/b/c/d', '/', 2) //Returns 'a/b'  (Keep text before the second instance of '/')
+  keepbefore('a/b/c/d', '/', -1) //Returns 'a/b/c'  (Keep text before the second instance of '/', from the end)
+  keepbefore('a/b/c/d', 'z') //Returns (empty)  ('z' not found within the text value)
+\\
+===== See also =====
+  * [[syntax:functions:keepafter|KeepAfter(text, after_string)]]
+  * [[syntax:functions:removestart|RemoveStart(text, remove_num)]]