NSStringMask

This tiny library was developed to help you apply masks and formats to strings.

For instance, suppose you have the string 12345678 and want to format it as a Social Security Number (which regex pattern is \d{3}-\d{2}-\d{3}). With NSStringMask, all you have to do is [NSStringMask maskString:@"12345678" withPattern:@"(\\d{3})-(\\d{2})-(\\d{3})"] and the result will be "123-45-678". Simple enough?

Installation

You can clone the repository and copy the folder Classes to your project or install it via cocoa pods.

pod "NSStringMask"

References

Take a look on the complete documentation >.

Please, note that this is still in development and may be unstable. Suggestions and improvements are always welcome, specially with tests that are not my greatest skill.

I'll try to keep the branch master with the most stable updates, even before deploying new features.

I've also created this gist with some commonly used patterns. Feel free to improve it!

Usage Example

Whenever you set a string pattern or a regex, it must have at least one capturing parentheses [group]. This is because the class comprehends that everything that is in between parentheses are the strings that must be matched and replaced. If you need explicit parentheses in your format, escape it with slashes:

[NSStringMask maskString:@"c" withPattern:@"\\w"]
// result: nil

[NSStringMask maskString:@"c" withPattern:@"(\\w)"]
// result: "c"

[NSStringMask maskString:@"3" withPattern:@"\\((\\d)\\)"]
// result: (3)

[NSStringMask maskString:@"3" withPattern:@"\\((\\d{4})\\)" placeholder:@"_"]
// result: (3___)

These are few of the many forms to use NSStringMask:

Simple Pattern

In this case, the method will return the expected result only if the provided string's length is equal or longer than expected:

[NSStringMask maskString:@"1234567890" withPattern:@"(\\d{3})-(\\d{3})-(\\d{4})"]
// result: 123-456-7890

If the string is shorter, the method won't apply the format, but instead, return a cleaned string with the valid characters:

[NSStringMask maskString:@"123foo456" withPattern:@"(\\d{3})#(\\d{4})]
// result: 123456

Pattern with Placeholder:

Placeholders allow you to fill strings shorter than expected with characters to complete the formatting:

[NSStringMask maskString:@"" withPattern:@"(\\d{2})/(\\d{2})/(\\d{4})" placeholder:@"_"]
// result: __/__/____

It can also be a long string. In this case, the replacement will restart for each group in your pattern:

[NSStringMask maskString:@"" withPattern:@"(\\d{2})/(\\d{2})/(\\d{4})" placeholder:@"abcde"]
// result: ab/ab/abcd

NSRegularExpression

You may also provide an instance of NSRegularExpression instead of a pattern, the result is the same.

When a pattern is passed, the class creates a NSRegularExpression object with 0 option. If you need it to be different, it may be interesting to provide the regex and not a string pattern.

UITextFieldMask

To create a text field with a mask, just set it as an instance UITextFieldMask in your class or nib (if using the Interface Builder). It’s recommended that the mask is passed in the initialization of the text field, so if the text field is in a nib, the mask must be passed inside [UIViewController viewDidLoad] or [UIView awakeFromNib].

Help Wanted

Do you love NSStringMask and work actively on apps that use it? We'd love if you could help us keep improving it! Feel free to message us or to start contributing right away!

Complete Documentation >

License

NSStringMask is available under the MIT license. See the LICENSE file for more info.