You are previewing Regular Expressions Cookbook, 2nd Edition.

Regular Expressions Cookbook, 2nd Edition

Cover of Regular Expressions Cookbook, 2nd Edition by Jan Goyvaerts... Published by O'Reilly Media, Inc.
  1. Regular Expressions Cookbook
  2. Preface
    1. Caught in the Snarls of Different Versions
    2. Intended Audience
    3. Technology Covered
    4. Organization of This Book
    5. Conventions Used in This Book
    6. Using Code Examples
    7. Safari® Books Online
    8. How to Contact Us
    9. Acknowledgments
  3. 1. Introduction to Regular Expressions
    1. Regular Expressions Defined
      1. Many Flavors of Regular Expressions
      2. Regex Flavors Covered by This Book
    2. Search and Replace with Regular Expressions
      1. Many Flavors of Replacement Text
    3. Tools for Working with Regular Expressions
      1. RegexBuddy
      2. RegexPal
      3. RegexMagic
      4. More Online Regex Testers
      5. More Desktop Regular Expression Testers
      6. grep
      7. Popular Text Editors
  4. 2. Basic Regular Expression Skills
    1. 2.1. Match Literal Text
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    2. 2.2. Match Nonprintable Characters
      1. Problem
      2. Solution
      3. Discussion
      4. Variations on Representations of Nonprinting Characters
      5. See Also
    3. 2.3. Match One of Many Characters
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. Flavor-Specific Features
      6. See Also
    4. 2.4. Match Any Character
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    5. 2.5. Match Something at the Start and/or the End of a Line
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    6. 2.6. Match Whole Words
      1. Problem
      2. Solution
      3. Discussion
      4. Word Characters
      5. See Also
    7. 2.7. Unicode Code Points, Categories, Blocks, and Scripts
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    8. 2.8. Match One of Several Alternatives
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    9. 2.9. Group and Capture Parts of the Match
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    10. 2.10. Match Previously Matched Text Again
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    11. 2.11. Capture and Name Parts of the Match
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    12. 2.12. Repeat Part of the Regex a Certain Number of Times
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    13. 2.13. Choose Minimal or Maximal Repetition
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    14. 2.14. Eliminate Needless Backtracking
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    15. 2.15. Prevent Runaway Repetition
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    16. 2.16. Test for a Match Without Adding It to the Overall Match
      1. Problem
      2. Solution
      3. Discussion
      4. Alternative to Lookbehind
      5. Solution Without Lookbehind
      6. See Also
    17. 2.17. Match One of Two Alternatives Based on a Condition
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    18. 2.18. Add Comments to a Regular Expression
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
    19. 2.19. Insert Literal Text into the Replacement Text
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    20. 2.20. Insert the Regex Match into the Replacement Text
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    21. 2.21. Insert Part of the Regex Match into the Replacement Text
      1. Problem
      2. Solution
      3. Discussion
      4. Solution Using Named Capture
      5. See Also
    22. 2.22. Insert Match Context into the Replacement Text
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
  5. 3. Programming with Regular Expressions
    1. Programming Languages and Regex Flavors
      1. Languages Covered in This Chapter
      2. More Programming Languages
    2. 3.1. Literal Regular Expressions in Source Code
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    3. 3.2. Import the Regular Expression Library
      1. Problem
      2. Solution
      3. Discussion
    4. 3.3. Create Regular Expression Objects
      1. Problem
      2. Solution
      3. Discussion
      4. Compiling a Regular Expression Down to CIL
      5. Discussion
      6. See Also
    5. 3.4. Set Regular Expression Options
      1. Problem
      2. Solution
      3. Discussion
      4. Additional Language-Specific Options
      5. See Also
    6. 3.5. Test If a Match Can Be Found Within a Subject String
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    7. 3.6. Test Whether a Regex Matches the Subject String Entirely
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    8. 3.7. Retrieve the Matched Text
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    9. 3.8. Determine the Position and Length of the Match
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    10. 3.9. Retrieve Part of the Matched Text
      1. Problem
      2. Solution
      3. Discussion
      4. Named Capture
      5. See Also
    11. 3.10. Retrieve a List of All Matches
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    12. 3.11. Iterate over All Matches
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    13. 3.12. Validate Matches in Procedural Code
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    14. 3.13. Find a Match Within Another Match
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    15. 3.14. Replace All Matches
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    16. 3.15. Replace Matches Reusing Parts of the Match
      1. Problem
      2. Solution
      3. Discussion
      4. Named Capture
      5. See Also
    17. 3.16. Replace Matches with Replacements Generated in Code
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    18. 3.17. Replace All Matches Within the Matches of Another Regex
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    19. 3.18. Replace All Matches Between the Matches of Another Regex
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    20. 3.19. Split a String
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    21. 3.20. Split a String, Keeping the Regex Matches
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    22. 3.21. Search Line by Line
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    23. Construct a Parser
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
  6. 4. Validation and Formatting
    1. 4.1. Validate Email Addresses
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    2. 4.2. Validate and Format North American Phone Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    3. 4.3. Validate International Phone Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    4. 4.4. Validate Traditional Date Formats
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    5. 4.5. Validate Traditional Date Formats, Excluding Invalid Dates
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    6. 4.6. Validate Traditional Time Formats
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    7. 4.7. Validate ISO 8601 Dates and Times
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    8. 4.8. Limit Input to Alphanumeric Characters
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    9. 4.9. Limit the Length of Text
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    10. 4.10. Limit the Number of Lines in Text
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    11. 4.11. Validate Affirmative Responses
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    12. 4.12. Validate Social Security Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    13. 4.13. Validate ISBNs
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    14. 4.14. Validate ZIP Codes
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    15. 4.15. Validate Canadian Postal Codes
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    16. 4.16. Validate U.K. Postcodes
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    17. 4.17. Find Addresses with Post Office Boxes
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    18. 4.18. Reformat Names From “FirstName LastName” to “LastName, FirstName”
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    19. 4.19. Validate Password Complexity
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    20. 4.20. Validate Credit Card Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. Extra Validation with the Luhn Algorithm
      5. See Also
    21. 4.21. European VAT Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
  7. 5. Words, Lines, and Special Characters
    1. 5.1. Find a Specific Word
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    2. 5.2. Find Any of Multiple Words
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    3. 5.3. Find Similar Words
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    4. 5.4. Find All Except a Specific Word
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    5. 5.5. Find Any Word Not Followed by a Specific Word
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    6. 5.6. Find Any Word Not Preceded by a Specific Word
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    7. 5.7. Find Words Near Each Other
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    8. 5.8. Find Repeated Words
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    9. 5.9. Remove Duplicate Lines
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    10. 5.10. Match Complete Lines That Contain a Word
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    11. 5.11. Match Complete Lines That Do Not Contain a Word
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    12. 5.12. Trim Leading and Trailing Whitespace
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    13. 5.13. Replace Repeated Whitespace with a Single Space
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    14. 5.14. Escape Regular Expression Metacharacters
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
  8. 6. Numbers
    1. 6.1. Integer Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    2. 6.2. Hexadecimal Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    3. 6.3. Binary Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    4. 6.4. Octal Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    5. 6.5. Decimal Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    6. 6.6. Strip Leading Zeros
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    7. 6.7. Numbers Within a Certain Range
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    8. 6.8. Hexadecimal Numbers Within a Certain Range
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    9. 6.9. Integer Numbers with Separators
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    10. 6.10. Floating-Point Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    11. 6.11. Numbers with Thousand Separators
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    12. 6.12. Add Thousand Separators to Numbers
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    13. 6.13. Roman Numerals
      1. Problem
      2. Solution
      3. Discussion
      4. Convert Roman Numerals to Decimal
      5. See Also
  9. 7. Source Code and Log Files
    1. Keywords
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    2. Identifiers
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    3. Numeric Constants
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    4. Operators
      1. Problem
      2. Solution
      3. Discussion
    5. Single-Line Comments
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    6. Multiline Comments
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    7. All Comments
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    8. Strings
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    9. Strings with Escapes
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    10. Regex Literals
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    11. Here Documents
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    12. Common Log Format
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    13. Combined Log Format
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    14. Broken Links Reported in Web Logs
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
  10. 8. URLs, Paths, and Internet Addresses
    1. 8.1. Validating URLs
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    2. 8.2. Finding URLs Within Full Text
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    3. 8.3. Finding Quoted URLs in Full Text
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    4. 8.4. Finding URLs with Parentheses in Full Text
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    5. 8.5. Turn URLs into Links
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    6. 8.6. Validating URNs
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    7. 8.7. Validating Generic URLs
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    8. 8.8. Extracting the Scheme from a URL
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    9. 8.9. Extracting the User from a URL
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    10. 8.10. Extracting the Host from a URL
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    11. 8.11. Extracting the Port from a URL
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    12. 8.12. Extracting the Path from a URL
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    13. 8.13. Extracting the Query from a URL
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    14. 8.14. Extracting the Fragment from a URL
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    15. 8.15. Validating Domain Names
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    16. 8.16. Matching IPv4 Addresses
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    17. 8.17. Matching IPv6 Addresses
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    18. 8.18. Validate Windows Paths
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    19. 8.19. Split Windows Paths into Their Parts
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    20. 8.20. Extract the Drive Letter from a Windows Path
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    21. 8.21. Extract the Server and Share from a UNC Path
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    22. 8.22. Extract the Folder from a Windows Path
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    23. 8.23. Extract the Filename from a Windows Path
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    24. 8.24. Extract the File Extension from a Windows Path
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    25. 8.25. Strip Invalid Characters from Filenames
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
  11. 9. Markup and Data Formats
    1. Processing Markup and Data Formats with Regular Expressions
      1. Basic Rules for Formats Covered in This Chapter
    2. 9.1. Find XML-Style Tags
      1. Problem
      2. Solution
      3. Discussion
      4. Skip Tricky (X)HTML and XML Sections
      5. See Also
    3. 9.2. Replace <b> Tags with <strong>
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    4. 9.3. Remove All XML-Style Tags Except <em> and <strong>
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    5. 9.4. Match XML Names
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    6. 9.5. Convert Plain Text to HTML by Adding <p> and <br> Tags
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    7. 9.6. Decode XML Entities
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    8. 9.7. Find a Specific Attribute in XML-Style Tags
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    9. 9.8. Add a cellspacing Attribute to <table> Tags That Do Not Already Include It
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    10. 9.9. Remove XML-Style Comments
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    11. 9.10. Find Words Within XML-Style Comments
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    12. 9.11. Change the Delimiter Used in CSV Files
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    13. 9.12. Extract CSV Fields from a Specific Column
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    14. 9.13. Match INI Section Headers
      1. Problem
      2. Solution
      3. Discussion
      4. Variations
      5. See Also
    15. 9.14. Match INI Section Blocks
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
    16. 9.15. Match INI Name-Value Pairs
      1. Problem
      2. Solution
      3. Discussion
      4. See Also
  12. Index
  13. About the Authors
  14. Colophon
  15. Copyright
