A formatter that uses MORegularExpression objects to validate input.
A MORegexFormatter has a list of MORegularExpressions that it uses to validate input. If a candidate string matches one of the expressions, it is valid. In addition to the list of expressions the formatter can be set to specifically allow or disallow the empty string.
For formatting output MORegexFormatter allows a format pattern that can reference subexpression matches in the regular expression(s) to provide a normalized version of any conforming input.
addRegularExpression: |
- ( void ) addRegularExpression: (MORegularExpression *) expression;
Adds a new regular expression to the end of the formatter's list of expressions.
- expression
- The new MORegularExpression to add.
allowsEmptyString |
- ( BOOL ) allowsEmptyString;
Returns whether empty strings are allowed as valid input.
formatPattern |
- ( NSString *) formatPattern;
Returns the format pattern for the formatter. The format pattern is used to format the output text from the formatter. See the -setFormatPattern: documentation for details about the syntax of the pattern.
getObjectValue:forString:errorDescription: |
- ( BOOL ) getObjectValue: (id *) obj forString: (NSString *) string errorDescription: (NSString **) error;
NSFormatter method for validating input strings and converting them to final values. MORegexFormatter implements this to test the candidate string against its list of regular expressions. If it matches one of them, the string is valid. In this case, the formatPattern of the formatter is used to create an output string.
- obj
- A pointer to the output string, formatted according to the formatPattern.
- string
- The input string to be validated and converted.
- error
- A pointer to a pointer to an error string describing why the string was not valid.
initWithRegularExpression: |
- ( id ) initWithRegularExpression: (MORegularExpression *) expression;
Initializes the receiver with a single regular expressions.
- expression
- A MORegularExpression object.
initWithRegularExpressions: |
- ( id ) initWithRegularExpressions: (NSArray *) expressions;
Designated Initializer. Initializes the receiver given an array of regular expressions.
- expressions
- An NSArray of MORegularExpressions.
insertRegularExpression:atIndex: |
- ( void ) insertRegularExpression: (MORegularExpression *) expression atIndex: (unsigned ) index;
Inserts a new regular expression into the formatter's list of expressions at the given index.
- expression
- The new MORegularExpression to insert.
- index
- The index where the new expression should be inserted.
lastMatchedExpression |
- ( MORegularExpression *) lastMatchedExpression;
Returns the last regular expression that matched an input string (or nil if the last input did not match any expression). This can be useful to retrieve the expression so subexpressions can be extracted or further matching can be done based on which regular expression the input matched. A subclass might use this to be able to reason about how to go on to convert the input value to a value of a different class.
objectForValidatedString:matchedExpressionIndex: |
- ( id ) objectForValidatedString: (NSString *) string matchedExpressionIndex: (unsigned ) matchedIndex;
This method is automatically invoked by the -getObjectValue:forString:errorDescription: method. You should not need to call it directly, but subclasses can override it. If the string is empty and valid, the matchedIndex parameter will be NSNotFound. This method is responsible for formatting or converting a valid string into its final form object value. MORegexFormatter implements this by using the -formatPattern to construct a final string value. A subclass might override this to, for example, convert a conforming phone number into an instance of a PhoneNumber class. Overriding this method to do final conversion is easier than fully overriding -getObjectValue:forString:errorDescription:.
- string
- The validated string.
- matchedIndex
- The index of the matched regular expression (or NSNotFound is the string is the empty string).
regularExpressions |
- ( NSArray *) regularExpressions;
Returns the formatter's list of regular expressions.
removeRegularExpressionAtIndex: |
- ( void ) removeRegularExpressionAtIndex: (unsigned ) index;
Removes the regular expression at the given index from the formatter's list of expressions.
- index
- The index of the expression to remove.
replaceRegularExpressionAtIndex:withRegularExpression: |
- ( void ) replaceRegularExpressionAtIndex: (unsigned ) index withRegularExpression: (MORegularExpression *) expression;
Replaces a regular expression in the formatter's list of expressions at the given index with a new regular expression.
- index
- The index of the expression to be replaced.
- expression
- The new MORegularExpression to replace the old one with.
setAllowsEmptyString: |
- ( void ) setAllowsEmptyString: (BOOL ) flag;
Sets whether empty strings are allowed as valid input.
- flag
- YES if empty strings should be allowed, NO if not.
setFormatPattern: |
- ( void ) setFormatPattern: (NSString *) pattern;
Sets the format pattern for the formatter. The format pattern is used to format the output text from the formatter. It allows the formatter to normalize the format of input values. The string can use "%#" where "#" is a subexpression index. For example, if you have a telephone number formatter which matches with subexpressions for area code, prefix and number, you can reformat entered phone numbers to a standard format with something like "(%1) %2-%3". If the formatter has multiple expressions, they all need to have the same subexpressions. The default format pattern is "%0" which just means the whole matched string.
- pattern
- The format pattern string.
stringForObjectValue: |
- ( NSString *) stringForObjectValue: (id ) obj;
NSFormatter method for converting values to strings. MORegexFormatter implements this simply to return the -description of the value. In general, MORegexFormatter is used to validate strings not to convert them into other types.
- obj
- The object to be converted to a string.
validateString:matchedExpressionIndex: |
- ( BOOL ) validateString: (NSString *) string matchedExpressionIndex: (unsigned *) matchedIndex;
This method is automatically invoked by the -getObjectValue:forString:errorDescription: method. You should not need to call it directly, but subclasses can override it. This method should take the -allowsEmptyString setting into account. This method is responsible for validating input strings and for identifying which regular expression of the formatter matched the string if it is valid. MORegexFormatter implements this to check for empty string, and if the string is empty, check whether it is valid or not using the -allowsEmptyString setting (if the string is empty and valid, the matchedIndex is set to NSNotFound). If the string is not empty, it is checked against the formatters regular expressions until a match is found or all the expressions are tested.
- string
- The candidate string.
- matchedIndex
- A pointer to an unsigned int that will be set to the index of the matched regular expression if the return value is YES.
(Last Updated 3/20/2005)