MRZ_Data Class Reference

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 MRZ_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 ValidatedMRZ class.

The raw text contained within an MRZ is set at construction, or via the setText() method. It may be read back by the line1(), line2() and line3() methods. Note that this class does not provide ICAO 9303 conformance as an invariant - that is, invalid or incomplete MRZ scans will still generate text and that will still be returned.

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)

Public Member Functions
	MRZ_Data ()
	Construct with empty MRZ contents and unknown type ID.
	MRZ_Data (@NonNull String initText)
	[DEPRECATED] Construction - sets stored text More...
	MRZ_Data (@NonNull String initLine1, @NonNull String initLine2, @NonNull String initLine3)
	Construct from MRZ text lines. More...
MRZ_Format	format ()
	Query the format of the MRZ. More...
String	line1 ()
	Read the first line of text, if present. More...
String	line2 ()
	Read the second line of text, if present. More...
String	line3 ()
	Read the third line of text, if present. More...
void	setLine1 (@NonNull String newLine)
	Set the first line of the MRZ data. More...
void	setLine2 (@NonNull String newLine)
	Set the second line of the MRZ data. More...
void	setLine3 (@NonNull String newLine)
	Set the third line of the MRZ data. More...
void	setText (@NonNull String newText)
	[DEPRECATED] Set the stored text More...
void	setText (@NonNull String newLine1, @NonNull String newLine2, @NonNull String newLine3)
	Set the MRZ text as per given line data. More...
String	text ()
	[DEPRECATED] Text from a successful read of an MRZ More...

Static Public Attributes
static final short	MaxLineSize
	Maximum supported size of each line.

Constructor & Destructor Documentation

MRZ_Data() [1/2]

MRZ_Data

(

@NonNull String

initText

)

[DEPRECATED] Construction - sets stored text

This is an older form of the constructor for this class, provided solely for backward compatibility purposes. Use the three-parameter constructor instead.

Parameters

initText

Initial value of the stored text; see text() for details of the format

MRZ_Data() [2/2]

MRZ_Data	(	@NonNull String	initLine1,
		@NonNull String	initLine2,
		@NonNull String	initLine3
	)

Construct 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

initLine1	New value of line 1 text; will be truncated to MaxLineSize if it exceeds that
initLine2	New value of line 2 text; will be truncated to MaxLineSize if it exceeds that
initLine3	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.

Member Function Documentation

format()

MRZ_Format format

(

)

Query the format of the MRZ.

This performs 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 is returned. If any of the checks fail, then UNKNOWN will be returned.

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; UNKNOWN otherwise

line1()

String line1

(

)

Read the first line of text, if present.

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

Returns

First line of text, length 0 to MaxLineSize inclusive. Zero length indicates no lines were read.

line2()

String line2

(

)

Read the second line of text, if present.

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

Returns

Second line of text, length 0 to MaxLineSize inclusive. Zero length indicates less than two lines were read.

line3()

String line3

(

)

Read the third line of text, if present.

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

Returns

Third line of text, length 0 to MaxLineSize inclusive. Zero length indicates less than three lines were read.

setLine1()

void setLine1

(

@NonNull String

newLine

)

Set the first line of the MRZ data.

Parameters

newLine

New value of the line's text; will be truncated to MaxLineSize if it exceeds that

setLine2()

void setLine2

(

@NonNull String

newLine

)

Set the second line of the MRZ data.

Parameters

newLine

New value of the line's text; will be truncated to MaxLineSize if it exceeds that

setLine3()

void setLine3

(

@NonNull String

newLine

)

Set the third line of the MRZ data.

Parameters

newLine

New value of the line's text; will be truncated to MaxLineSize if it exceeds that. For two-line MRZ formats, this should be set to an empty string.

setText() [1/2]

void setText

(

@NonNull String

newText

)

[DEPRECATED] Set the stored text

This is a deprecated form of the set-text method, provided solely for backward compatibility. Use the three-parameter form of this function instead.

Parameters

newText

New value of the stored text; see text() for details of the format

setText() [2/2]

void setText	(	@NonNull String	newLine1,
		@NonNull String	newLine2,
		@NonNull String	newLine3
	)

Set the MRZ text as per given line data.

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, setting of non-compliant MRZ text is permitted.

Parameters

newLine1	New value of line 1 text; will be truncated to MaxLineSize if it exceeds that
newLine2	New value of line 2 text; will be truncated to MaxLineSize if it exceeds that
newLine3	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.

text()

String text

(

)

[DEPRECATED] Text from a successful read of an MRZ

This is an older form of the text-access method, provided solely for backward compatibility purposes. Use the line1(), line2() and line3() methods instead.

Returns

Passport or visa data, 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>