O'Reilly logo

4.2. Validate and Format North American Phone Numbers

Problem

You want to determine whether a user entered a North American phone number, including the local area code, in a common format. These formats include 1234567890, 123-456-7890, 123.456.7890, 123 456 7890, (123) 456 7890, and all related combinations. If the phone number is valid, you want to convert it to your standard format, (123) 456-7890, so that your phone number records are consistent.

Solution

A regular expression can easily check whether a user entered something that looks like a valid phone number. By using capturing groups to remember each set of digits, the same regular expression can be used to replace the subject text with precisely the format you want.

Regular expression

^\(?([0-9]{3})\)?[-.]?([0-9]{3})[-.]?([0-9]{4})$
Regex options: None
Regex flavors: .NET, Java, JavaScript, PCRE, Perl, Python, Ruby

Replacement

($1)$2-$3
Replacement text flavors: .NET, Java, JavaScript, Perl, PHP
(\1)\2-\3
Replacement text flavors: Python, Ruby

C# example

Regex phoneRegex =
    new Regex(@"^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$");

if (phoneRegex.IsMatch(subjectString)) {
    string formattedPhoneNumber =
        phoneRegex.Replace(subjectString, "($1) $2-$3");
} else {
    // Invalid phone number
}

JavaScript example

var phoneRegex = /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/;

