kleinere Optimierungen und Dokumentation

1 files changed, 41 insertions, 0 deletions

diff --git a/alphametiken.md b/alphametiken.md
new file mode 100644
index 0000000..ca8e96d
--- /dev/null
+++ b/alphametiken.md
@@ -0,0 +1,41 @@
+Alphametiken
+============
+
+Das Programm ist in zwei Teile gegliedert:
+
+* `löse(zu_lösendes_Alphametikum)` gibt eine Liste mit allen Lösungen eines Alphametikums in dem Format `[['Rechnung', {'Buchstabe': zugehörige_Zahl, ...}], ...]` zurück (zum Beispiel `[['8928-3164=5764', {'Ü': 9, 'F': 8, 'W': 7, 'N': 2, 'Z': 5, 'I': 4, 'E': 6, 'D': 3, 'R': 1}]]` für `FÜNF-DREI=ZWEI`).
+
+* `generiere(Länge)` gibt ein Alphametikum als String zurück (zum Beispiel `FÜNF-DREI=ZWEI`), für welches mindestens eine Lösung vorhanden ist.
+
+Alphametikum lösen
+------------------
+
+Die Funktion `ersetze`, aufgerufen durch `löse`, ersetzt jeweils den ersten Buchstaben im Alphametikum durch eine Zahl, nacheinander 0 bis 9. Für den Rest des Alphametikum-Strings wird die Funktion rekursiv aufgerufen. Ist der letzte Buchstabe ersetzt, wird mithilfe von Pythons `eval`-Funktion überprüft, ob die ersetzten Zahlen zu einer wahren Gleichung führen. Ist dies der Fall, wird die gefundene Lösung in einer Liste festgehalten und nach Überprüfen aller Kombinationen zurückgegeben.
+Der Ausnahmefall, dass die Lösung eine Null als erste Ziffer einer Zahl hat, wird durch einen regulären Ausdruck `re.search` überprüft. Um gleiche Zahlen nicht an mehrere Buchstaben zu verteilen wird in der rekursiven Funktion die Liste an bereits verwendeten Zahlen mitgegeben.
+
+Beispiel für eine Lösung:
+```
+>>> import alphametiken
+>>> alphametiken.löse("SEND + MORE = MONEY")
+[['9567 + 1085 = 10652', {'O': 0, 'N': 6, 'M': 1, 'E': 5, 'Y': 2, 'S': 9, 'D': 7, 'R': 8}]]
+```
+
+Alphametikum finden
+-------------------
+
+Zum Finden von Alphametiken in der Form `FÜNF-DREI=ZWEI` ist es zuerst nötig, eine valide Gleichung - hier `5-3=2` zu finden. Um dies für eine beliebige Länge zu tun, wird in der Funktion `generiere` ein Template erstellt, in dem `_` dann durch ein zufälliges Rechenzeichen, `x` und `y` durch eine zufällige Zahl von 0-9 ersetzte wird, sodass bei einer Länge von 1 dieses Schema entsteht:
+```
+x_x=y
+```
+das nun auf Richtigkeit, wieder durch `eval`, geprüft wird. Eine Gleichung wie `5-3=2` wird schließlich mithilfe von Zahlwörtern abgebildet: `FÜNF-DREI=ZWEI`. Jetzt wird mit `löse` geprüft, ob eine Lösung vorhanden ist. Wenn ja, endet die Funktion, sonst wird nach einer neuen Gleichung gesucht.
+`random.choice` und `random.randrange` dienen hier zum Finden zufälliger Rechenzeichen und Zahlen.
+
+
+TODO FIXME BEISPIELE + LÖSUNG
+
+Beispiel für ein Alphametikum mit mehr als 20 Zeichen:
+```
+>>> import alphametiken
+>>> alphametiken.generiere(3)
+'FÜNF-ZWEI+VIER-ZWEI=FÜNF'
+```