C++-Programmierung/ Eine Matrix-Bibliothek – mitrax/ mitrax.hpp

Aus Wikibooks
Zur Navigation springen Zur Suche springen
Nuvola-inspired-terminal.svg
  1 #ifndef _mitrax_mitrax_hpp_INCLUDED_
  2 #define _mitrax_mitrax_hpp_INCLUDED_
  3 /// \file mitrax.hpp
  4 ///
  5 /// \brief Kompletteinbindung und Projektbeschreibung
  6 ///
  7 /// Diese Datei bindet alle mitrax-Dateien ein. Dies ist nur zum Testen gedacht, einer Einbindung
  8 /// der wirklich benötigten Komponenten ist der Vorzug zu gewähren.
  9 ///
 10 /// Weiterhin steht in dieser Datei die Projektbeschreibung für die Dokumentation.
 11 
 12 #include "mitrax/io.hpp"
 13 #include "mitrax/simple_operator.hpp"
 14 
 15 /// \mainpage Übersicht
 16 ///
 17 /// \author Benjamin Buch
 18 /// \version 0.5.2
 19 /// \date 14.06.2011
 20 ///
 21 /// \section intro_sec Einleitung
 22 ///
 23 /// mitrax ist eine C++-Bibliothek, welche als Herzstück eine matrix-Klasse (im Sinne einer
 24 /// mathematischen Matrix) zur Verfügung stellt. Es werden eine Reihe von Rechenoperationen,
 25 /// Ein- und Ausgabe (inklusive eigener Manipulatoren), der Zugriff auf Zeilen und Spalten mittels
 26 /// Proxyklassen und ein Iterator-Interface für elementweise Bearbeitung angeboten.
 27 ///
 28 /// \subsection intro_name_sec Entstehung
 29 ///
 30 /// <div style="float:right;border:1px black solid;">
 31 /// \image html mitra_mitra_html.jpg "Mitra Mitra aus der Gattung der Mitra"</div>
 32 /// Die Bibliothek entstand als Semesterprojekt während meines Studiums und ist vornehmlich als
 33 /// Lehrbeispiel für die aufgeführten Funktionalitäten gedacht. Für die praktische Nutzung ist
 34 /// Boost::uBLAS zu empfehlen, welche deutlich mehr Funktionalitäten implementiert.
 35 ///
 36 /// Der Name mitrax entstand durch zufälliges Vertauschen der Buchstaben von matrix, wobei sich
 37 /// nach entfernen des Buchstabens x am Ende, ein Wort ergab, das in der Biologie eine Gattung
 38 /// innerhalb der Familie der Mitridae (auch Mitraschnecken genannt) bezeichnet. Da deren Gestalt
 39 /// zwar immer ähnlich und dennoch abwechslungsreich ist, erinnern diese Tiere ein wenig an den
 40 /// Templatecharakter der Matrixklasse, auf den besonderen Wert gelegt wurde.
 41 ///
 42 /// \image latex mitra_mitra.jpg "Mitra Mitra aus der Gattung der Mitra" width=7cm
 43 ///
 44 /// \section install_sec Installation
 45 ///
 46 /// Die Bibliothek ist als Header-Only-Bibliothek aufgebaut. Eine Installation oder Vorkompilierung
 47 /// ist daher nicht nötig.
 48 ///
 49 /// \section structure_sec Struktur
 50 ///
 51 /// Die Datei mitrax.hpp bindet alle Funktionalitäten von mitrax ein. Die Verwendung dieser Datei
 52 /// ist nur für Testzwecke zu empfehlen, da sich die Compilierzeit gegenüber der Verwendung der
 53 /// spezifisch benötigten Funktionen erhöhen kann.
 54 ///
 55 /// Die Kernkomponente von mitrax ist die <code>matrix</code>-Klasse. Die Ein- und Ausgabe sowie
 56 /// die Operatoren sind von dieser losgelöst und müssen daher zusätzlich eingebunden werden, wenn
 57 /// sie benötigt werden.
 58 ///
 59 /// \section Konventionen
 60 ///
 61 /// Templateparameter beginnen mit einem Großbuchstaben und werden durch im Falle mehrteiliger
 62 /// Bezeichner durch Großbuchstaben getrennt. Alle anderen Bezeichner werden vollständig klein
 63 /// geschrieben und die Trennung mehrteiliger Bezeichner erfolgt per Unterstrich. Private
 64 /// Memberdaten-Bezeichner enden auf einen Unterstrich.
 65 ///
 66 /// Alles womit der Nutzer nicht unmittelbar Kontakt haben sollte, steht im Namensraum
 67 /// <code>detail</code>. Die Schnittstellen der dortigen Komponenten können sich jederzeit ändern,
 68 /// sofern dadurch kein Nutzercode ungültig wird, der diese Komponenten nur indirekt nutzt.
 69 ///
 70 /// Als Methoden werden nur jene Funktionen implementiert die zwingend Zugriff auf
 71 /// nicht-öffentliche Member benötigen. Im Falle der Proxyklassen gibt es mehrere Member mit
 72 /// gleicher Funktionalität. Dies dient der Schaffung einer einheitlichen Schnittstelle aller
 73 /// Proxyklassen, so dass Templates richtungsunabhängig gestaltet werden können. Weitere Ausnahmen
 74 /// gibt es derzeit nicht.
 75 /// 
 76 /// Die Iteratorklassen folgenden den Richtlinien, die der C++-Standard zu Iteratoren vorgibt.
 77 /// Entsprechend ist keine nähere Erläuterung der einzelnen Member Notwendig. Der Nutzer sollte mit
 78 /// diesen Klassen ohnehin nur in Form von <code>typedef</code>s Kontakt haben.
 79 ///
 80 /// Sofern nichts unmittelbar dagegen spricht, sind zurückgegebene Objekte konstant. Im Falle der
 81 /// Iteratormethoden wird hierbei den Vorgaben des C++-Standards widersprochen. Dies sollte jedoch
 82 /// in realem Code keine Probleme bereiten.
 83 ///
 84 /// Funktionen des C++-Standard werden zunächst mittels <code>using</code>-Deklaration verfügbar
 85 /// gemacht und dann ohne Qualifizierer aufgerufen, um eine parameterabhängige Namenssuche für
 86 /// etwaige Spezialisierungen zu unterstützen.
 87 
 88 /// \brief Namensraum der mitrax-Bibliothek
 89 ///
 90 /// In diesem Namensraum stehen alle Komponente, welche mitrax für die Nutzung durch den
 91 /// Bibliotheksnutzer bereitstellt.
 92 namespace mitrax{
 93 
 94 /// \brief Namensraum für Hilfskonstrukte der Bibliothekskomponenten
 95 ///
 96 /// Auf Komponenten aus diesem Namensraum sollte der Bibliotheksnutzer niemals direkt zugreifen.
 97 /// Sie dienen ausschließt als Helfer für die Komponenten aus dem Namensraum mitrax. Insbesondere
 98 /// können sich Schnittstellen, welche der Nutzer nicht durch einen indirekten Zugriff zu Gesicht
 99 /// bekommt auch bei kleinen Versionssprüngen ändern. Auf derartige Änderungen muss bei einem
100 /// Update der Bibliothek nicht zwingend hingewiesen werden.
101 namespace detail{}
102 
103 /// \brief Namensraum für die Fehlerklassen von mitrax
104 ///
105 /// In diesem Namensraum stehen alle Fehlerklassen, welche von mitrax-Komponenten mittels
106 /// <code>throw</code> geworfen werden.
107 namespace error{}
108 
109 }
110 
111 #endif