• Introduction
• Getting Started
• Quick Examples
• Documentation
  • Macros
  • Creation
  • Test If Match
  • Index Of Match
  • Split
  • First Match
  • Matches
  • Replace
  • RxMatch Objects
• Support
• Licensing
• Testing
• Alternatives
• Who Uses It

As of iOS 4 (and OSX 10.7), NSRegularExpression is built-in to Foundation.framework. The syntax is somewhat cumbersome and it leaves much of the work to you, so this library creates categories and macros to simplify usage of NSRegularExpression.

Here is an example where four lines of code become one:

// Without this library
NSString* string = @"I have 2 dogs.";
NSRegularExpression *regex = [NSRegularExpression regular ExpressionWithPattern:@"\\d+" options:NSRegularExpressionCaseInsensitive error:&error];
NSTextCheckingResult *match = [regex firstMatchInString:string options:0 range:NSMakeRange(0, [string length])];
BOOL isMatch = match != nil;

// With this library
BOOL isMatch = [@"I have 2 dogs." isMatch:RX(@"\\d+")];

TIP: Refer to the header (RegExCategories.h) for more details and examples.

• RegExCategories.h
• RegExCategories.m

You may want to add it to your AppName-Prefix.pch so that is is available across your code base.

#ifdef __OBJC__
    /* ...other references... */
    #import "RegExCategories.h"
#endif

You also need to have ARC enabled on your XCode project. If you don't then add the -fobjc-arc flag on RegExCategories.m under Targets > Build Phases > Compile Sources (more info).

Here are some short examples of how you might use the code. The documentation section below goes into full detail.

//Create an NSRegularExpression
Rx* rx = RX(@"\\d");
Rx* rx = [Rx rx:@"\\d"];
Rx* rx = [Rx rx:@"\\d" ignoreCase:YES];

//Test if a string matches
BOOL isMatch = [@"2345" isMatch:RX(@"^\\d+$")];

//Get first match
NSString* age = [@"My dog is 3." firstMatch:RX(@"\\d+")];

//Get matches as a string array
NSArray* words = [@"Hey pal" matches:RX(@"\\w+")];
// words => @[ @"Hey", @"pal" ]

//Get first match with details
RxMatch* match = [@"12.34, 56.78" firstMatchWithDetails:RX(@"\\d+([.]\\d+)")];
// match.value => @"12.34"
// match.range => NSRangeMake(0, 5);
// match.original => @"12.34, 56.78";
// match.groups => @[ RxMatchGroup, RxMatchGroup ];

//Replace with a template string
NSString* result = [@"My dog is 12." replace:RX(@"\\d+") with:@"old"];
// result => @"My dog is old."

//Replace with a block
NSString* result = [RX(@"\\w+") replace:@"hi bud" withBlock:^(NSString* match){
  return [NSString stringWithFormat:@"%i", match.length];
}];
// result => @"2 3"

//Replace with a block that has the match details
NSString* result = [RX(@"\\w+") replace:@"hi bud" withDetailsBlock:^(RxMatch* match){
  return [NSString stringWithFormat:@"%i", match.value.length];
}];
// result => @"2 3"

//this
NSRegularExpression* rx = [[NSRegularExpression alloc] initWithPattern:@"\\d"];

//can be written as
Rx* rx = [[Rx alloc] initWithPattern:@"\\d"];

//this
NSRegularExpression* rx = [[NSRegularExpression alloc] initWithPattern:@"\\d"];

//can be written as
Rx* rx = RX(@"\\d");

#define DisableRegExCategoriesMacros
#include "RegExCategories.h"

Rx* rx = [Rx rx:@"\\d+"];

Rx* rx = [Rx rx:@"\\d+" ignoreCase:YES];

Rx* rx = [Rx rx:@"\\d+" options:NSRegularExpressionCaseInsensitive];

Rx* rx = [[Rx alloc] initWithPattern:@"\d+"];

Rx* rx = [@"\\d+" toRx];

Rx* rx = [@"\\d+" toRxIgnoreCase:YES];

Rx* rx = [@"\\d+" toRxWithOptions:NSRegularExpressionCaseInsensitive];

BOOL isMatch = [RX(@"\\d+") isMatch:@"Dog #1"];
// => true

BOOL isMatch = [@"Dog #1" isMatch:RX(@"\\d+")];
// => true

int index = [RX(@"\\d+") indexOf:@"Buy 1 dog or buy 2?"];
// => 4

int index = [RX(@"\\d+") indexOf:@"Buy a dog?"];
// => -1

int index = [@"Buy 1 dog or buy 2?" indexOf:RX(@"\\d+")];
// => 4

int index = [@"Buy a dog?" indexOf:RX(@"\\d+")];
// => -1