if (phoneRegex.test(subjectString)) {
    var formattedPhoneNumber =
        subjectString.replace(phoneRegex, "($1) $2-$3");
} else {
    // Invalid phone number
}

Other programming languages

If you need help converting the examples just listed to your programming language of choice, Recipe 3.6 shows how to implement the test of whether a regex matches the entire subject, and Recipe 3.15 has code listings for performing a replacement that reuses parts of a match (done here to reformat the phone number).

Discussion

This regular expression matches three groups of digits. The first group can optionally be enclosed with parentheses, and the first two groups can optionally be followed with a choice of three separators (a hyphen, dot, or space). The following layout breaks the regular expression into its individual parts, omitting the redundant groups of digits:

^        # Assert position at the beginning of the string.
\(       # Match a literal "("
  ?      #   between zero and one time.
(        # Capture the enclosed match to backreference 1:
  [0-9]  #   Match a digit
    {3}  #     exactly three times.
)        # End capturing group 1.
\)       # Match a literal ")"
  ?      #   between zero and one time.
[-. ]    # Match one hyphen, dot, or space
  ?      #   between zero and one time.
       # [Match the remaining digits and separator.]
$        # Assert position at the end of the string.

Let’s look at each of these parts more closely.

The ^ and $ at the beginning and end of the regular expression are a special kind of metacharacter called an anchor or assertion. Instead of matching text, assertions match a position within the text. Specifically, ^ matches at the beginning of the text, and $ at the end. This ensures that the phone number regex does not match within longer text, such as 123-456-78901.

