New Core Tutorial

git-svn-id: svn://ultimatepp.org/upp/trunk@10538 f0d560ea-af0d-0410-9eb7-867de7ffcac7

tutorial/CoreTutorial/Map.cpp

@@ -0,0 +1,138 @@
+#include "Tutorial.h"
+
+void Map()
+{
+	/// .`VectorMap`, `ArrayMap`
+
+	/// `VectorMap` is nothing else than a simple composition of `Index` of keys and `Vector`
+	/// of values. You can use `Add` methods to put elements into the `VectorMap`:
+
+	struct Person : Moveable<Person> {
+		String name;
+		String surname;
+		
+		String ToString() const { return String() << name << ' ' << surname; }
+	
+		Person(String name, String surname) : name(name), surname(surname) {}
+		Person() {}
+	};
+
+	VectorMap<String, Person> m;
+	
+	m.Add("1", Person("John", "Smith"));
+	m.Add("2", Person("Carl", "Engles"));
+
+	Person& p = m.Add("3");
+	p.name = "Paul";
+	p.surname = "Carpenter";
+	
+	DUMP(m);
+
+	/// `VectorMap` provides read-only access to its `Index` of keys and read-write access to its
+	/// `Vector` of values:
+
+	DUMP(m.GetKeys());
+	DUMP(m.GetValues());
+	
+	///
+	
+	m.GetValues()[2].name = "Peter";
+	
+	DUMP(m);
+	
+	/// You can use indices to iterate `VectorMap` contents:
+
+	for(int i = 0; i < m.GetCount(); i++)
+		LOG(m.GetKey(i) << ": " << m[i]);
+	
+	/// Standard `begin` / `end` pair for `VectorMap` is the range of just values (internal Vector)
+	/// - it corresponds with `operator[]` returning values:
+
+	for(const auto& p : m)
+		DUMP(p);
+	
+	/// To iterate through keys, you can use `begin`/`end` of internal `Index`:
+	
+	for(const auto& k : m.GetKeys())
+		DUMP(p);
+	
+	/// Alternatively, it is possible to create 'projection range' of VectorMap that provides
+	/// convenient key/value iteration, using `operator~` (note that is also removes 'unliked'
+	/// items, see later):
+	
+	for(const auto& e : ~m) {
+		DUMP(e.key);
+		DUMP(e.value);
+	}
+
+	/// You can use Find method to retrieve position of element with required key:
+
+	DUMP(m.Find("2"));
+
+	/// or Get method to retrieve corresponding value:
+
+	DUMP(m.Get("2"));
+
+	/// Passing key not present in `VectorMap` as `Get` parameter is undefined behavior (ASSERT
+	/// fails in debug mode), but there exists two parameter version of `Get` that returns second
+	/// parameter if the key is not found in VectorMap:
+
+	DUMP(m.Get("33", Person("unknown", "person")));
+
+	/// As with `Index`, you can use `Unlink` to make elements invisible for Find operations:
+
+	m.Unlink(1);
+	DUMP(m.Find("2"));
+
+	/// `SetKey` changes the key of the element:
+
+	m.SetKey(1, "33");
+	DUMP(m.Get("33", Person("unknown", "person")));
+
+	/// If there are more elements with the same key in `VectorMap`, you can iterate them using
+	/// `FindNext` method:
+
+	m.Add("33", Person("Peter", "Pan"));
+
+	int q = m.Find("33");
+	while(q >= 0) {
+		DUMP(m[q]);
+		q = m.FindNext(q);
+	}
+	
+	/// Unlinked positions can be 'reused' using Put method:
+
+	m.UnlinkKey("33");
+	m.Put("22", Person("Ali", "Baba"));
+	m.Put("44", Person("Ivan", "Wilks"));
+
+	DUMP(m);
+
+	/// `PickValues` / `PickIndex` / `PickKeys` / pick internal `Vector` / `Index` / `Vector`
+	/// of `Index`:
+
+	Vector<Person> ps = m.PickValues();
+	Vector<String> ks = m.PickKeys();
+	
+	DUMP(ps);
+	DUMP(ks);
+	DUMP(m);
+	
+	/// `VectorMap` pick constructor to create map by picking:
+	
+	ks[0] = "Changed key";
+
+	m = VectorMap<String, Person>(pick(ks), pick(ps));
+	
+	DUMP(m);
+
+	/// `ArrayMap` is composition of Index and Array, for cases where Array is better fit for
+	/// value type (e.g. they are polymorphic):
+
+	ArrayMap<String, Person> am;
+	am.Create<Person>("key", "new", "person");
+	
+	DUMP(am);
+	
+	///
+}