NSArray* pieces = [RX(@"[ ,]") split:@"A dog,cat"];
// => @[@"A", @"dog", @"cat"]

NSArray* pieces = [@"A dog,cat" split:RX(@"[ ,]")];
// => @[@"A", @"dog", @"cat"]

NSArray* pieces = [@",a,,b," split:RX(@"[,]")];
// => @[@"", @"a", @"", @"b", @""]

NSString* match = [@"55 or 99 spiders" firstMatch:RX(@"\\d+")];
// => @"55"

NSString* match = [@"A lot of spiders" firstMatch:RX(@"\\d+")];
// => nil

NSString* match = [RX(@"\\d+") firstMatch:@"55 or 99 spiders"];
// => @"55"

If you want more details about the match (such as the range or captured groups), then use match with details. It returns an RxMatch object if a match is found, otherwise nil.

RxMatch* match = [@"55 or 99 spiders" firstMatchWithDetails:RX(@"\\d+")];
// => { value: @"55", range:NSRangeMake(0, 2), groups:[RxMatchGroup, ...] }

RxMatch* match = [@"A lot of spiders" firstMatchWithDetails:RX(@"\\d+")];
// => nil

RxMatch* match = [RX(@"\\d+") firstMatchWithDetails:@"55 or 99 spiders"];
// => { value: @"55", range:NSRangeMake(0, 2), groups:[RxMatchGroup, ...] }

Matches returns all matches as an NSArray, each as an NSString. If no matches are found, the NSArray is empty.

NSArray* matches = [@"55 or 99 spiders" matches:RX(@"\\d+")];
// => @[ @"55", @"99" ]

NSArray* matches = [RX(@"\\d+") matches:@"55 or 99 spiders"];
// => @[ @"55", @"99" ]

Matches with details returns all matches as an NSArray, each object is an RxMatch object.

NSArray* matches = [@"55 or 99 spiders" matchesWithDetails:RX(@"\\d+")];
// => @[ RxMatch, RxMatch ]

NSArray* matches = [RX(@"\\d+") matchesWithDetails:@"55 or 99 spiders"];
// => @[ RxMatch, RxMatch ]

Replace allows you to replace matched substrings with a templated string.

NSString* result = [RX(@"ruf+") replace:@"ruf ruff!" with:@"meow"];
// => @"meow meow!"

Replace with block lets you pass an objective-c block that returns the replacement NSString. The block receives an NSString which is the matched substring.

NSString* result = [RX(@"[A-Z]+") replace:@"i love COW" withBlock:^(NSString*){ return @"lamp"; }];
// => @"i love lamp"

Similar to replace with block, but this block receives an RxMatch for each match. This gives you details about the match such as captured groups.

NSString* result = [RX(@"\\w+") replace:@"two three" withDetailsBlock:^(RxMatch* match){ 
    return [NSString stringWithFormat:@"%i", match.value.length];
  }];
// => @"3 5"

Replace can also be called from an NSString.

NSString* result = [@"ruf ruff!" replaceRX(@"ruf+") with:@"meow"];
// => @"meow meow!"

NSString* result = [@"i love COW" replace:RX(@"[A-Z]+") withBlock:^(NSString*){ return @"lamp"; }];
// => @"i love lamp"

NSString* result = [@"two three" replace:RX(@"\\w+") withDetailsBlock:^(RxMatch* match){ 
    return [NSString stringWithFormat:@"%i", match.value.length];
}];
// => @"3 5"

@interface RxMatch : NSObject

	/* The substring that matched the expression. */
	@property (retain) NSString* value;    

	/* The range of the original string that was matched. */
	@property (assign) NSRange   range;    

	/* Each object is an RxMatchGroup. */
	@property (retain) NSArray*  groups;   

	/* The full original string that was matched against.  */
	@property (retain) NSString* original; 

@end

@interface RxMatchGroup : NSObject

   /* The substring matched for the group. */
	@property (retain) NSString* value;
	
   /* The range of the captured group, relative to the original string. */
	@property (assign) NSRange range;
		
@end

If you need help, submit an issue or send a pull request. Please include appropriate unit tests in any pull requests.

You can visit my website at joshwright.com or tweet at me @BendyTree.

MIT License - do whatever you want, just (1) provide attribution and (2) don't hold me liable.

This repository includes unit tests written in the XCTest framework.

• Raw NSRegularExpression - Built in to Foundation since OSX 10.7 and iOS 4.0.
• RegexKitLite - Bridge between NSString and ICU Regex
• CocoaRegex - Alternative bridge to ICU

Here is a list of projects using Objective-C RegEx Categories. If you're using it, tweet at me (@BendyTree) and I'll add you to the list:

• Memorize Anything
• SpeakY
• Oyster 1.2