namespace Cepis;

/// <summary>
/// The CEP is well-formed but does not exist in the DNE database.
/// </summary>
/// <remarks>
/// <para>
/// Retrying does not help: the answer is definitive until the next fortnightly
/// database. A batch never throws this — a CEP with no address is
/// <see langword="null"/> at its position instead.
/// </para>
/// <para>
/// <see cref="Faixa"/> carries the municipality the CEP would have belonged to,
/// when the API can name one. It is context for the failure and not a fallback
/// address: this is still a 404.
/// </para>
/// </remarks>
public sealed class CepNotFoundException : CepisException
{
    /// <summary>Create the exception with a message and the range, if any.</summary>
    /// <param name="message">what went wrong</param>
    /// <param name="faixa">
    /// the municipality the CEP would belong to, or <see langword="null"/> when
    /// the API named none
    /// </param>
    public CepNotFoundException(string message, Faixa? faixa = null)
        : base(message)
    {
        Faixa = faixa;
    }

    /// <summary>Create the exception with a message, the range and a cause.</summary>
    /// <param name="message">what went wrong</param>
    /// <param name="faixa">the municipality the CEP would belong to, if any</param>
    /// <param name="innerException">the failure underneath</param>
    public CepNotFoundException(string message, Faixa? faixa, Exception? innerException)
        : base(message, innerException)
    {
        Faixa = faixa;
    }

    /// <summary>
    /// The municipality the CEP would have belonged to, or
    /// <see langword="null"/> when there is none.
    /// </summary>
    /// <remarks>
    /// <para>
    /// <see langword="null"/> is the ordinary case for a CEP falling in a band
    /// no municipality owns: the API <b>omits</b> the block rather than sending
    /// a null, and an older API does not send it at all. Anything unreadable in
    /// it lands here as <see langword="null"/> too — a courtesy field is not
    /// worth turning a clean not-found into a parse error over.
    /// </para>
    /// <para>
    /// It says which municipality the number <i>would</i> be in, not that any
    /// address exists. Read <see cref="Cepis.Faixa"/> before using
    /// <see cref="Cepis.Faixa.CepIni"/> and <see cref="Cepis.Faixa.CepFim"/>:
    /// they bound the CEPs that exist there, and the range between them is
    /// mostly empty.
    /// </para>
    /// </remarks>
    public Faixa? Faixa { get; }
}