https://github.com/fjcaetano/nsstringmask
NSStringMask allows you to apply masks or formats to NSStrings using NSRegularExpression to input your format.
https://github.com/fjcaetano/nsstringmask
ios mask nsregularexpression objective-c regex swift
Last synced: 4 months ago
JSON representation
NSStringMask allows you to apply masks or formats to NSStrings using NSRegularExpression to input your format.
- Host: GitHub
- URL: https://github.com/fjcaetano/nsstringmask
- Owner: fjcaetano
- License: mit
- Created: 2013-04-26T21:54:59.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2018-12-13T18:54:12.000Z (almost 7 years ago)
- Last Synced: 2025-04-09T20:09:51.393Z (6 months ago)
- Topics: ios, mask, nsregularexpression, objective-c, regex, swift
- Language: Objective-C
- Homepage: http://fjcaetano.github.io/NSStringMask/
- Size: 739 KB
- Stars: 241
- Watchers: 6
- Forks: 36
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# NSStringMask
[](https://travis-ci.org/fjcaetano/NSStringMask)
[](http://cocoapods.org/pods/NSStringMask)
[](http://cocoapods.org/pods/NSStringMask)
[](http://cocoapods.org/pods/NSStringMask)
[](https://codecov.io/gh/fjcaetano/NSStringMask)
[](https://github.com/Carthage/Carthage)
---
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.
```ruby
pod "NSStringMask"
```
## References
Take a look on the [complete documentation >](http://cocoadocs.org/docsets/NSStringMask/).
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](https://gist.github.com/fjcaetano/5600452) 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:
```objective-c
[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:
```objective-c
[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:
```objective-c
[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:
```objective-c
[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:
```objective-c
[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 >](http://cocoadocs.org/docsets/NSStringMask/)
## License
NSStringMask is available under the MIT license. See the LICENSE file for more info.