Skip to content

Commit bffd7d9

Browse files
rijnbrijnb
committed
Improved examples
1 parent 23d6afc commit bffd7d9

File tree

1 file changed

+128
-53
lines changed

1 file changed

+128
-53
lines changed

‎src/main/java/com/mapcode/example/Example.java‎

Lines changed: 128 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -29,40 +29,20 @@ public class Example {
2929
* @param args Arguments (unused).
3030
*/
3131
public static void main(final String[] args) throws UnknownTerritoryException {
32-
exampleDisambiguateTerritory();
33-
exampleGetTerritoryFromISOCode();
34-
exampleDecode();
3532
exampleEncode();
36-
exampleEncodeInAllTerritories();
37-
}
38-
39-
private static void exampleGetTerritoryFromISOCode() throws UnknownTerritoryException {
40-
LOG.info("Example: Get territory from ISO code");
41-
42-
// Print the full English name of the territory.
43-
final Territory territory = Territory.fromString("NLD");
44-
LOG.info("Territory {}: {}", territory.name(), territory.getFullName());
45-
LOG.info("");
46-
}
47-
48-
private static void exampleDisambiguateTerritory() throws UnknownTerritoryException {
49-
LOG.info("Example: (disambiguate code MN, which can be in USA and IND):");
50-
51-
final String isoCode = "MN";
52-
LOG.info("ISO code {} without context : {}", isoCode,
53-
Territory.fromString(isoCode).toString());
54-
LOG.info("ISO code {} in USA context : {}", isoCode,
55-
Territory.fromString(isoCode, ParentTerritory.USA).toString());
56-
LOG.info("ISO code {} in IND context : {}", isoCode,
57-
Territory.fromString(isoCode, ParentTerritory.IND).toString());
58-
LOG.info("ISO code {} in RUS context : {}", isoCode,
59-
Territory.fromString(isoCode, ParentTerritory.RUS).toString());
60-
LOG.info("");
33+
exampleDecode();
34+
exampleGetTerritoryFromISOCode();
35+
exampleDisambiguateTerritory();
6136
}
6237

6338
private static void exampleDecode() throws UnknownTerritoryException {
64-
LOG.info("Example: Decode");
39+
LOG.info("Example: Decoding Mapcodes to lat/lon points");
40+
LOG.info("--------");
6541

42+
/**
43+
* This example shows you how to decode a Mapcode to a point. The first example decodes
44+
* a valid Mapcode to a point.
45+
*/
6646
final Territory territory = Territory.fromString("NLD");
6747
final String mapcode1 = "49.4V";
6848
try {
@@ -71,57 +51,152 @@ private static void exampleDecode() throws UnknownTerritoryException {
7151
mapcode1, territory, p.getLatDeg(), p.getLonDeg());
7252
}
7353
catch (final UnknownMapcodeException ignored) {
74-
LOG.info("Mapcode {} in territory {} is invalid", mapcode1, territory);
54+
LOG.info("This should never happen in this example as the Mapcode is valid.");
7555
}
7656

57+
/**
58+
* The second example tries to decode an invalid Mapcode to a point which results
59+
* in an exception being thrown.
60+
*/
7761
final String mapcode2 = "49.4A";
7862
try {
7963
final Point p = Mapcode.decode(mapcode2, territory);
8064
LOG.info("Mapcode {} in territory {} represents latitude {}, longitude {}",
8165
mapcode2, territory, p.getLatDeg(), p.getLonDeg());
8266
}
8367
catch (final UnknownMapcodeException ignored) {
84-
LOG.info("Mapcode {} in territory {} is invalid", mapcode2, territory);
68+
LOG.info("Mapcode {} in territory {} is invalid, as expected in this example", mapcode2, territory);
69+
}
70+
71+
/**
72+
* The third example tries to decode a valid international Mapcode without a territory context.
73+
* This will succeed.
74+
*/
75+
final String mapcode3 = "PQ0PF.5M1H";
76+
try {
77+
final Point p = Mapcode.decode(mapcode3);
78+
LOG.info("Mapcode {} represents latitude {}, longitude {}", mapcode3, p.getLatDeg(), p.getLonDeg());
79+
}
80+
catch (final UnknownMapcodeException ignored) {
81+
LOG.info("This should never happen in this example as the Mapcode is valid.");
8582
}
8683
LOG.info("");
8784
}
8885

89-
private static void exampleEncode() throws UnknownTerritoryException {
90-
LOG.info("Example: Encode");
86+
private static void exampleEncode() {
87+
LOG.info("Example: Encoding lat/lon points to Mapcodes");
88+
LOG.info("--------");
9189

92-
final Territory territory = Territory.NLD;
93-
final double lat = 52.376514;
94-
final double lon = 4.908542;
95-
LOG.info("All possible Mapcodes in {} for latitude {}, longitude {}", territory.getFullName(), lat, lon);
90+
/**
91+
* This example shows you how to encode a lat/lon point into a Mapcode.
92+
*/
93+
double lat = 52.376514;
94+
double lon = 4.908542;
9695

97-
// Get all results for territory NLD.
98-
final List<MapcodeInfo> results = Mapcode.encode(lat, lon, territory);
99-
LOG.info("Point latitude {}, longitude {} has {} possible Mapcodes in {}",
100-
lat, lon, results.size(), territory.getFullName());
96+
/**
97+
* First, we will try to get all possible Mapcodes, for all territories.
98+
*/
99+
List<MapcodeInfo> results = Mapcode.encode(lat, lon);
100+
LOG.info("There are {} Mapcodes in total for latitude {}, longitude {} world-wide",
101+
results.size(), lat, lon);
101102

102103
int count = 1;
103104
for (final MapcodeInfo result : results) {
104-
LOG.info(" Alternative {}: {} {}", count,
105-
territory.toNameFormat(Territory.NameFormat.MINIMAL_UNAMBIGUOUS), result.getMapcode());
105+
LOG.info(" #{}: {}", count, result);
106106
++count;
107107
}
108108
LOG.info("");
109-
}
110109

111-
private static void exampleEncodeInAllTerritories() throws UnknownTerritoryException {
112-
LOG.info("Example: Encode in all territories");
110+
/**
111+
* Now, we will limit our search to a specific territory.
112+
*/
113+
final Territory territory = Territory.NLD;
114+
results = Mapcode.encode(lat, lon, territory);
115+
LOG.info("There are {} Mapcodes in total for latitude {}, longitude {} in {}",
116+
results.size(), lat, lon, territory.getFullName());
113117

114-
final double lat = 26.87016;
115-
final double lon = 75.847;
116-
LOG.info("All possible Mapcodes in the world for latitude {}, longitude {}", lat, lon);
118+
count = 1;
119+
for (final MapcodeInfo result : results) {
120+
LOG.info(" #{}: {}", count, result);
121+
++count;
122+
}
123+
LOG.info("");
117124

118-
final List<MapcodeInfo> results = Mapcode.encode(lat, lon);
119-
int count = 1;
125+
/**
126+
* This example tries to encode a lat/lon to Mapcode, regardless of the territory.
127+
* This produces a full list of Mapcodes.
128+
*/
129+
lat = 26.87016;
130+
lon = 75.847;
131+
132+
results = Mapcode.encode(lat, lon);
133+
LOG.info("There are {} Mapcodes in total for latitude {}, longitude {} world-wide",
134+
results.size(), lat, lon);
135+
count = 1;
120136
for (final MapcodeInfo result : results) {
121-
LOG.info(" Alternative {}: {} {}", count,
122-
result.getTerritory().toNameFormat(Territory.NameFormat.MINIMAL), result.getMapcode());
137+
LOG.info(" #{}: {}", count, result);
123138
++count;
124139
}
125140
LOG.info("");
141+
142+
/**
143+
* Finally, we will see what happens when we try to encode a location that is not
144+
* contained within a territory.
145+
*/
146+
results = Mapcode.encode(0, 0, territory);
147+
if (results.isEmpty()) {
148+
LOG.info(" No Mapcode results found, as expected in this example");
149+
}
150+
else {
151+
LOG.info("This should never happen in this example.");
152+
}
153+
LOG.info("");
154+
}
155+
156+
private static void exampleGetTerritoryFromISOCode() throws UnknownTerritoryException {
157+
LOG.info("Example: Get territory from an ISO code");
158+
LOG.info("--------");
159+
160+
/**
161+
* This examples print the full English name of the territory, given an ISO code as a string,
162+
* which may be obtained from user input, for example.
163+
*/
164+
final Territory territory = Territory.fromString("NLD");
165+
LOG.info("Territory {}: {}", territory.name(), territory.getFullName());
166+
LOG.info("");
167+
}
168+
169+
private static void exampleDisambiguateTerritory() throws UnknownTerritoryException {
170+
LOG.info("Example: Disambiguate a territory code");
171+
LOG.info("--------");
172+
173+
/**
174+
* This example uses an ISO code which is ambiguous: MN. MN is a state in the USA (Minnesota)
175+
* as well as a state in India. The examples shows how such a territory code can be
176+
* disambiguated using a parent territory context.
177+
*/
178+
final String isoCode = "MN";
179+
180+
// No disambiguation context.
181+
LOG.info("ISO code {} without context : {}", isoCode,
182+
Territory.fromString(isoCode).toString());
183+
184+
// Disambiguation using a correct parent territory context.
185+
LOG.info("ISO code {} in USA context : {}", isoCode,
186+
Territory.fromString(isoCode, ParentTerritory.USA).toString());
187+
LOG.info("ISO code {} in IND context : {}", isoCode,
188+
Territory.fromString(isoCode, ParentTerritory.IND).toString());
189+
190+
// Disambiguation using an incorrect parent territory context, which does not contains the state.
191+
// This call will actually fail and throw an exception because the disambiguation cannot be
192+
// completed.
193+
try {
194+
LOG.info("ISO code {} in RUS context : {}", isoCode,
195+
Territory.fromString(isoCode, ParentTerritory.RUS).toString());
196+
}
197+
catch (final UnknownTerritoryException ignored) {
198+
LOG.info("ISO code {} in RUS context : failed (as expected in this example)", isoCode);
199+
}
200+
LOG.info("");
126201
}
127202
}

0 commit comments

Comments
 (0)