1.1 Custom Notations

An advanced experimental feature. Use with caution.

Internal Mask compiler supports a series of symbols which represent letters and numbers in user input. Each symbol stands for its own character set.

For instance, 0 and 9 stand for a numeric character set. This means user can type any digit instead of 0 or 9. A and a represent letters, which means user can type any letter instead of A or a.

The difference between 0 and 9 is that 0 stands for a mandatory digit, while 9 represents an optional digit. With the mask like [099][A] user will be able to enter 1b, 12c or 123d, while with the mask [000][A] user won't be able to enter letters unless he has entered all three digits: 1 or 12 or 123 or 123e.

Summarizing, each symbol supported by the compiler has its own character set associated with it, and also has an option to be mandatory or not.

That said, you may configure your own symbols in addition to the default ones through the Notation objects:

Notation(character:characterSet:isOptional:)

Here, character is a symbol you put into square brackets, characterSet is a set of acceptable symbols for the user to enter, and isOptional speaks for itself.

Use the array of Notation when constructing a Mask object:

Mask(
    format: "[999][.][99]",
    customNotations: [
        Notation(
            character: ".", 
            characterSet: CharacterSet(charactersIn: ".,"), 
            isOptional: true
        ),
    ]
)

or

Mask.getOrCreate(
    withFormat: "[999][.][99]",
    customNotations: [
        Notation(
            character: ".", 
            characterSet: CharacterSet(charactersIn: ".,"), 
            isOptional: true
        ),
    ]
)

MaskedTextFieldDelegate and its children also contain a customNotations field. You may use the Interface Builder with custom formats, just don't forget to programmatically assign your custom notations:

class ViewController: UIViewController {
    @IBOutlet weak var listener: MaskedTextFieldDelegate!
    
    open override func viewDidLoad() {
        super.viewDidLoad()
        listener.customNotations = [
            Notation(
                character: ".", 
                characterSet: CharacterSet(charactersIn: ".,"), 
                isOptional: true
            ),
        ]
    }
}

Please note, that you won't have autocompletion for any of your custom symbols. For more examples, see below.

A floating point number with two decimal places

Mask: [999999999][.][99]

Custom notations:

Notation(character: ".", characterSet: CharacterSet(charactersIn: "."), isOptional: true)

Results

1
123
1234.
1234.5
1234.56

An email (please use regular expressions instead)

With optional and mandatory "dots" and "at" symbol.

Mask: [aaaaaaaaaa][d][aaaaaaaaaa][@][aaaaaaaaaa][d][aaaaaaaaaa][D][aaaaaaaaaa]

Custom notations:

Notation(
    character: "D",
    characterSet: CharacterSet(charactersIn: "."),
    isOptional: false
),
Notation(
    character: "d",
    characterSet: CharacterSet(charactersIn: "."),
    isOptional: true
),
Notation(
    character: "@",
    characterSet: CharacterSet(charactersIn: "@"),
    isOptional: false
)

Results

d
derh
derh.
derh.a
derh.asd
derh.asd@
derh.asd@h
derh.asd@hello.
derh.asd@hello.c
derh.asd@hello.com.
derh.asd@hello.com.u
derh.asd@hello.com.uk

An optional currency symbol

Mask: [s][9999]

Custom notations:

Notation(character: "s", characterSet: CharacterSet(charactersIn: "$€"), isOptional: true)

Results

12
$12
918
€918
1000
$1000