Available Functions in Source Code Snippets

To make it easy for you to apply the same regex techniques in a variety of programming languages, RegexBuddy uses the same function descriptions for all languages it supports. Some functions are not available for all languages, depending on the functionality provided by the language or its regular expression library.

Import regex library: If the regular expression support is not a core part of the language, you need to reference the regex library in your code, before you can use any of the other code snippets.

Test if the regex matches (part of) a string: Tests if the regular expression can be matched anywhere in a subject string, and stores the result in a boolean variable.

Test if the regex matches a string entirely: Tests if the regular expression matches the subject string entirely, and stores the result in a boolean variable. This function is appropriate when validating user input or external data, since you typically want to validate everything you received. If the language does not have a separate function for testing if a string can be matched entirely, RegexBuddy places anchors around your regular expression to obtain the same effect.

If/else branch whether the regex matches (part of) a string: Tests if the regular expression can be matched anywhere in a subject string. Add code to the if section to take action if the match is successful. Add code to the else section to take action if the match fails.

If/else branch whether the regex matches a string entirely: Tests if the regex matches a subject string in its entirety, adding anchors to the regex if necessary.

Create an object with details about how the regex matches (part of) a string: Applies the regular expression to a subject string, and returns an object with detailed information about the part of the subject string that could be matched. The details usually include the text that was matched, the offset position in the string where the match started, and the number of characters in the match. If the regex contains capturing groups, the details also contain the same information for each of the capturing groups. The groups are numbered starting at one, with group number zero being the overall regex match. The Find First button on the Test panel performs the same task as this function.

Note that for regular expressions that consist only of anchors or lookaround, or where everything is optional, it is possible for a successful match to have a length of zero. Such regexes can also match at the point right after the end of the string, in which case the offset points to a non-existent character.

Get the part of a string matched by the regex: Applies the regular expression to a subject string, and returns the part of the subject string that could be matched. This function is appropriate if you are only interested in the first (or only) possible match in the subject string.

Get the part of a string matched by a numbered group: Applies the regular expression to a subject string, and returns the part of the subject string that was matched by a capturing group in the regex. This function is appropriate if you are only interested in a particular part of the first (or only) possible match in the subject string. One of the parameters for this function is the number of the capturing group. You can easily obtain this number from the regex tree on the Create panel.

Get the part of a string matched by a named group: Applies the regular expression to a subject string, and returns the part of the subject string that was matched by a named capturing group in the regex. This function is appropriate if you are only interested in a particular part of the first (or only) possible match in the subject string. One of the parameters for this function is the name of the capturing group.

Iterate over all matches in a string: Applies and re-applies a regular expression to a subject string, iterating over all matches in the subject, until no further matches can be found. Insert your own code inside the loop to process each match. Match details such as offset and length of the match, the matched text, the results from capturing groups, etc. are available inside the loop.

Iterate over all matches and capturing groups in a string: Iterates over all matches in the string like the previous function, and also iterates over all capturing groups of each match. Note that the number of available capturing groups may be different for each match. If certain capturing groups did not participate at all in the overall match, no details will be available for those groups. In practice, you will usually use the previous function, and only work with the capturing groups that you are specifically interested in. This function illustrates how you can access each group.

Validate input with a regular expression: Applies the regular expression to the text entered in a field on a form to validate the field before processing the form.

Replace Functions

These functions are available for languages that can use a regular expression to search-and-replace through a string. These functions only appear in the Function drop-down list when you're defining a replace action.

Replace all matches in a string: Executes a replace action. All regex matches in the subject string are substituted with the replacement text. References to capturing groups in the replacement text are expanded. Unless otherwise indicated in the function's name, the "replace all" function does not modify the original subject string. It returns a new string with the replacements applied.

Search and replace through a string: Executes a replace action using a callback function that returns the replacement text. You can edit this callback function to use procedural code to modify or build the replacement for each regex match.

Split Functions

These functions are available for languages that can use a regular expression to split a string. These functions only appear in the Function drop-down list when you're defining a split action.

Split a string: Executes a split action. Returns an array or list of strings from a given subject string. The first string in the array is the part of the subject before the first regex match. The second string is the part between the first and second matches, the third string the part between the second and third matches, etc. The final string is the remainder of the subject after the last regex match. The text actually matched by the regex is not added to the array.

