/*!

@mainpage	static_container

English document is under construction. Now, Japanese and English are written together.
This library is a STL like containers. These containers never allocate memory dynamicaly. These containers' implementation is just an array. This library targets embedded programming.

@section	summary	概要 : Summary

STL コンテナが登場し、利用者が直接面倒なメモリの動的確保をすることなく、各種のコンテナを利用することが可能になった。だが、MMU の存在しないハードウェアに対してのプログラム ( 多くの場合、組み込み系のプログラム ) においては、メモリの断片化が現在においても問題であり、メモリの動的確保を無秩序に行われると、その解決が困難となる。そのため、頻繁に動的確保を行う STL コンテナの利用は組み込み分野では倦厭されることが多い。その解決のため、様々な方法が試行されているが、今もって完全な解決には至っていない。本ライブラリ static_container は、動的確保を一切行わず、静的確保によって STL 互換コンテナを実現することを目的としている。また、仮想関数などもで極力使用していないため、vector, string はそのままバイナリファイルに書き出し、読み込むことが可能である。

@section	strategy	方針 : Strategy

-# 動的確保は一切使わない
-# 仮想関数もできるだけ使用しない
-# 全てのコンテナが、ふたを開ければ「ただの配列」
-# 例外を投げず、アサートでの異常感知

@section	vector	ベクター : Vector

@see static_container::vector

std::vector の下位互換コンテナ(上位互換を目指している)。最大サイズを指定する。

@code
#include <gslib/static_container/vector.h>

using namespace gslib;
using namespace static_container;
vector< int, 10 >	c; // int のベクター ( 最大サイズ 10 )
c.max_size(); // = 10
c.size(); // = 0
c.push_back( 5 ); // 5 を末尾に挿入
c.size(); // = 1
c.pop_back(); // 削除
c.size(); // = 0
@endcode

現在、４バイトアラインにしか対応していない。

@section	list	リスト : List

@see static_container::list

std::list の下位互換コンテナ(上位互換を目指している)。最大サイズを指定する。

@code
#include <gslib/static_container/list.h>

using namespace gslib;
using namespace static_container;
list< int, 10 >	c; // int のリスト ( 最大サイズ 10 )
c.max_size(); // = 10
c.size(); // = 0
c.push_back( 5 ); // 5 を末尾に挿入
c.size(); // = 1
c.pop_back(); // 削除
c.size(); // = 0
@endcode

vector と違い、こいつはアライン問題は、大丈夫だと思う。

@section	lodge_list	間借りリスト

@see static_container::lodge_list
@see static_container::list_node_pool

list を分解し、ノードプールと、リストに切り分けた。管理側で大きなノードプールを用意し、複数のサブシステムがそのノードプールを共有して使いまわしていくために作られた。

@code
#include <gslib/static_container/lodge_list.h>

using namespace gslib;
using namespace static_container;

void test_lodge_list() {
	list_node_pool< int, 10 >	pool;
	lodge_list< int >	list0( pool );
	lodge_list< int >	list1( pool );
	lodge_list< int >	list2( pool );
	
	pool.rest(); // = 10 初期状態では、10 個余っています
	list0.push_back( 100 ); // 100 を list0 に挿入
	pool.rest(); // = 9 一つ減ります
	list0.front(); // = 100 もちろん、back も 100 になります
}
@endcode

現在、もっと良い名前を募集中！

@section	string	文字列 : String

@see static_container::string

std::string の下位互換コンテナ(上位互換を目指している)。最大サイズを指定する。最大サイズが異なるコンテナ同士の演算もサポートしている。

@code
#include <gslib/static_container/string.h>

using namespace gslib;
using namespace static_container;

string< 10 >	c; // 最大サイズ 10 の文字列
c.max_size(); // = 10
c.size(); // = 0
c.length(); // = 0 ( size() と同じ )
c.push_back( 5 ); // 5 を末尾に挿入
c.size(); // = 1
c.pop_back(); // 削除
c.size(); // = 0
"" == c; // = true ( C 文字列との比較 )
c < "a"; // = true ( C 文字列との辞書順比較 )
c = "hello"; // 文字列の代入

string< 100 >	c100( c ); // 別の型への代入
c100 = c;
c100 += c;
c100.append( c );

@endcode

@section	hash	ハッシュ : Hash

@see static_container::hash
@see static_container::list_hash

std::map の下位互換コンテナ。std::map との大きな違いは、

- コンテナではなく、コンテナアダプタ
	- 既存のコンテナを利用して実装する
- 木を作らない。常に線形検索

である。多くの場合、hash は list と組み合わせて使われることを想定しているため、最初からそれを組み合わせた list_hash というものも存在する。ほとんどの場合は、これを利用していれば、大きな問題に出会うことも無いであろう。

@code
typedef list_hash<
	int,
	int,
	10 >	int_hash;

int_hash ihash;
ihash[ 0 ] = 100;
ihash[ 5 ] = 20;

ihash.size(); // = 2
ihash[ 0 ]; // = 100
ihash[ 5 ]; // = 20
ihash[ 5 ] = 30;
30 == ihash[ 5 ]; // = 30
ihash.size(); // = 2 すでにキーが存在する場合は、サイズが増えない
@endcode

@section	future	今後の方向性 : Future

- VC 以外のコンパイラへの対応
- STL コンテナとの互換性を高める
	- resize() がないので、実装したい
	- コンストラクタが足りない
	- string の便利な関数が全く足りない
- 仮想関数のいっそうの排除
- 効率化
	- 冗長な部分、実装上の都合が垣間見える部分が目立つ
- vector へのアライン指定
- set, multi_map に対応するものも、余裕があれば対応したい

@section	dir	ディレクトリ構成 : Directories

- Code
	- ヘッダ/ソースファイル。このディレクトリにインクルードパスを通すか、インクルードパスが通ったディレクトリにこのディレクトリをコピーすることで、このライブラリを利用することができます。
	- header and source files. To use this library, you need to set INCLUDE path to this directory.
- Doc
	- ドキュメント
	- Documents
- Test
	- test cases ( Boost.Test is used )
	- テスト ( Boost.Test 利用 )

@section	env	動作確認環境 : Compile Check Environment

- WIndows 2000
- VC++ 7.1
- boost 1.31.0

このライブラリは、boost に依存しています。

@section	author	作者に関して : Author

- 名前 ( name )
	- &o
	- 安藤崇紘 ( ANDO Takahiro )
- Web サイト ( Web site )
	- http://www.game-syokunin.com/
- メールアドレス ( Mail address )
	- u235 at milk dot freemail dot ne dot jp

@section	licese	ライセンス : License

zlib/libpng license

  Copyright (C) 2004 &o

  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the authors be held liable for any damages
  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:

-# The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
-# Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
-# This notice may not be removed or altered from any source distribution.

-----------------------------------------------------------------------------------------

商用利用していただいても、改変していただいても、結構です。謝辞は必要ありませんが、レスポンスがあるとうれしいのは言うまでもありません(^^)。一応 zlib/libpng ライセンスとしておきますが、&o に被害が及ばない範囲でのパブリックドメインであると考えていただいて、差し支えありません。そのため、ライセンスは随時よりゆるいものへ変えていっています。おそらく、ある日突然厳しいライセンスを求めるものになったりはしないと思います。安心してお使いください。

法的には、上記の原文のほうが有効なので、より厳密には日本語訳よりも原文を参考にしてください。日本語訳は、http://opensource.jp/licenses/zlib-license.html から頂いてきました。

zlib/libpngライセンス ( 日本語訳 )

  Copyright (c) 2004 &o

  本ソフトウェアは「現状のまま」で、明示であるか暗黙であるかを問わず、何らの保証もなく提供されます。本ソフトウェアの使用によって生じるいかなる損害についても、作者は一切の責任を負わないものとします。
  以下の制限に従う限り、商用アプリケーションを含めて、本ソフトウェアを任意の目的に使用し、自由に改変して再頒布することをすべての人に許可します。

-# 本ソフトウェアの出自について虚偽の表示をしてはなりません。あなたがオリジナルのソフトウェアを作成したと主張してはなりません。あなたが本ソフトウェアを製品内で使用する場合、製品の文書に謝辞をれていただければ幸いですが、必須ではありません。
-# ソースを変更した場合は、そのことを明示しなければなりません。オリジナルのソフトウェアであるという虚偽の表示をしてはなりません。
-# ソースの頒布物から、この表示を削除したり、表示の内容を変更したりしてはなりません。
*/