Unit KambiClassUtils

Equivalent to FreeAndNil, but calls FreeWithContents instead of Free. Be careful — pass here only TObjectsList_Abstract descendants !

Add some strings to TStrings

Add all strings from string array to TStrings object.

wersje z IniFile : zapisuja klucze o nazwach Count i ItemXxx gdzie Xxx to numer stringa w podanej sekcji. Defaultowo zostanie przyjete count = 0.

Append to SList some directiories.

• AddPathsFromFileLines reads directiories list from given file. If the file doesn't exist or is not readable, will append nothing, without raising any error. Empty lines (only whitespace) in file are ignored.

• AddPathsFromPathList reads directiories from a list separated by PathSeparator.

• AddPathsFromEnvironmentVar reads directiories from a list in environment variable, also separated by PathSeparator. This is suitable for parsing environment variable like $PATH or $LD_LIBRARY_PATH.

All appended directories are guaranteed to end with PathDelim.

zwraca wszystkie stringi z slist sklejone separatorem.

Assuming that List is sorted, searches in log time for a Value in List. Returns -1 if not found. Very useful for simple dictionaries of words, where lookup must be fast.

Splits S by Splitter, and adds each splitted part to Strings. Splitting is done by Splitter, i.e. if N is the number of occurences of Splitter inside S, then it always adds N + 1 strings to Strings. Yes, this means that if S starts with Splitter then the first part is equal to ''. And if S ends with Splitter then the last oart is equal to ''.

Something like SVrmlEngineProgramHelpSuffix, but appends contents as a couple of lines to Strings.

