ph_regexsnap1

Argument	Description
pattern	String. A regular expression search pattern containing tagged regions of (up to 9) that you want snapped out and returned.
snap	String. A regular expression snap pattern containing the snapped regions of text along with other desired text.
data	String. The string in which to perform the search and snap.
start	Long. The starting postion of the search. Use 1 to start at the beginning.
occurrence	Integer. The matching occurrence number to be returned. Use 1 to return the first matching occurrence. A 3 will return the third matching occurrence, etc.
flags	Integer. Flags that control how the search is performed. Add individual flag values together. Add 1 to cause the search to match case. Add 2 to cause the search to ignore cr/lf's within the data.
localstart	Integer. The index of a local variable in which to have the start of the found data returned. Use 0 to not have the start returned.
locallength	Integer. The index of a local variable in which to have the length of the found data returned. Use 0 to not have the length returned.

Use this function for powerful text search capabilities. The regular expression special characters supported are:

.	Matches any character.
\(	This marks the start of a region for tagging a match.
\)	This marks the end of a tagged region.
\<	This matches the start of a word.
\>	This matches the end of a word.
\x	This allows you to use a character x that would otherwise have a special meaning. For example, \[ would be interpreted as [ and not as the start of a character set.
[...]	This indicates a set of characters, for example, [abc] means any of the characters a, b or c. You can also use ranges, for example [a-z] for any lower case character.
[^...]	The complement of the characters in the set. For example, [^A-Za-z] means any character except an alphabetic character.
^	This matches the start of a line (unless used inside a set, see above).
$	This matches the end of a line.
*	This matches 0 or more times. For example, Sa*m matches Sm, Sam, Saam, Saaam and so on.
+	This matches 1 or more times. For example, Sa+m matches Sam, Saam, Saaam and so on.
\1 - \9	Use this only within the snap parameter. These tags represent the up to 9 snapped regions.

An important note on this function is that it is a "greedy" regular expression search. When using the * and + special characters this function will not stop at the first match but will instead go to the last match.

This function will also not perform a regular expression search that spans multiple lines. If the data to search contains carraige returns or line feeds, the entire matching search data for the regular expression must exist within a single line. If your regular expression must span across a line, then add 2 to the flags to have CR's and LF's temporarily converted. CR will be converted to ASCII 128 and LF will be converted to ASCII 129. If you convert CF/LF then you can include them in your search with PowerHome escape characters ~128 and ~129 respectively.

You may perform multiple searchs within your search pattern by separating your searchs with the PowerHome escape character ~255. Only the last search will be used for "snapping" data for return.

This function is similar to the ph_regexdiff function in that it uses regular expressions to search and return data within the searched string. Instead of returning data between two regular expressions (like ph_regexdiff), this function uses the $ and $ to mark tagged regions. You may have up to 9 tagged regions in the last search pattern. All matched text within the tagged regions will be "snapped out" and formatted according to the snap parameter and then returned by this function.