Create a new Address instance and parse a physical address.
This function parses a physical address written in a free-form string.
It returns an object with a number of properties from the list below
that it may have extracted from that address.
The following is a list of properties that the algorithm will return:
- streetAddress: The street address, including house numbers and all.
- locality: The locality of this address (usually a city or town).
- region: The region where the locality is located. In the US, this
corresponds to states. In other countries, this may be provinces,
cantons, prefectures, etc. In some smaller countries, there are no
such divisions.
- postalCode: Country-specific code for expediting mail. In the US,
this is the zip code.
- country: The country of the address.
- countryCode: The ISO 3166 2-letter region code for the destination
country in this address.
The above properties will not necessarily appear in the instance. For
any individual property, if the free-form address does not contain
that property or it cannot be parsed out, the it is left out.
The options parameter may contain any of the following properties:
- locale - locale or localeSpec to use to parse the address. If not
specified, this function will use the current ilib locale
- onLoad - a callback function to call when the address info for the
locale is fully loaded and the address has been parsed. When the onLoad
option is given, the address object
will attempt to load any missing locale data using the ilib loader callback.
When the constructor is done (even if the data is already preassembled), the
onLoad function is called with the current instance as a parameter, so this
callback can be used with preassembled or dynamic loading or a mix of the two.
- sync - tell whether to load any missing locale data synchronously or
asynchronously. If this option is given as "false", then the "onLoad"
callback must be given, as the instance returned from this constructor will
not be usable for a while.
- loadParams - an object containing parameters to pass to the
loader callback function when locale data is missing. The parameters are not
interpretted or modified in any way. They are simply passed along. The object
may contain any property/value pairs as long as the calling code is in
agreement with the loader callback function as to what those parameters mean.
When an address cannot be parsed properly, the entire address will be placed
into the streetAddress property.
When the freeformAddress is another Address, this will act like a copy
constructor.