Description

Class encapsulating data read from a machine-readable zone (MRZ)

This class encapsulates raw data read from an MRZ, and provides low-level parsing and checking facilities. It is intended for use with ICAO 9303 MRZs, but does not require compliance; the only real limitations on this class are that it only supports up to 3 lines, and up to maxLineSize characters per line.

While this class does provide basic detection of MRZ data formats (see GrabbaMRZ_Format for details), it does not provide guarantees of validity, field parsing support, or validation of check digits and field contents. Support for those operations is provided by the GrabbaMRZ_Validated class.

The raw text contained within an MRZ is set at construction, or via the line1, line2 and line3 properties. It may be read back via those same properties. All property values are passed by copy; a new copy of the value will be generated each time a property is read.

This class does not provide ICAO 9303 conformance as an invariant - that is, invalid or incomplete MRZ scans will still generate text, and whatever text is read by the reader will still be accessible via an object of this class.

Note: ICAO 9303 uses 1-based "numbers", unlike the 0-based indices of most programming languages. Accordingly, all references to line numbers or character numbers here will match those of ICAO 9303 and thus be 1-based - e.g. for a passport, the lines are numbered 1 and 2, and the characters in each line are numbered 1-44 inclusive. If extracting data from a line, it will be necessary to subtract one from each character number to obtain an 0-based string index.

Invariant: Size of each stored line will be less than or equal to maxLineSize.

Thread safety:

Concurrent accesses to distinct objects: safe
Concurrent accesses to same object: unsafe, unless all accesses are read-only (i.e. property reads)

Inheritance diagram for GrabbaMRZ_Data:

Instance Methods
(instancetype _Nullable)	- init
	Initialise an empty MRZ data object. More...

(instancetype _Nullable)	- initWithLine1:line2:line3:
	Initialise from MRZ text lines. More...

(instancetype _Nullable)	- initWithText:
	[DEPRECATED] Initialise with given raw MRZ text More...

Class Methods
(instancetype _Nullable)	+ data
	Allocate and initialise an empty MRZ data object. More...

(instancetype _Nullable)	+ dataWithLine1:line2:line3:
	Allocated and initialise from MRZ text lines. More...

(instancetype _Nullable)	+ dataWithText:
	[DEPRECATED] Allocate and initialise with given raw MRZ text More...

(short)	+ maxLineSize
	Maximum supported size of each line. More...

Properties
GrabbaMRZ_Format	format
	Format of the MRZ, if it can be determined. More...

NSString *_Nonnull	line1
	First line of text, if present. More...

NSString *_Nonnull	line2
	Second line of text, if present. More...

NSString *_Nonnull	line3
	Third line of text, if present. More...

NSString *_Nonnull	text
	[DEPRECATED] Text from a successful read of an MRZ More...

Method Documentation

◆ data()

+ (instancetype _Nullable) data

Allocate and initialise an empty MRZ data object.

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ dataWithLine1:line2:line3:()

+ (instancetype _Nullable) dataWithLine1:	(NSString *_Nonnull)	line1
line2:	(NSString *_Nonnull)	line2
line3:	(NSString *_Nonnull)	line3

Allocated and initialise from MRZ text lines.

For successful reads of compliant MRZs, the length of each line should be identical, and the data should match one of the formats defined in ICAO 9303 (e.g. the passport format, TD3, contains 2 lines of 44 characters apiece). However, construction with non-compliant MRZ text is permitted.

Parameters

line1	New value of line 1 text; will be truncated to maxLineSize if it exceeds that
line2	New value of line 2 text; will be truncated to maxLineSize if it exceeds that
line3	New value of line 3 text; will be truncated to maxLineSize if it exceeds that. For two-line MRZ formats, this should be set to an empty string.

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ dataWithText:()

+ (instancetype _Nullable) dataWithText: (NSString *_Nonnull) text

[DEPRECATED] Allocate and initialise with given raw MRZ text