As we’ve repeatedly seen, parentheses are special characters in regular expressions, but in this case we want to allow a user to enter parentheses and have our regex recognize them. This is a textbook example of where we need a backslash to escape a special character so the regular expression treats it as literal input. Thus, the \( and \) sequences that enclose the first group of digits match literal parenthesis characters. Both are followed by a question mark, which makes them optional. We’ll explain more about the question mark after discussing the other types of tokens in this regular expression.

The parentheses that appear without backslashes are capturing groups and are used to remember the values matched within them so that the matched text can be recalled later. In this case, backreferences to the captured values are used in the replacement text so we can easily reformat the phone number as needed.

Two other types of tokens used in this regular expression are character classes and quantifiers. Character classes allow you to match any one out of a set of characters. [0-9] is a character class that matches any digit. The regular expression flavors covered by this book all include the shorthand character class \d that also matches a digit, but in some flavors \d matches a digit from any language’s character set or script, which is not what we want here. See Recipe 2.3 for more information about \d.

[-.] is another character class, one that allows any one of three separators. It’s important that the hyphen appears first or last in this character class, because if it appeared between other characters, it would create a range, as with [0-9]. Another way to ensure that a hyphen inside a character class matches a literal version of itself is to escape it with a backslash. [.\-] is therefore equivalent. The represents a literal space character.

Finally, quantifiers allow you to repeatedly match a token or group. {3} is a quantifier that causes its preceding element to be matched exactly three times. The regular expression [0-9]{3} is therefore equivalent to [0-9][0-9][0-9], but is shorter and hopefully easier to read. A question mark (mentioned earlier) is a quantifier that causes its preceding element to match zero or one time. It could also be written as {0,1}. Any quantifier that allows something to match zero times effectively makes that element optional. Since a question mark is used after each separator, the phone number digits are allowed to run together.

Tip

Note that although this recipe claims to handle North American phone numbers, it’s actually designed to work with North American Numbering Plan (NANP) numbers. The NANP is the telephone numbering plan for the countries that share the country code “1.” This includes the United States and its territories, Canada, Bermuda, and 17 Caribbean nations. It excludes Mexico and the Central American nations.

Variations

Eliminate invalid phone numbers

So far, the regular expression matches any 10-digit number. If you want to limit matches to valid phone numbers according to the North American Numbering Plan, here are the basic rules:

  • Area codes start with a number 2–9, followed by 0–8, and then any third digit.

  • The second group of three digits, known as the central office or exchange code, starts with a number 2–9, followed by any two digits.

  • The final four digits, known as the station code, have no restrictions.

These rules can easily be implemented with a few character classes.

^\(?([2-9][0-8][0-9])\)?[-.]?([2-9][0-9]{2})[-.]?([0-9]{4})$
Regex options: None
Regex flavors: .NET, Java, JavaScript, PCRE, Perl, Python, Ruby

