//
//  NSRegularExpression+MPParsingAdditions.h
//  MathKit
//
//  Created by Kim Wittenburg on 09.09.14.
//  Copyright (c) 2014 Kim Wittenburg. All rights reserved.
//


/*!
 @header
 This file contains the <code>NSRegularExpression(MPParsingAdditions)</code>
 category.
 */



/*!
    @category   NSRegularExpression (MPParsingAdditions)
    @abstract   This category adds convenience methods for typical calls to
                <code>firstMatchInString:options:range:</code>.
 */
@interface NSRegularExpression (MPParsingAdditions)

/*!
    @method     firstMathInString:
    @abstract   Returns the first match of the regular expression within the
                specified string.
 
    @discussion This is a convenience method that calls
                <code>firstMatchInString:options:range:</code>.
 
    @param      string
                The string to search.
 
    @return     An NSTextCheckingResult object. This result gives the overall
                matched range via its range property, and the range of each
                individual capture group via its rangeAtIndex: method. The range
                <code>{NSNotFound, 0}</code> is returned if one of the capture
                groups did not participate in this particular match.
 */
- (NSTextCheckingResult *)firstMatchInString:(NSString *)string;


/*!
    @method     firstMathInString:fromIndex
    @abstract   Returns the first match of the regular expression from the
                specified index in the string.
 
    @discussion This is a convenience method that calls
                <code>firstMatchInString:options:range:</code>.
 
    @param      string
                The string to search.
 
    @param      start
                The index from which to start searching.
 
    @return     An NSTextCheckingResult object. This result gives the overall
                matched range via its range property, and the range of each
                individual capture group via its rangeAtIndex: method. The range
                <code>{NSNotFound,</code> 0} is returned if one of the capture
                groups did not participate in this particular match.
 */
- (NSTextCheckingResult *)firstMatchInString:(NSString *)string fromIndex:(NSUInteger)start;


/*!
    @method     firstMathInString:options:
    @abstract   Returns the first match of the regular expression within the
                specified string.
 
    @discussion This is a convenience method that calls
                <code>firstMatchInString:options:range:</code>.
 
    @param      string
                The string to search.
 
    @param      options
                The matching options to use. See <code>NSMatchingOptions</code>
                for possible values.
 
    @return     An NSTextCheckingResult object. This result gives the overall
                matched range via its range property, and the range of each
                individual capture group via its rangeAtIndex: method. The range
                <code>{NSNotFound,</code> 0} is returned if one of the capture
                groups did not participate in this particular match.
 */
- (NSTextCheckingResult *)firstMatchInString:(NSString *)string options:(NSMatchingOptions)options;


/*!
    @method     firstMathInString:options:fromIndex
    @abstract   Returns the first match of the regular expression from the
                specified index in the string.
 
    @discussion This is a convenience method that calls
                <code>firstMatchInString:options:range:</code>.
 
    @param      string
                The string to search.
 
    @param      options
                The matching options to use. See <code>NSMatchingOptions</code>
                for possible values.

    @param      start
                The index from which to start searching.
 
    @return     An NSTextCheckingResult object. This result gives the overall
                matched range via its range property, and the range of each
                individual capture group via its rangeAtIndex: method. The range
                <code>{NSNotFound,</code> 0} is returned if one of the capture
                groups did not participate in this particular match.
 */
- (NSTextCheckingResult *)firstMatchInString:(NSString *)string options:(NSMatchingOptions)options fromIndex:(NSUInteger)start;

@end