Methods


initWithRegularExpressions:
Init method.
initWithRegularExpression:
Init method.
regularExpressions
Returns the formatter's list of regular expressions.
insertRegularExpression:atIndex:
Inserts a new regular expression.
addRegularExpression:
Adds a new regular expression.
removeRegularExpressionAtIndex:
Removes a regular expression.
replaceRegularExpressionAtIndex:withRegularExpression:
Replaces a regular expression.
allowsEmptyString
Returns whether empty strings are allowed as valid input.
setAllowsEmptyString:
Sets whether empty strings are allowed as valid input.
formatPattern
Returns the format pattern for the formatter.
setFormatPattern:
Sets the format pattern for the formatter.
validateString:matchedExpressionIndex:
Checks a string against the regular expression list.
objectForValidatedString:matchedExpressionIndex:
Formats a valid string into its final object value.
stringForObjectValue:
NSFormatter method for converting values to strings.
getObjectValue:forString:errorDescription:
NSFormatter method for validating input strings and converting them to final values.
lastMatchedExpression
Returns the last regular expression that matched an input string.

addRegularExpression:

Adds a new regular expression.
- ( void ) addRegularExpression:
        (MORegularExpression *) expression;

Adds a new regular expression to the end of the formatter's list of expressions.

Parameter Descriptions
expression
The new MORegularExpression to add.

allowsEmptyString

Returns whether empty strings are allowed as valid input.
- ( BOOL ) allowsEmptyString;

Returns whether empty strings are allowed as valid input.

method result
YES if the formatter allows empty strings, NO if not.

formatPattern

Returns the format pattern for the formatter.
- ( 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.

method result
The format pattern string.

getObjectValue:forString:errorDescription:

NSFormatter method for validating input strings and converting them to final values.
- ( 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.

Parameter Descriptions
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.
method result
YES if the string matches one of the formatter's regular expressions, NO if not. If YES, then obj will be filled in with a pointer to the resulting output string. If NO, then error will be filled in with a pointer to an error string.

initWithRegularExpression:

Init method.
- ( id ) initWithRegularExpression:
        (MORegularExpression *) expression;

Initializes the receiver with a single regular expressions.

Parameter Descriptions
expression
A MORegularExpression object.
method result
The initialized receiver or nil if an error occurred during initialization.

initWithRegularExpressions:

Init method.
- ( id ) initWithRegularExpressions:
        (NSArray *) expressions;

Designated Initializer. Initializes the receiver given an array of regular expressions.

Parameter Descriptions
expressions
An NSArray of MORegularExpressions.
method result
The initialized receiver or nil if an error occurred during initialization.

insertRegularExpression:atIndex:

Inserts a new regular expression.
- ( void ) insertRegularExpression:
        (MORegularExpression *) expression atIndex:
        (unsigned ) index;

Inserts a new regular expression into the formatter's list of expressions at the given index.

Parameter Descriptions
expression
The new MORegularExpression to insert.
index
The index where the new expression should be inserted.

lastMatchedExpression

Returns the last regular expression that matched an input string.
- ( 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.

method result
The last regular expression that matched an input string (or nil if the last input did not match any expression).

objectForValidatedString:matchedExpressionIndex:

Formats a valid string into its final object value.
- ( 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:.

Parameter Descriptions
string
The validated string.
matchedIndex
The index of the matched regular expression (or NSNotFound is the string is the empty string).
method result
The final object value for the given validated string.

regularExpressions

Returns the formatter's list of regular expressions.
- ( NSArray *) regularExpressions;

Returns the formatter's list of regular expressions.

method result
The list of regular expressions.

removeRegularExpressionAtIndex:

Removes a regular expression.
- ( void ) removeRegularExpressionAtIndex:
        (unsigned ) index;

Removes the regular expression at the given index from the formatter's list of expressions.

Parameter Descriptions
index
The index of the expression to remove.

replaceRegularExpressionAtIndex:withRegularExpression:

Replaces a regular expression.
- ( 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.

Parameter Descriptions
index
The index of the expression to be replaced.
expression
The new MORegularExpression to replace the old one with.

setAllowsEmptyString:

Sets whether empty strings are allowed as valid input.
- ( void ) setAllowsEmptyString:
        (BOOL ) flag;

Sets whether empty strings are allowed as valid input.

Parameter Descriptions
flag
YES if empty strings should be allowed, NO if not.

setFormatPattern:

Sets the format pattern for the formatter.
- ( 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.

Parameter Descriptions
pattern
The format pattern string.

stringForObjectValue:

NSFormatter method for converting values to strings.
- ( 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.

Parameter Descriptions
obj
The object to be converted to a string.
method result
The string.

validateString:matchedExpressionIndex:

Checks a string against the regular expression list.
- ( 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.

Parameter Descriptions
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.
method result
YES if the string matches one of the formatter's regular expressions, NO otherwise.

(Last Updated 3/20/2005)