1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
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; }
}
|