add FeatureDictionary.byId

Author: westnordost

README.md

@@ -86,3 +86,13 @@ List<Feature> matches = dictionary
     .find();
 // result list will have matches with at least amenity=bank, but not amenity=bench because it is a point-feature
 ```
+
+### Find by id
+
+```java
+Feature feature = dictionary
+    .byId("amenity/bank")
+    .forLocale(Locale.GERMAN)        // show results in German
+    .inCountry("DE")                 // also include things (brands) that only exist in Germany
+    .get();
+```

library/src/main/java/de/westnordost/osmfeatures/FeatureDictionary.java

@@ -57,6 +57,23 @@ public static FeatureDictionary create(String presetsBasePath, String brandPrese
 		return new FeatureDictionary(featureCollection, brandsFeatureCollection);
 	}
 
+	//region Get by id
+
+	/** Find feature by id */
+	public QueryByIdBuilder byId(String id)
+	{
+		return new QueryByIdBuilder(id);
+	}
+
+	private Feature get(String id, List<Locale> locales, String countryCode)
+	{
+		Feature feature = featureCollection.get(id, locales);
+		if (feature != null) return feature;
+		return brandFeatureCollection.get(id, Collections.singletonList(countryCode));
+	}
+
+	//endregion
+
 	//region Query by tags
 
 	/** Find matches by a set of tags */
@@ -387,6 +404,48 @@ private FeatureTagsIndex createBrandTagsIndex(List<String> countryCodes)
 
 	//region Query builders
 
+	public class QueryByIdBuilder
+	{
+		private final String id;
+		private Locale[] locale = new Locale[]{Locale.getDefault(), null};
+		private String countryCode = null;
+
+		private QueryByIdBuilder(String id) { this.id = id; }
+
+		/** <p>Sets the locale(s) in which to present the results.</p>
+		 *  <p>You can specify several locales in
+		 *  a row to each fall back to if a translation does not exist in the locale before that.
+		 *  For example <code>[new Locale("ca", "ES"), new Locale("es","ES")]</code> if you
+		 *  wanted results preferredly in Catalan, but Spanish is also fine.</p>
+		 *
+		 *  <p><code>null</code> means to include unlocalized results.</p>
+		 *
+		 *  <p>If nothing is specified, it defaults to <code>[Locale.getDefault(), null]</code>,
+		 *  i.e. unlocalized results are included by default.</p>
+		 *   */
+		public QueryByIdBuilder forLocale(Locale... locale)
+		{
+			this.locale = locale;
+			return this;
+		}
+
+		/** the ISO 3166-1 alpha-2 country code (e.g. "US") or the ISO 3166-2 (e.g. "US-NY") of the
+		 *  country/state the element is in. If not specified, will only return matches that are not
+		 *  county-specific. */
+		public QueryByIdBuilder inCountry(String countryCode)
+		{
+			this.countryCode = countryCode;
+			return this;
+		}
+
+		/** Returns the feature associated with the given id or <code>null</code> if it does not
+		 *  exist */
+		public Feature get()
+		{
+			return FeatureDictionary.this.get(id, Arrays.asList(locale), countryCode);
+		}
+	}
+
 	public class QueryByTagBuilder
 	{
 		private final Map<String, String> tags;

library/src/test/java/de/westnordost/osmfeatures/FeatureDictionaryTest.java

@@ -583,6 +583,51 @@ public class FeatureDictionaryTest
 
 	//endregion
 
+	//region by id
+
+	@Test public void find_no_entry_by_id()
+	{
+		FeatureDictionary dictionary = dictionary(bakery);
+		assertNull(dictionary.byId("amenity/hospital").get());
+	}
+
+	@Test public void find_no_entry_by_id_because_unlocalized_results_are_excluded()
+	{
+		FeatureDictionary dictionary = dictionary(bakery);
+		assertNull(dictionary.byId("shop/bakery").forLocale(Locale.ITALIAN).get());
+	}
+
+	@Test public void find_entry_by_id()
+	{
+		FeatureDictionary dictionary = dictionary(bakery);
+		assertEquals(bakery, dictionary.byId("shop/bakery").get());
+		assertEquals(bakery, dictionary.byId("shop/bakery").forLocale(Locale.CHINESE, null).get());
+	}
+
+	@Test public void find_localized_entry_by_id()
+	{
+		FeatureDictionary dictionary = dictionary(panetteria);
+		assertEquals(panetteria, dictionary.byId("shop/bakery").forLocale(Locale.ITALIAN).get());
+		assertEquals(panetteria, dictionary.byId("shop/bakery").forLocale(Locale.ITALIAN, null).get());
+	}
+
+	@Test public void find_no_entry_by_id_because_wrong_country()
+	{
+		FeatureDictionary dictionary = dictionary(ditsch);
+		assertNull(dictionary.byId("shop/bakery/Ditsch").get());
+		assertNull(dictionary.byId("shop/bakery/Ditsch").inCountry("IT").get());
+		assertNull(dictionary.byId("shop/bakery/Ditsch").inCountry("AT-9").get());
+	}
+
+	@Test public void find_entry_by_id_in_country()
+	{
+		FeatureDictionary dictionary = dictionary(ditsch);
+		assertEquals(ditsch, dictionary.byId("shop/bakery/Ditsch").inCountry("AT").get());
+		assertEquals(ditsch, dictionary.byId("shop/bakery/Ditsch").inCountry("DE").get());
+	}
+
+	//endregion
+
 	@Test public void find_by_term_sorts_result_in_correct_order()
 	{
 		FeatureDictionary dictionary = dictionary(