shippex v0.8.0 Shippex.Address

Represents an address that can be passed to other Shippex functions. Do not initialize this struct directly. Instead, use address/1.

Link to this section Summary

Functions

Returns the list of non-nil address lines. If no address_line_2 is present, it returns a list of a single String.

Converts a full country name to its 2-letter ISO-3166-2 code.

Initializes an Address struct from the given params, and performs minor validations that do not require any service requests.

Calls new/1 and raises an error on failure.

Converts a full state name to its 2-letter ISO-3166-2 code. The country MUST be an ISO-compliant 2-letter country code.

Returns the state code without its country code prefix.

Takes a state and country input and returns the validated, ISO-3166-compliant results in a tuple.

Link to this section Types

Specs

t() :: %Shippex.Address{
  address: String.t(),
  address_line_2: nil | String.t(),
  city: String.t(),
  company_name: nil | String.t(),
  country: String.t(),
  first_name: nil | String.t(),
  last_name: nil | String.t(),
  name: nil | String.t(),
  phone: nil | String.t(),
  state: String.t(),
  zip: String.t()
}

Link to this section Functions

Link to this function

address_line_list(address)

Specs

address_line_list(t()) :: [String.t()]

Returns the list of non-nil address lines. If no address_line_2 is present, it returns a list of a single String.

Link to this function

country_code(country)

Specs

country_code(String.t()) :: nil | String.t()

Converts a full country name to its 2-letter ISO-3166-2 code.

iex> Address.country_code("United States")
"US"
iex> Address.country_code("Mexico")
"MX"
iex> Address.country_code("Not a country.")
nil

Specs

new(map()) :: {:ok, t()} | {:error, String.t()}

Initializes an Address struct from the given params, and performs minor validations that do not require any service requests.

You may specify first_name and last_name separately, which will be concatenated to make the name property, or just specify name directly.

If name is specified directly, Shippex will try to infer the first and last names in case they're required separately for API calls.

Shippex.Address.new(%{
  first_name: "Earl",
  last_name: "Grey",
  phone: "123-123-1234",
  address: "9999 Hobby Lane",
  address_line_2: nil,
  city: "Austin",
  state: "TX",
  zip: "78703"
})

Specs

new!(map()) :: t() | none()

Calls new/1 and raises an error on failure.

Link to this function

state_code(state, country \\ "US")

Specs

state_code(String.t(), String.t()) :: nil | String.t()

Converts a full state name to its 2-letter ISO-3166-2 code. The country MUST be an ISO-compliant 2-letter country code.

iex> Address.state_code("Texas")
"US-TX"
iex> Address.state_code("teXaS")
"US-TX"
iex> Address.state_code("TX")
"US-TX"
iex> Address.state_code("US-TX")
"US-TX"
iex> Address.state_code("AlberTa", "CA")
"CA-AB"
iex> Address.state_code("Veracruz", "MX")
"MX-VER"
iex> Address.state_code("Yucatán", "MX")
"MX-YUC"
iex> Address.state_code("Yucatan", "MX")
"MX-YUC"
iex> Address.state_code("YucatAN", "MX")
"MX-YUC"
iex> Address.state_code("Not a state.")
nil
Link to this function

state_without_country(map)

Specs

state_without_country(t() | %{state: String.t(), country: String.t()}) ::
  String.t()

Returns the state code without its country code prefix.

iex> address = Shippex.Address.new!(%{
...>   first_name: "Earl",
...>   last_name: "Grey",
...>   phone: "123-123-1234",
...>   address: "9999 Hobby Lane",
...>   address_line_2: nil,
...>   city: "Austin",
...>   state: "US-TX",
...>   zip: "78703",
...>   country: "US"
...>  })
iex> Address.state_without_country(address)
"TX"
Link to this function

validated_state_and_country(state, country \\ nil)

Specs

validated_state_and_country(any(), any()) ::
  {:ok, String.t(), String.t()} | {:error, String.t()}

Takes a state and country input and returns the validated, ISO-3166-compliant results in a tuple.

iex> Address.validated_state_and_country("TX")
{:ok, "US-TX", "US"}
iex> Address.validated_state_and_country("TX", "US")
{:ok, "US-TX", "US"}
iex> Address.validated_state_and_country("US-TX", "US")
{:ok, "US-TX", "US"}
iex> Address.validated_state_and_country("Texas", "US")
{:ok, "US-TX", "US"}
iex> Address.validated_state_and_country("Texas", "United States")
{:ok, "US-TX", "US"}
iex> Address.validated_state_and_country("Texas", "United States")
{:ok, "US-TX", "US"}
iex> Address.validated_state_and_country("SG-SG", "SomeCountry")
{:error, "Invalid country: SomeCountry"}
iex> Address.validated_state_and_country("SG-Invalid", "SG")
{:error, "Invalid state 'SG-Invalid' for country: SG (SG)"}