Beyond the basic rules just listed, there are a variety of reserved, unassigned, and restricted phone numbers. Unless you have very specific needs that require you to filter out as many phone numbers as possible, don’t go overboard trying to eliminate unused numbers. New area codes that fit the rules listed earlier are made available regularly, and even if a phone number is valid, that doesn’t necessarily mean it was issued or is in active use.

Find phone numbers in documents

Two simple changes allow the previous regular expressions to match phone numbers within longer text:

\(?\b([0-9]{3})\)?[-.]?([0-9]{3})[-.]?([0-9]{4})\b
Regex options: None
Regex flavors: .NET, Java, JavaScript, PCRE, Perl, Python, Ruby

Here, the ^ and $ assertions that bound the regular expression to the beginning and end of the text have been removed. In their place, word boundary tokens (\b) have been added to ensure that the matched text stands on its own and is not part of a longer number or word.

Similar to ^ and $, \b is an assertion that matches a position rather than any actual text. Specifically, \b matches the position between a word character and either a nonword character or the beginning or end of the text. Letters, numbers, and underscore are all considered word characters (see Recipe 2.6).

Note that the first word boundary token appears after the optional, opening parenthesis. This is important because there is no word boundary to be matched between two nonword characters, such as the opening parenthesis and a preceding space character. The first word boundary is relevant only when matching a number without parentheses, since the word boundary always matches between the opening parenthesis and the first digit of a phone number.

Allow a leading “1”

You can allow an optional, leading “1” for the country code (which covers the North American Numbering Plan region) via the addition shown in the following regex:

^(?:\+?1[-.]?)?\(?([0-9]{3})\)?[-.]?([0-9]{3})[-.]?([0-9]{4})$
Regex options: None
Regex flavors: .NET, Java, JavaScript, PCRE, Perl, Python, Ruby

In addition to the phone number formats shown previously, this regular expression will also match strings such as +1 (123) 456-7890 and 1-123-456-7890. It uses a noncapturing group, written as (?:). When a question mark follows an unescaped left parenthesis like this, it’s not a quantifier, but instead helps to identify the type of grouping. Standard capturing groups require the regular expression engine to keep track of backreferences, so it’s more efficient to use noncapturing groups whenever the text matched by a group does not need to be referenced later. Another reason to use a noncapturing group here is to allow you to keep using the same replacement string as in the previous examples. If we added a capturing group, we’d have to change $1 to $2 (and so on) in the replacement text shown earlier in this recipe.

The full addition to this version of the regex is (?:\+?1[-.]?)?. The “1” in this pattern is preceded by an optional plus sign, and optionally followed by one of three separators (hyphen, dot, or space). The entire, added noncapturing group is also optional, but since the “1” is required within the group, the preceding plus sign and separator are not allowed if there is no leading “1.”

Allow seven-digit phone numbers

To allow matching phone numbers that omit the local area code, enclose the first group of digits together with its surrounding parentheses and following separator in an optional, noncapturing group:

^(?:\(?([0-9]{3})\)?[-.]?)?([0-9]{3})[-.]?([0-9]{4})$
Regex options: None
Regex flavors: .NET, Java, JavaScript, PCRE, Perl, Python, Ruby

Since the area code is no longer required as part of the match, simply replacing any match with «($1)$2-$3» might now result in something like () 123-4567, with an empty set of parentheses. To work around this, add code outside the regex that checks whether group 1 matched any text, and adjust the replacement text accordingly.

See Also

Recipe 4.3 shows how to validate international phone numbers.

As noted previously, the North American Numbering Plan (NANP) is the telephone numbering plan for the United States and its territories, Canada, Bermuda, and 17 Caribbean nations. More information is available at http://www.nanpa.com.

Techniques used in the regular expressions and replacement text in this recipe are discussed in Chapter 2. Recipe 2.1 explains which special characters need to be escaped. Recipe 2.3 explains character classes. Recipe 2.5 explains anchors. Recipe 2.9 explains grouping. Recipe 2.12 explains repetition. Recipe 2.6 explains word boundaries. Recipe 2.21 explains how to insert text matched by capturing groups into the replacement text.

The best content for your career. Discover unlimited learning on demand for around $1/day.