Documentation - CityStateZip Public Functions

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