Object-Oriented Functions

These functions are available for programming languages that use an object-oriented regular expression library.

Create an object to use the same regex for many operations: Before a regular expression can be applied to a subject string, the regex engine needs to convert the textual regex that you (or the user of your software) entered into a binary format that can be processed by the engine's pattern matcher. If you use any of the functions listed above, the regex is (re-)compiled each time you call one of the functions. That is inefficient if you use the same regex over and over. Therefore, you should create an object that stores the regular expression and its associated internal data for the regex engine. Your source code becomes easier to read and maintain if you create regex objects with descriptive names.

Create an object to apply a regex repeatedly to a given string: Some regex libraries, such as Java's java.util.regex package, use a separate pattern matcher object to apply a regex to a particular subject string, instead of using the regex object created by the function above. Explicitly creating and using this object, instead of using one of the convenience functions that create and discard it behind the scenes, makes repeatedly applying the same regex to the same string more efficient. This way you can find all regex matches in the string, rather than just the first one.

Apply the same regex to more than one string: Illustrates how to use the regex object to apply a given regular expression to more than one subject string.

Use regex object to ...: This series of functions creates and uses a regex object to perform its task. The results of these functions are identical to the results of the similarly named functions already described above. The advantage of these functions over the ones above, is that you can reuse the same regex object to use a given regular expression more than once. For the second and following invocations, you obviously only copy and paste the part of the code snippet that uses the regex object into your source code.

Database Functions

These functions are available for database languages (various flavors of SQL).

Select rows in which a column is/cannot (partially) matched by the regex: SQL code for selecting rows from a database checking for a regex match on a certain column. Only those rows where the column does/doesn't match the regex are returned.

Select rows in which a column is/cannot entirely matched by the regex: SQL code for selecting rows from a database checking for a regex match on a certain column. Anchors are added to the regex to require it to match the column's value entirely. Only those rows where the column does/doesn't match the regex are returned.

Select the part of a column matched by a regex: SQL code for selecting rows from a database checking for a regex match on a certain column. Returns only the part of the column that was matched by the regular expression, and only for those rows where the column matched at all.

Regex Tree Functions

Comment with RegexBuddy's regex tree: A series of comment lines with the regular expression "as is" (not converted to a string or operator) and the regex tree from the Create panel in RegexBuddy.

Comment inside a region with RegexBuddy's regex tree: A series of comment lines with the regular expression "as is" (not converted to a string or operator) and the regex tree from the Create panel in RegexBuddy. The comment lines are placed inside a region to make it easy to fold the whole comment in your development tool.

XML comment with RegexBuddy's regex tree: A series of comment lines with the regular expression "as is" (not converted to a string or operator) and the regex tree from the Create panel in RegexBuddy. The comment has added XML tags that allow it to be included in documentation that is automatically generated from your source code.

String literal with RegexBuddy's regex tree: For regex flavors that support the free-spacing regular expression syntax, RegexBuddy converts your regex to use free-spacing mode (if it doesn't already) and add the regex tree regex tree as comments to the regular expression. For regex flavors that do no support free-spacing, RegexBuddy splits the regex into a concatenation of strings, adding the regex tree as source code comments next to the string parts. Either way, the resulting string holds the actual regular expression, and can be passed to a class or function to actually match the regular expression to a subject string.

Replacement Tree Functions

Comment with RegexBuddy's replacement tree: A series of comment lines with the replacement text "as is" (not converted to a string or operator) and the replacement tree from the Create panel in RegexBuddy.

Comment inside a region with RegexBuddy's replacement tree: A series of comment lines with the replacement text "as is" (not converted to a string or operator) and the replacement tree from the Create panel in RegexBuddy. The comment lines are placed inside a region to make it easy to fold the whole comment in your development tool.

XML comment with RegexBuddy's replacement tree: A series of comment lines with the replacement text "as is" (not converted to a string or operator) and the replacement tree from the Create panel in RegexBuddy. The comment has added XML tags that allow it to be included in documentation that is automatically generated from your source code.

String literal with RegexBuddy's replacement tree: RegexBuddy splits the replacement into a concatenation of strings, adding the replacement tree as source code comments next to the string parts. The resulting string holds the actual replacement text, and can be passed to a class or function to actually replace regex matches.