################################################################################
  Kodowanie Windows-1250, koniec wiersza CR+LF, test: Za gl ja
  Stream - Hierarchia klas strumieni
  Copyleft (C) 2007 Adam Sawicki
  Licencja: GNU LGPL
  Kontakt: mailto:sawickiap@poczta.onet.pl , http://regedit.gamedev.pl/
################################################################################


Strumienie
================================================================================

Modu Stream ustanawia hierarchi klas strumieni.

Zaoenia strumieni:

- Strumienie s wzorowane na Delphi, C# i Java, zupenie rne od tych z
biblioteki iostream w C++.

- Reprezentuj strumienie surowych danych binarnych. W przeciwiestwie do
iostream nie posiadaj adnych funkcji do zapisywania czy parsowania
(odczytywania) danych w sposb tekstowy, tj. zamiany znakw na liczby czy inne
typy.

- Strumienie nie s zaprojektowane by byy super szybkie, za to wygodne,
bezpieczne i polimorficzne. Uywaj funkcji wirtualnych, sprawdzaj wszystko i
przy kadym bdzie rzucaj wyjtki moduu Error.

- W wikszoci rodzajw strumieni kursor moe by poza zakresem. Jedynie nie
udadz si wtedy operacje zapisu i odczytu.

- Te strumienie nie nadaj si do implementacji gniazd sieciowych, poniewa
sytuacja w ktrej strumie zgasza koniec danych podczas gdy za chwil kolejna
prba odczytu moe si powie jest niezgodna z ide tych strumieni.


Organizacja strumieni
================================================================================

Wan decyzj projektow by wybr, czy osobnymi klasami powinny by
strumienie zapisu i odczytu, strumienie obsugujce i nie obsugujce kursora,
czy moe jedne i drugie albo adne. Ostatecznie dostpne s dwie bazowe klasy
strumieni:

> Stream
  Wspiera zapis i odczyt danych
> SeekableStream - dziedziczy ze Stream
  Dodatkowo wspiera sprawdzanie i zmian dugoci danych oraz pozycji kursora

Decyzja ta bya dla mnie oczywista. To czy strumie wspiera kursor, to
ewidentnie zaley od jego typu (np. strumie plikowy tak, strumie kompresji
danych nie), podczas gdy to czy strumie jest do odczytu czy do zapisu albo do
jednego i drugiego, to ju sprawa danego strumienia zalena od parametrw, z
jakimi zosta utworzony (np. czy plik ma by otwarty do zapisu czy do odczytu).


Skadniki
================================================================================

Modu definiuje nastpujce klasy:

- Stream - klasa bazowa strumieni
- SeekableStream - klasa bazowa strumieni z obsug dugoci i kursora

- CharWriter - klasa przyspieszajca zapisywanie do strumienia po znaku
- CharReader - klasa przyspieszajca odczytywanie ze strumienia po znaku

- MemoryStream - strumie do bloku pamici o staym rozmiarze
- VectorStream - strumie do samorozszerzajcego si bloku pamici
- StringStream - strumie do acucha typu string

- OverlayStream - klasa bazowa nakadek na strumienie
- CounterOverlayStream - nakadka zliczajca zapisywane i odczytywane dane
- LimitOverlayStream - nakadka ograniczajca ilo zapisywanych i odczytywanych
  danych
- MultiWriterStream - strumie zapisujcy na raz do wielu strumieni

- Hash_Calc - strumie liczcy hash
- CRC32_Calc - strumie liczcy sum kontroln CRC32
- MD5_Calc - strumie liczcy sum kontroln MD5
- XorCoder - strumie szyfrujcy i deszyfrujcy dane operacj XOR

- BinEncoder, BinDecoder - strumie kodujcy, dekodujcy dane binarne jako cig
  zer i jedynek. Szczyt bezuytecznoci :) Kady bajt zamienia na 8 znakw.
- HexEncoder, HexDecoder - strumie kodujcy, dekodujcy dane binarne jako cig
  liczb szesnastkowych. Kady bajt zamienia na 2 znaki.
- Base64Encoder, Base64Decoder - strumie kodujcy, dekodujcy dane binarne w
  formacie Base64. Kade 3 bajty zamienia na 4 znaki.

Modu Stream definiuje te struktur MD5_SUM reprezentujc sum kontroln MD5,
a take jej konwersj do i z acucha.

Inne moduy - Files i ZlibUtils - rozszerzaj hierarchi strumieni o nowe klasy.


Wasne klasy strumieni
================================================================================

Poniej jest szablon klasy strumienia.

Metody oznaczone jako [x] maj wersje oryginalne i nie trzeba ich implementowa,
eby dziaay, chyba e w strumieniu danego rodzaju da si zaimplementowa dan
metod bezporednio, eby dziaaa szybciej i lepiej.

class XXX : public SeekableStream
{
private:
	...

public:
	XXX(...);
	virtual ~XXX();

	// ======== Implementacja Stream ========
	
	virtual void Write(const void *Data, size_t Size);
	virtual void Flush(); [x, domylnie nie robi nic]
	
	virtual size_t Read(void *Out, size_t MaxLength);
	virtual void MustRead(void *Out, size_t Length); [x]
	virtual bool End(); [dopiero w Seekable ma domyln implementacj]
	virtual size_t Skip(size_t MaxLength); [x]

	// ======== Implementacja Seekable ========

	virtual size_t GetSize();
	virtual int GetPos();
	virtual void SetPos(int pos);
	virtual void SetPosFromCurrent(int pos); [x]
	virtual void SetPosFromEnd(int pos); [x]
	virtual void Rewind(); [x]
	virtual void SetSize(size_t Size);
	virtual void Truncate(); [x]
	virtual void Clear(); [x]
};

