Thursday, March 5, 2015

CityStateZip DLL - Reliably Parse CSZ fields using this class library

CityStateZip DLL - Reliably parse CSZ fields using a Windows class library developed by  Without bragging, this routine is slick - it understands and knows all about city-state-zip fields.  It can figure this stuff out, no matter how badly typed.

You are welcome to use this library for commercial and non-commercial use.  This is a different (and more powerful) routine than the VBA programs published previously.

Related Article:
Parsing CityStateZip in Excel using VBA


I periodically need to parse a single field's City-State-Zip into its constituent parts, typically after processing US Postal files from a program called "NCOA".

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, it can return a fully-assembled and re-punctuated CSZ:
Salt Lake City, UT 84101-1234

The routine takes a passed City-State-Zip and can return either a newly-re-assembled string, with proper punctuation and state codes -- or it can return each constituent part, complete with two-character State and Province Codes.

It can handle multi-word city, multi-word states, with or without punctuation.  It converts abbreviated or spelled-out state names, converting them to US Postal 2-character codes.  It knows all about zipcodes and country codes.

Badly-formed CSZ's, such as these, are correctly parsed:

In each case, the city, official State-code, and a properly-formatted zipcode is returned.  You can return individual components, such as the city, or a fully-formed, correctly punctuated string.  This can handle Canadian Provinces, US Territories, and US Military Destinations, such as Europe ("AE").  It can handle Country Names (e.g. Vancouver B.C. 1A2-1B3 Canada), etc.

The routines prefer to work, but is not required, with a comma after the city name.

This is a Windows class library and is expected to be linked into your program's (C# or other) code as a new module.  Once linked, the following public methods are available.  See below for instructions on how to link.

Public Methods:
ReturnZipCode (full postal-code, zip5 + zip4)
ReturnCountryName (Canada, etc.)

Other Public Methods (utility routines)
ReturnStateAbbr (Returns "WV" for "West Virginia")
SuperTrim (trims redundant internal spaces, hyphen-spaces, etc.)
FindLastSpacePos (position of last-word)

Complete Documentation on these Methods can be found here:
Documentation - CSZ Public Methods

Download Instructions:

Download the DLL/Class library from keyliner's G-Drive:
G-Drive Link: ns801_CityState.dll

Download a sample program (executable - dot-net 4.5) to test or try out the library.
This executable is self-contained and does not require the DLL.

Example Program download:
G-Drive Link: CityStateZipTest.exe

Self-contained test program, available for download
The Test program has the DLL linked internally, and the external DLL is not needed to run the program.  This allows you to manually type CSZ's to see how they will parse.  This is not meant, nor is it usable for production work.  You will need to apply the DLL to your specific project, with the instructions below.

Legal stuff: There is no charge or registration required to download these routines.  You are free to use for commercial and non-commercial use.  If you use the routines, leave a comment, telling me how it went.  Please give credit to the author in your commercial projects.  You may not re-distribute the DLL as a stand-alone distribution; instead, link to this article.  Much effort has gone into the development, but the author assumes no liability for errors or mistakes.  Test before deploying in a production environment.  If you find errors or mis-parsed lines, I would like to know about them.

Linking and Use Instructions

This is a standard, unsigned DLL, which you can link into your development project as a resource.  Once linked and instantiated, all public methods are exposed and can be used in your program

These instructions assume a Visual Studio C# project.  Your development language or environment may be different, but the steps are similar:

A.  Save the DLL (ns801_CityState.dll) to a known location.

For example, C:\Data\Source\CommonVS\ns801_CityState.DLL

B.  From your project (development code), open Solution Explorer.  "Other-mouse-click" References, choosing "Add Reference".

C.  Browse to the DLL's location  (e.g. C:\Data\Source\CommonVS\ns801_CityState.DLL)

D.  At the top of your program, add this recommended 'using' statement:

using ns801_CityState;

E.  In the public partial class Form1 (or other location, declare a class or method variable)

//Assigning a name "citystate." to the module
//Note: No equalsign, no parens: 
cl801_CityState citystate;

F.  Typically in the Form1's constructor, after "InitializeComponent," -- or in a function or method of your choosing, instantiate the class with this statement:

citystate = new cl801_CityState();

G.  The class is ready to use:  For example:
citystate.ReturnCityName ("Boise Idaho 83700 1234");

Click for larger view

Can the DLL be linked into an Excel Spreadsheet or VBA routine?  I'll fiddle with the idea in the future.

A boat-load of work went into building this class library.
If you find it useful, make a donation to the International Keyliner Pizza Fund (via PayPal).
It would make me happy and you proud:

If you have a suggestion, feature request, or find something it does not parse correctly, leave a comment, below.  Registration not required.

I wonder: Should this routine return a "Proper"-cased string?  Currently, it returns the data, as typed.  Comments on this are welcome.

Version History:
1.01  Initial Release

Related Articles:

Similar, but less powerful routines were written for Excel, and they can be found here:
Parsing CityStateZip in Excel using VBA

Related Items:

DLL/Class library Download from keyliner's G-Drive:  ns801_CityState.dll
Example Program download: CityStateZipTest.exe
Documentation - CSZ Public Methods

No comments:

Post a Comment

Comments are moderated and published upon review.