This is a deprecated form of the data routine, provided solely for backward compatibility. Use the three-parameter variant instead.

Parameters

text	Initial value of the text property; empty string indicates no data

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ init()

- (instancetype _Nullable) init

Initialise an empty MRZ data object.

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ initWithLine1:line2:line3:()

- (instancetype _Nullable) initWithLine1:	(NSString *_Nonnull)	line1
line2:	(NSString *_Nonnull)	line2
line3:	(NSString *_Nonnull)	line3

Initialise from MRZ text lines.

For successful reads of compliant MRZs, the length of each line should be identical, and the data should match one of the formats defined in ICAO 9303 (e.g. the passport format, TD3, contains 2 lines of 44 characters apiece). However, initialisation with non-compliant MRZ text is permitted.

Parameters

line1	New value of line 1 text; will be truncated to maxLineSize if it exceeds that
line2	New value of line 2 text; will be truncated to maxLineSize if it exceeds that
line3	New value of line 3 text; will be truncated to maxLineSize if it exceeds that. For two-line MRZ formats, this should be set to an empty string.

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ initWithText:()

- (instancetype _Nullable) initWithText: (NSString *_Nonnull) text

[DEPRECATED] Initialise with given raw MRZ text

This is a deprecated form of the init routine, provided solely for backward compatibility. Use the three-parameter variant instead.

Parameters

text	Initial value of the text property; empty string indicates no data

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ maxLineSize()

+ (short) maxLineSize

Maximum supported size of each line.

Returns: The maximum length, which is a fixed value (200)

Property Documentation

◆ format

- (GrabbaMRZ_Format) format

readnonatomicassign

Format of the MRZ, if it can be determined.

Determination of this property's value requires the following checks:

Each line has the same length
Line count and length match those of one of the MRZ formats defined in ICAO 9303
First character of document type field matches one of the MRZ formats defined in ICAO 9303

If all of the checks pass, then the relevant format will be the property's value. If any of the checks fail, then the property will hold GrabbaMRZ_FormatUnknown.

Note: No validation of fields contained within each line is performed here. That is, if the first character matches one of the known formats, and the line count and lengths are consistent with that format, then that format's ID will be returned.

Returns: Matching format if there is one; GrabbaMRZ_FormatUnknown otherwise

◆ line1

- (NSString* _Nonnull) line1

readwritenonatomiccopy

First line of text, if present.

Asterisk characters ('*') will be used as placeholders for any characters which were not read clearly.

Length will range from 0 to maxLineSize inclusive; zero length indicates no lines were read.

◆ line2

- (NSString* _Nonnull) line2

readwritenonatomiccopy

Second line of text, if present.

Asterisk characters ('*') will be used as placeholders for any characters which were not read clearly.

Length will range from 0 to maxLineSize inclusive; zero length indicates that less than two lines were read.

◆ line3

- (NSString* _Nonnull) line3

readwritenonatomiccopy

Third line of text, if present.

Asterisk characters ('*') will be used as placeholders for any characters which were not read clearly.

Length will range from 0 to maxLineSize inclusive; zero length indicates that less than three lines were read.

◆ text

- (NSString* _Nonnull) text

readwritenonatomiccopy

[DEPRECATED] Text from a successful read of an MRZ

This property is deprecated, and provided solely for backward compatibility. Use the line1, line2 and line3 properties instead.

Passport or visa text is represented in the string as follows:

If line 1 present : <Line 1 Data><CR>
If line 2 present : <Line 2 Data><CR>
If line 3 present : <Line 3 Data><CR>

Description

Instance Methods

Class Methods

Properties

Method Documentation

◆ data()

◆ dataWithLine1:line2:line3:()

◆ dataWithText:()

◆ init()

◆ initWithLine1:line2:line3:()

◆ initWithText:()

◆ maxLineSize()

Property Documentation

◆ format

◆ line1

◆ line2

◆ line3

◆ text