The Keyliner class Library "cl801_CityState" will parse any City-State-Zip field and return its constituent parts. This post describes the public methods and is meant for reference
See this article for a complete description of the class library, with download instructions
Keyliner: City-State-Zip DLL - Reliably Parse CSZ Fields
Example Standard City-State-Zip:
Salt Lake City UTAH 84101 1234
Returned Constituent parts:
City: Salt Lake City
State: UT
ZipCode: 84101-1234
Zip5: 84101
Zip4: 1234
or Return a fully-assembled and re-punctuated CSZ:
Salt Lake City, UT 84101-1234
For documentation, these are the public methods in the class library.
Class Library (DLL) "cl801_CityState"
Public Methods
About
public string ns801CityState_About()
---------------------------------------------------------------------------------------------------------------
Returns a string pointing to this article.
ReturnFormattedCityStateZip
public string ReturnFormattedCityStateZip (string strpassedString)
---------------------------------------------------------------------------------------------------------------
This returns a fully formed CSZ string, such as "Boise, ID 83700-1234", punctuated and supertrimmed.
Pass any CSZ field, formatted in any fashion, to this method
Returned is a single string: "City, State-Code Zip5-Zip4"
States are resolved to USPostal two-character State-Codes, when possible
Properly punctuated, fully assembled, in the same upper-lower-case (case) as sent
Military, Canadian, and US Territory codes are supported
For example:
"Boise, Idaho 83700 - 1234" -- returns "Boise, ID 83700-1234"
"Boise ID 83700" -- returns "Boise, ID 83700"
"Miles City 83700" -- returns "Miles City 83700" (note no comma)
",Utah 83700" -- returns "*, UT 83700" (note the asterisk)
Do not use this method if you want to individual fields returned; Instead, call the individual field methods, below.
This
method is relatively inefficient because it calls each of the field
routines below, and then re-assembles the results, making numerous calls
the same parsing routines.
ReturnStateName
public string ReturnStateName (string strpassedString)
---------------------------------------------------------------------------------------------------------------
This
returns the State-Code (State Name), Province, or US Territory Code,
favoring US Postal recommendations when possible, but falling back to
the as-typed version if it cannot be resolved.
For example,
"Id.", "ID", "Idaho", "Ida." -- all return "ID"
"N.Y.", "ny", "NewYork", "New York" -- all return "NY"
"S.C.", "S. Carolina", "S.Carolina", "South Carolina" -- all return "SC"
Canadian Province, U.S. Territories, and Military codes are supported.
Pass a standard CSZ string (e.g. "Salt Lake City, Utah 84101"), with or without punctuation, returns "UT".
If
the State-code cannot be reconciled against the US Postal
recommendations, the state is returned, as-typed. For example, "Boise,
zIdaho" returns a state-value of "zIadaho", as typed. The comma helps
the decision.
Without a city-comma, the routine will
return correctly-spelled State names or State-Codes and abbreviations
into the STATE field; other wise, they are appended to the City Name,
making the address likely still deliverable. For example:
Boise Idaho 83700 -- returns State Code "ID"
Boise Zidaho 83700 -- returns State Code "" (empty), with city "Boise Zidaho"
ReturnCityName
public string ReturnCityName (string strpassedString)
---------------------------------------------------------------------------------------------------------------
Returns the City name from any CSZ string, with or without a city-comma.
A
comma is not required to parse the city name, but in some instances, a
comma will return better results, especially if the State-name is
non-standard or non-determinable.
Multiple-word City names are supported:
"Post Falls, ID 83700" -- returns "Post Falls"
"Post Falls ID 83700" -- returns "Post Falls"
"Salt Lake City Utah" -- returns "Salt Lake City"
The returned City name is in the same case (upper/lower) as-typed.
Your calling routine should upper-case or proper-case as needed*
Missing
City names, such as a badly-formed CSV file, behave differently,
depending on the city-comma. For example, consider this string, with a
leading comma:
",ID 83700" --returns
CityName = "*" (an asterisk)
indicating a required city
is missing and
this will not be deliverable by the post office. The asterisk helps
identify bad records. Zipcodes can span multiple cities and in most
cases, a city is required. (However, with a zipcode, the State is
optional, see below).
Badly-formed
records, without a city-comma, will return a city name and will result in a
deliverable mail, albeit it won't be "liked" by the Post Office:
"Boise 83700" or
"Boise, 83700"
-- returns CityName = "Boise"; State-Code = (empty).
ReturnZipCode
public string ReturnZipCode (string strpassedString)
---------------------------------------------------------------------------------------------------------------
Returns
the complete Zip or Postal-Code, including Zip-5+Zip4, as one string.
As with most public methods in this class, pass a fully-formed CSZ as
the passed-string; returned results will be the ZipCode, fully-formed
and punctuated.
For example, passing
"Boise, ID 83703-1234" -- returns "83703-1234"
"Boise, ID 83703 1234" -- returns "83703-1234"
"Boise, ID 837031234" -- returns "83703-1234"
"Boise, ID 83703" -- returns "83703"
"Belleview ONT K01 1B2" -- returns "K01-1B2" (Canadian)
"Amherst MA 1003" -- returns "01003" - leading zero was stripped, typically by Excel, and re-added.
"Baton Rouge, MI" -- returns "" (empty-string - missing postal code)
Note: Does not confirm the ZipCode against the State, nor is the zipcode cross-checked for accuracy.
ReturnZip5
public string ReturnZip5 (string strpassedString)
---------------------------------------------------------------------------------------------------------------
Returns
the Zip5-part of the ZipCode, stripping Zip4. Pass a fully-formed CSZ
(City-State-Zip) into the method and get returned the Zip5.
For example, passing
"Boise, ID 83703-1234" -- returns "83703"
"Boise ID 83703 1234" -- returns "83703"
"Boise Idaho 837031234" -- returns "83703"
"Boise, ID 83703" -- returns "83703"
"Boise, ID" -- returns "" (empty string)
"Belleview ONT K01 1B2" -- returns "K01-1B2" (Canadian)
"Belleview ON K011b2" -- returns "K01-1B2"
ReturnZip4
public string ReturnZip4 (string strpassedString)
---------------------------------------------------------------------------------------------------------------
Returns only the Zip4-part of the ZipCode, if present. Pass a fully-formed CSZ
(City-State-Zip) into the method and get returned the Zip5.
For example, passing
"Boise, ID 83703-1234" -- returns "1234"
"Boise Idaho 837031234" -- returns "1234"
"Boise, ID 83703" -- returns "" (empty string - no zip4 information)
"Boise, ID" -- returns "" (empty string, no zipcode passed)
"Belleview ONT K01 1B2" (Canadian) -- returns "" (empty string)
ReturnStateAbbr
public string ReturnStateAbbr (string strpassedString
---------------------------------------------------------------------------------------------------------------
When
passed a State Name or abbreviation, returns the US Postal recommended
two-character State-Code, Province, or US. Territory. This routine is
called by all other public State methods and you do not need to call
this routine directly. It is exposed as a public method, should you
find other needs.
For example, passing
"Id" -- returns "ID"
"District of Columbia" -- returns "DC"
"W.V." -- returns "WV"
"W.Virginia" -- returns "WV"
"West Virginia" -- returns "WV"
"W Virginia" -- returns "WV"
If
a State (province, etc.) cannot be resolved, the original string is
returned, unmolested. Common variants are supported (N.Y., NewYork,
etc.). Advise the author if you find any missing.
State-Codes
can be parsed, with or without a comma (the city-comma), but work best
when a comma is present. See "ReturnCityName" for more information on
comma-processing
ReturnCountryName
public string ReturnCountryName (string strpassedString
---------------------------------------------------------------------------------------------------------------
Returns
the Country name, if typed on the CSZ line (be aware most people
address the Country name on a separate envelope-line and it would not be
seen or processed by this routine).
For example:
Boise, ID 83700-1234 U.S. -- returns "U.S."
Belleview ON LDU-9Z1 Canada -- returns "Canada"
This
routine is relatively stupid. Basically, everything to the right of
the Zipcode is considered a Country name. No effort is made to validate
as this is just a parsing routine.
Other Public Methods included in this Library:
SuperTrim
public string SuperTrim(string strpassedString)
---------------------------------------------------------------------------------------------------------------
Trims multiple leading, trailing and redundant interior spaces from a string.
Space-hyphne-Space (" - ") are compressed into a single hyphen.
Leading commas and hyphens are stripped (orphaned commas, orphaned hyphens).
Trailing hyphens are stripped.
EM and EMM dashes (long dashes) are replaced with simple hyphens.
For example:
" The rain falls. " -- returns "The rain falls."
"Boise , ID 83700 - 1234" -- returns "Boise, ID 83700-1234"
",ID 83700" -- returns "ID 83700"
CountWords
public int CountWords(string strpassedString)
---------------------------------------------------------------------------------------------------------------
Returns
a numeric count showing how many words are in the string, where words
are delimited with a space or hyphen. Words are super-trimmed prior to
counting -- multiple embedded spaces are compressed. For example:
"Three dog night" -- returns 3
"My three sons-and a daughter" -- returns 6
ReturnFirstWord
ReturnLastWord
public string ReturnFirstWord(string strpassedString)
public string ReturnLastWord(string strpassedString)
---------------------------------------------------------------------------------------------------------------
Returns
the first word or last word in a string. If only one word passed, that
word is returned. The string is simple-trimmed before processing.
Hyphenated words and other punctuation are not considered in these
routines.
FindLastSpacePos
public int FindLastSpacePos(string strpassedString)
---------------------------------------------------------------------------------------------------------------
Returns
a numeric, base-zero count showing the last space (character) found in
the string - Horizontal Position. This is a simple ".LastIndexOf(' ')"
and does not account for multiple interior spaces. For best results,
supertrim prior to calling.
TruncateTrailingPunctuation
public string TruncateTrailingPunctuation(string strpassedString)
---------------------------------------------------------------------------------------------------------------
Removes
all manner of trailing punctuation on a string, including commas,
periods, special characters. This uses a .TrimEnd(array) method.
See this article for a complete description of the class library, with download instructions
Keyliner: City-State-Zip DLL - Reliably Parse CSZ Fields