Use this instead of SList.Text := S to workaround FPC 2.0.2 bug. See [http://www.freepascal.org/mantis/view.php?id=6699]

If Strings.Count is larger than MaxCount then it will delete the last strings (to make Strings.Count = MaxCount).

Free all objects within the StringList, then free and set to Nil StringList itself.

AppendStream : skopiuj cala zawartosc strumienia OwnedSourceStream do DestStream. Potem zrob OwnedSourceStream.Free (czyli OwnedSourceStream najlepiej przekazac w postaci freshly created stream, like this AppendStream(DestStream, TMyStream.Create(...))).

This simply writes Length(s) bytes starting from s[1]. Versions with "ln" append nl, end of the line marker, to this. Versions without Stream param write to StdOutStream.

reads one char from stream using ReadBuffer (so EReadError will be raised if end of stream)

StringReadUpto_NotEOS czyta strumien az do jakiegos znaku sposrod endingChars. Jezeli wczesniej napotka koniec strumienia - exception Stream Read Error. Zwrocony result nie zawiera endingChar. Wersja 2-argumentowa po prostu o nim "zapomina" - jezeli jej uzyjesz i backEndingChar = false, nie dowiesz sie jaki znak sposrod endingChars zatrzymal czytanie. Jezeli nie podasz backEndingChar to bedzie znaczylo ze nie ma go zwracac (tak samo jakbys podal false).

NOTE: not every stream can back characters - it is implemented as Seek(-1, soFromCurrent) and some streams in FCL/VCL simply raise exception when we're doing this ! This is a problem with TStream class, not with our code.

Use TPeekCharStream if you want to avoid this uncertainty, i.e. if you need functionality of StreamReadUpto_Xxx without using tricks with changing Position of the stream.

StringReadUpto_EOS czyta az napotka znak sposrod endingChars lub koniec strumienia. Zwraca endingChar = -1 w tym przypadku, jezeli endingChar <> -1 to mozesz swobodnie wziac Chr(endingChar) i masz znak ktory zakonczyl czytanie. Podobnie jako _NotEOS, zwrocony result nie zawiera endingChar.

_NotEOS wyrzuca blad EStreamReadError jezeli bedziemy stac na koncu stringa. Natomiast _EOS zwroci -1. Robia Peek czytajac znak a potem wracajac Seek(-1, soFromCurrent) a wiec aby dzialac wymagaja strumienia TStream na ktorym takie Seek jest dozwolone.

odczytaj plik ze strumienia CreateReadFileStream. CreateReadFileStream gwarantuje ze po otrzymanyn strumieniu mozna swobodnie skakac Seek'iem (czy ustawiajac Position:=) i gwarantuje ze odczyt ze strumienia bedzie buforowany (wiec mozna bez strachu o szybkosc odczytywac strumien malymi porcyjkami).

Tradycyjny strumien Delphi/FPC z modulu Classes TFileStream.Create(filename, fmOpenRead); NIE robi buforowania - jego operacje przenosza sie 1:1 na wywolania systemu operacyjnego. Pod Linuxem nawet prymitywne I/O (open/read/write) dziala szybciutko (wiem ze linux przechowuje ostatnio odczytywane dane w pamieci; przypuszcam ze plik jest po prostu zawsze odczytywany duzymi porcjami do pamieci i w zwiazku z tym nawet prymitywne IO ma jakby buforowanie), pod Windowsem proste operacje CreateFile/ReadFile/WriteFile (na ktore jest tlumaczony TFileStream) nie sa juz tak dobrze zrobione i uzywanie ponizszej proc. pod Windowsem z miejsca przyspiesza WIELE miejsc w programie i pozwala mi piszac kod czytajacy ze strumienia nie martwic sie tak bardzo o to zeby odczytywac ze strumienia duzymi porcjami. Ale oczywiscie najlepiej pod Linuxem tez uzywac ponizszej funkcji, ona bedzie zawsze "dostrojona" do aktualnego systemu operacyjnego i implementacji TFileStream.

this procedure reads GrowingStream (i.e. a stream that we can only read sequentially, no seeks allowed, and Size of the Stream cannot be queried.) and writes (appends) everything to DestStream.

It means that the only operation we do on GrowingStream is GrowingStream.Read and the only operation on DestStream is DestStream.WriteBuffer. So DestStream usually must be able to grow dynamically to accomodate any GrowingStream input size.

This procedure ends when GrowingStream ends. If ResetDestStreamPosition then at the end we do DestStream.Position := 0 (since it is usually useful and it would be easy for you to forget about it).

This is like ReadGrowingStream, but it returns read contents as a string.

read and write string as Length(s) (4 bytes) + s contents (Length(s) bytes).

Convert whole Stream to string. This changes Stream.Position to 0 and then reads Stream.Size bytes, so be sure that Stream supports these operations.

If Component = nil then it will do Component := ComponentClass.Create(Owner);

This is supposed to be TStringList that is case sensitive.

TODO: In FPC >= 2.0.0 TStringList.CaseSensitive property was added. However, TStringList.CaseSensitive should always be left false (because of a bug, see [http://www.freepascal.org/bugs/showrec.php3?ID=4698]). So with FPC 2.0.0 and 2.0.2 we can't have CaseSensitive TStringList.

I use this type to mark the places in my code that are vulnerable to this FPC bug.

Streams that wrap standard input/output/error of the program.

Note that you can't simultaneously read from StdInStream and StdInReader (see comments at TTextReader class).

Notes for Windows:

1. Under Windows when program is a GUI program then some (or all) of the variables below may be nil.

2. But they don't have to be nil. User can run a GUI program and explicitly redirect it's standard stream, e.g. cat something | my_program for stdin or my_program > output.txt for stdout. Actually some shells, like Cygwin's bash, always redirect some streams "under the mask". And then you have some of std* streams available.

   Actually FPC (and Delphi ?) RTL don't provide in such cases valid Input/Output/ErrOutput variables (because IsConsole = false). But my streams below try to obtain standard stream handles under Windows regardless of IsConsole value. So even a GUI program is able to write to stdin/stdout/stderr using these streams.

3. Unfortunately, in a GUI program under Windows you cannot depend on the fact that "StdOutStream <> nil means that stdout is actually available (because user redirected stdout etc.)". Reason ? Windows failure, as usual:

   This is tested on Windows 2000 Prof, with FPC 2.0.0 and 2.1.1 (revision 4317). When no stdout is available, StdOutStream should be nil, because GetStdHandle(STD_OUTPUT_HANDLE) should return 0. However, GetStdHandle(STD_OUTPUT_HANDLE) doesn't return 0... It returns some stupid handle (no, not INVALID_HANDLE_VALUE either) that you can't write into (trying to write returns in ERROR_INVALID_HANDLE WinAPI error). It seems that there is no way for me to check whether GetStdHandle(STD_OUTPUT_HANDLE) returned valid handle (e.g. because the program's stdout was redirected, so stdout is perfectly available) or whether it returned something unusable.

   So if you write an $apptype GUI program and you want to try to use stdout anyway, you can't just check for StdOutStream <> nil. You should also check the first write to StdOutStream for EWriteError.

   Note that GetStdHandle(STD_INPUT_HANDLE) and GetStdHandle(STD_ERROR_HANDLE) work correctly, so it should be OK to check StdInStream <> nil or StdErrStream <> nil. The only problematic one is GetStdHandle(STD_OUTPUT_HANDLE).

Streams that wrap standard input/output/error of the program.

Note that you can't simultaneously read from StdInStream and StdInReader (see comments at TTextReader class).

Notes for Windows:

1. Under Windows when program is a GUI program then some (or all) of the variables below may be nil.

2. But they don't have to be nil. User can run a GUI program and explicitly redirect it's standard stream, e.g. cat something | my_program for stdin or my_program > output.txt for stdout. Actually some shells, like Cygwin's bash, always redirect some streams "under the mask". And then you have some of std* streams available.

   Actually FPC (and Delphi ?) RTL don't provide in such cases valid Input/Output/ErrOutput variables (because IsConsole = false). But my streams below try to obtain standard stream handles under Windows regardless of IsConsole value. So even a GUI program is able to write to stdin/stdout/stderr using these streams.

3. Unfortunately, in a GUI program under Windows you cannot depend on the fact that "StdOutStream <> nil means that stdout is actually available (because user redirected stdout etc.)". Reason ? Windows failure, as usual:

   This is tested on Windows 2000 Prof, with FPC 2.0.0 and 2.1.1 (revision 4317). When no stdout is available, StdOutStream should be nil, because GetStdHandle(STD_OUTPUT_HANDLE) should return 0. However, GetStdHandle(STD_OUTPUT_HANDLE) doesn't return 0... It returns some stupid handle (no, not INVALID_HANDLE_VALUE either) that you can't write into (trying to write returns in ERROR_INVALID_HANDLE WinAPI error). It seems that there is no way for me to check whether GetStdHandle(STD_OUTPUT_HANDLE) returned valid handle (e.g. because the program's stdout was redirected, so stdout is perfectly available) or whether it returned something unusable.

   So if you write an $apptype GUI program and you want to try to use stdout anyway, you can't just check for StdOutStream <> nil. You should also check the first write to StdOutStream for EWriteError.

   Note that GetStdHandle(STD_INPUT_HANDLE) and GetStdHandle(STD_ERROR_HANDLE) work correctly, so it should be OK to check StdInStream <> nil or StdErrStream <> nil. The only problematic one is GetStdHandle(STD_OUTPUT_HANDLE).

Streams that wrap standard input/output/error of the program.

Note that you can't simultaneously read from StdInStream and StdInReader (see comments at TTextReader class).

Notes for Windows:

1. Under Windows when program is a GUI program then some (or all) of the variables below may be nil.

2. But they don't have to be nil. User can run a GUI program and explicitly redirect it's standard stream, e.g. cat something | my_program for stdin or my_program > output.txt for stdout. Actually some shells, like Cygwin's bash, always redirect some streams "under the mask". And then you have some of std* streams available.

   Actually FPC (and Delphi ?) RTL don't provide in such cases valid Input/Output/ErrOutput variables (because IsConsole = false). But my streams below try to obtain standard stream handles under Windows regardless of IsConsole value. So even a GUI program is able to write to stdin/stdout/stderr using these streams.

3. Unfortunately, in a GUI program under Windows you cannot depend on the fact that "StdOutStream <> nil means that stdout is actually available (because user redirected stdout etc.)". Reason ? Windows failure, as usual:

   This is tested on Windows 2000 Prof, with FPC 2.0.0 and 2.1.1 (revision 4317). When no stdout is available, StdOutStream should be nil, because GetStdHandle(STD_OUTPUT_HANDLE) should return 0. However, GetStdHandle(STD_OUTPUT_HANDLE) doesn't return 0... It returns some stupid handle (no, not INVALID_HANDLE_VALUE either) that you can't write into (trying to write returns in ERROR_INVALID_HANDLE WinAPI error). It seems that there is no way for me to check whether GetStdHandle(STD_OUTPUT_HANDLE) returned valid handle (e.g. because the program's stdout was redirected, so stdout is perfectly available) or whether it returned something unusable.

   So if you write an $apptype GUI program and you want to try to use stdout anyway, you can't just check for StdOutStream <> nil. You should also check the first write to StdOutStream for EWriteError.

   Note that GetStdHandle(STD_INPUT_HANDLE) and GetStdHandle(STD_ERROR_HANDLE) work correctly, so it should be OK to check StdInStream <> nil or StdErrStream <> nil. The only problematic one is GetStdHandle(STD_OUTPUT_HANDLE).