org.gicentre.utils.spatial

## Class Postcode

- java.lang.Object
- - org.gicentre.utils.spatial.Postcode

-     public class Postcode
      extends java.lang.Object

  Class for parsing postcodes. Allows areas, districts, sectors and units to be identified individually. Will parse partial postcodes as well as those containing arbitrary whitespace.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jo Wood, giCentre, City University London.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Postcode(java.lang.String postcode)` Stores the given postcode and validates it.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getArea()` Reports the postcode area or null if the postcode is invalid.
    `java.lang.String` | `getAreaCode()` Reports the part of the postcode that represents the postcode area or null if the postcode is invalid.
    `java.lang.String` | `getDistrict()` Reports the postcode district or null if the postcode is invalid.
    `java.lang.String` | `getDistrictCode()` Reports the part of the postcode that represents the postcode district or null if the postcode is invalid.
    `java.lang.String` | `getErrorMessage()` Reports any error messages associated with an attempt to parse the postcode text.
    `java.lang.String` | `getSector()` Reports the postcode sector or null if the postcode is invalid.
    `java.lang.String` | `getSectorCode()` Reports the part of the postcode that represents the postcode sector or null if the postcode is invalid.
    `java.lang.String` | `getUnit()` Reports the postcode unit or null if the postcode is invalid.
    `java.lang.String` | `getUnit7()` Reports a seven digit unit postcode or null if the postcode is invalid.
    `java.lang.String` | `getUnitCode()` Reports the part of the postcode that represents the postcode unit or null if the postcode is invalid.
    `boolean` | `isValid()` Reports whether the stored postcode is valid.
    `java.lang.String` | `toString()` Provides a string representation of the postcode.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Postcode

          public Postcode(java.lang.String postcode)

      Stores the given postcode and validates it.
      Parameters:
        `postcode` - Postcode to validate.

  - ### Method Detail

    - #### isValid

          public boolean isValid()

      Reports whether the stored postcode is valid. If it is, a separate area, district, sector and unit can be extracted.
      Returns:
        True if postcode is valid.

    - #### getArea

          public java.lang.String getArea()

      Reports the postcode area or null if the postcode is invalid. For postcode LE1 7RH, the postcode area is LE.
      Returns:
        Postcode area, or null if postcode is invalid.

    - #### getAreaCode

          public java.lang.String getAreaCode()

      Reports the part of the postcode that represents the postcode area or null if the postcode is invalid. For postcode LE1 7RH, the postcode area code is LE.
      Returns:
        Postcode area code, or null if postcode is invalid.

    - #### getDistrict

          public java.lang.String getDistrict()

      Reports the postcode district or null if the postcode is invalid. If the postcode is valid, but no district has been defined, this returns as much of the postcode as is defined. For postcode LE1 7RH, the postcode district is LE1.
      Returns:
        Postcode district, or empty string if not defined or null if postcode is invalid.

    - #### getDistrictCode

          public java.lang.String getDistrictCode()

      Reports the part of the postcode that represents the postcode district or null if the postcode is invalid. For postcode LE1 7RH, the postcode district code is 1.
      Returns:
        Postcode district code, or null if postcode is invalid.

    - #### getSector

          public java.lang.String getSector()

      Reports the postcode sector or null if the postcode is invalid. If the postcode is valid, but no sector has been defined, this returns an empty string. For postcode LE1 7RH, the postcode sector is LE1 7.
      Returns:
        Postcode sector, or empty string if not defined or null if postcode is invalid.

    - #### getSectorCode

          public java.lang.String getSectorCode()

      Reports the part of the postcode that represents the postcode sector or null if the postcode is invalid. For postcode LE1 7RH, the postcode sector code is 7.
      Returns:
        Postcode sector code, or null if postcode is invalid.

    - #### getUnit

          public java.lang.String getUnit()

      Reports the postcode unit or null if the postcode is invalid. If the postcode is valid, but no unit has been defined, this returns an empty string. For postcode LE1 7RH, the postcode unit is LE1 7RH.
      Returns:
        Postcode unit, or empty string if not defined or null if postcode is invalid.

    - #### getUnit7

          public java.lang.String getUnit7()

      Reports a seven digit unit postcode or null if the postcode is invalid. If there are fewer than seven digits, spaces are inserted between the district and sector. This can be used for comparison with CodePoint seven digit postcode records. For postcode LE1 7RH, the seven digit unit postcode LE1 7RH, for S1 2TN the seven digit unit postcode is S1 2TN, for EC1V 0HB the seven digit unit postcode is EC1V0HB.
      Returns:
        Seven digit unit postcode, or null if postcode is invalid.

    - #### getUnitCode

          public java.lang.String getUnitCode()

      Reports the part of the postcode that represents the postcode unit or null if the postcode is invalid. For postcode LE1 7RH, the postcode unit code is RH.
      Returns:
        Postcode unit code, or null if postcode is invalid.

    - #### getErrorMessage

          public java.lang.String getErrorMessage()

      Reports any error messages associated with an attempt to parse the postcode text. If the postcode is valid, this will always be an empty string.
      Returns:
        Error message associated with parsing the postcode or empty string if postcode is valid.

    - #### toString

          public java.lang.String toString()

      Provides a string representation of the postcode. If valid, this will be all uppercase with a single space separating the incode (e.g. LE1) from the outcode (7RH). Note the postcode need not be at the unit level, so, for example S, S10 and S10 3 are all valid. If invalid an empty string is returned.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        Text representing the postcode or empty string if no valid postcode represented.