Unit CastleUtils

Warning: this symbol is deprecated: use Generics.Collections lists and their Sort method

Sort given table of items.

Sorts items ascending, that is Arr[FirstIndex] <= ... <= Arr[LastIndex].

Parameters

Arr

Pointer to items array in memory.

ArrRecordSize

Size (in bytes) of every item. This is the size of item that will be moved around in the memory.

IsSmallerFunc

Comparison function, should return is "A < B" true.

I'm assuming here that IsSmallerFunc works like mathematical "<": it's not reflexive (IsSmallerFunc(A, A) = False), for A <> B exactly one of IsSmallerFunc(A, B) or IsSmallerFunc(B, A) is true, and it's transitive.

Note that IsSmallerFunc gets only the pointers to the items. These may be pointers to the Arr, or a pointer to internal temporary copy of some array item. So IsSmallerFunc cannot modify the item underneath (it would not work for internal copy, and also would create problems with types that need initialization/finalization since our internal copy is done using low-level memory copying.)

FirstIndex

FirstIndex and LastIndex allow you to sort only given part of the array. We don't touch items outside of this range. Note that you could achieve the effect of FirstIndex > 0 also by increasing the Arr pointer, but FirstIndex is usually more comfortable.

If FirstIndex > LastIndex, we do nothing.

ArrStride

Distance (in bytes) between array items in memory. If you don't provide it, we'll assume ArrRecordSize. ArrStride is useful if your array is interleaved with another array, and you want to keep the other data untouched by sorting.

ArrStride must be > 0, actually it must be > ArrRecordSize for sensible behavior. (Unless ArrRecordSize is 0, then ArrStride may be 0 too.).

Warning: this symbol is deprecated: use Generics.Collections lists and their Sort method

Warning: this symbol is deprecated: use Generics.Collections lists and their Sort method

Warning: this symbol is deprecated: use Generics.Collections lists and their Sort method

Current platform of the compiled application.

Note that you can also use compilations symbols: CASTLE_IOS, CASTLE_NINTENDO_SWITCH. And of course all the symbols defined by Pascal compilers: (for OS:) ANDROID, MSWINDOWS, UNIX, LINUX etc., (for CPU:) CPUX86_64, CPUI386, CPUAARCH64 etc.

Convert string to a platform name. Case (the difference between upper and lower letters) is ignored. Raises Exception on invalid platform name.

Check condition.

Exceptions raised

ECheckFailed

Raised with ErrMessage if condition TrueValue if false.

Search the array for a given value. Returns index (zero-based) or -1 if not found.

Useful for writing case as:

case ArrayPosStr(variable, [val1, val2]) of
  0 : Something1;
  1 : Something2;
  else SomethingElse;
end;

Name and version of the Pascal compiler used to compile this unit.

See also

TCastleApplicationProperties.Description

Print some common information about application, for example to use in –help command-line output.

SPlatformDescription

Describe current platform, OS, CPU.

Describe current platform, OS, CPU. This is all detected looking at compilation symbols defined when compiling this unit.

See also

TCastleApplicationProperties.Description

Print some common information about application, for example to use in –help command-line output.

SCompilerDescription

Name and version of the Pascal compiler used to compile this unit.

Warning: this symbol is deprecated: use ApplicationProperties.Description

If not TrueValue then RaiseLastOSError.

Like standard Format, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

In general this ignores locale, so also ThousandSeparator doesn't matter (conversion is done like it is #0).

Like standard FloatToStr, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

In general this ignores locale, so also ThousandSeparator doesn't matter (conversion is done like it is #0).

Like standard FloatToStr, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

In general this ignores locale, so also ThousandSeparator doesn't matter (conversion is done like it is #0).

Like standard TryStrToFloat, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

Also it doesn't Trim the argument (so whitespace around number is not tolerated), and in general ignores locale (standard StrToFloat looks at ThousandSeparator).

Like standard StrToFloat, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

Also it doesn't Trim the argument (so whitespace around number is not tolerated), and in general ignores locale (standard StrToFloat looks at ThousandSeparator).

Like standard StrToFloatDef, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

Also it doesn't Trim the argument (so whitespace around number is not tolerated), and in general ignores locale (standard StrToFloat looks at ThousandSeparator).

Nice exception description. Contains the ClassName (unless it descends from EShortErrorMessage), and the exception Message (if it descends from Exception).

Warning: this symbol is deprecated: Use Halt

Return the symlink target path. Like Libc.ReadLink or FpReadLink, but more comfortable, it returns a normal Pascal string.

Exceptions raised

EOSError

In case of any failure (non-existing FileName etc.)

Swap variables values.

Make sure the Smaller value is <= than the Larger value, by eventually swapping them.

Assign the smaller value from X, Y to Smaller variable, the other one to Larger variable.

Update value of A to be a minimum of A, B. Works like A := Min(A, B), but is marginally faster, since you don't have to do anything when A is already smaller.

Update value of A to be a maximum of A, B. Works like A := Max(A, B), but is marginally faster, since you don't have to do anything when A is already larger.

Index (0, 1 or 2) of maximum / minimum of 3 numbers.

Warning: this symbol is deprecated: Use ClampVar

Warning: this symbol is deprecated: Use ClampVar

Warning: this symbol is deprecated: Use ClampVar

Warning: this symbol is deprecated: Use ClampVar

Warning: this symbol is deprecated: Use ClampVar

Remaining 3D coordinates (0, 1 or 2) except the given coordinate, in the ascending order.

E.g. Coord = 0, then it sets First = 1 and Second = 2.

The coordinates are in ascending order, so e.g. for Coord = 1 we return First = 0, Second = 2.

Remaining 3D coordinates (0, 1 or 2) except the given coordinate, in order to cycle.

E.g. Coord = 0, then it sets First = 1 and Second = 2.

The coordinates are in order to cycle, so First = (Coord + 1) mod 3, Second = (Coord + 2) mod 3. E.g. for Coord = 1 we return First = 2, Second = 0.

Increase Value by Change, nicely wrapping in [0..MaxValue], accepting also negative Change. The final value is always in the [0..MaxValue] range, even when initial Value was outside.

Linear interpolation between two values. Returns (1-A)*L + A*H.

Linear interpolation between 2 angle values, in radians. Goes from one value to the other through a shortest path. Values are interpreted "modulo 2 * Pi", i.e. there's no difference between Angle1 = 0.1, Angle1 = 2 * Pi + 0.1, Angle1 = -2 * Pi + 0.1 etc.

Smallest multiple of Multiplicator that is still >= Value.

Largest power of 2 still <= Value. When Value = 0 returns 0.

Exponent of the largest power of 2 that it's still <= Value. Like BiggestPowerOf2, except that this returns which power of 2 it is, while BiggestPowerOf2 just returns exactly this power. Biggest2Exponent(0) = -1.

Smallest exponent such that 2ˆthis exponent is >= Value. Smallest2Exponent(0) = -1 (this is different situation than Smallest2Exponent(1), when we return 0.

Smallest power of 2 that is >= Value. Like Smallest2Exponent, except here we return 2ˆSmallest2Exponent(Value). Returns 0 when Value = 0.

Check is Value an exact power of 2.

Linearly map value from a one range to another.

Consider how SourceVal is placed in the [SourceBegin .. SourceEnd] (it may be outside of this range, it all still works OK). It has some distance to range start (SourceBegin), and some distance to range end (SourceEnd).

We want to find another number, that is identically placed in another range [DestBegin .. DestEnd].

1. Such that Distance(SourceVal, SourceBegin) / Distance(SourceVal, SourceEnd) = Distance(Result, DestBegin) / Distance(Result, DestEnd).

2. And such that it's on the same side of the range. So if SourceVal is beyond SourceEnd (that is, SourceBegin < SourceEnd < SourceVal or SourceBegin > SourceEnd > SourceVal) then the result must be similarly beyond DestEnd.

   As you can see, this works regardless if one, or both, of the ranges increase (range end is larger than range begin).

MapRangeClamped additionally at the end clamps the result to be within [DestBegin, DestEnd] range (or [DestEnd, DestBegin] range, in case DestEnd < DestBegin).

Random Float value in the given range, result is between RangeBegin and RangeEnd. Always pass arguments such that RangeBegin < RangeEnd.

Random integer value in the given range, result is always >= RangeBegin and < RangeEnd. So result is never equal to RangeEnd, this is often convenient, and makes RandomIntRange(0, N) consistent with Random(N). Always pass arguments such that RangeBegin < RangeEnd.

Random int value in the given range, result is always >= RangeBegin and <= RangeEnd. Always pass arguments such that RangeBegin <= RangeEnd.

Random -1 or +1.

Angle between a 2D line segments and OX axis. Angle 0 means that Y1 = Y2 and X2 > X1, then the angle increases as you rotate CCW. In radians.

Calculate power Base to Exponent, knowing both arguments (and so, also the result) are >= 0.

Trivial factorial with Int64 result. Beware, the results very quickly stop to fit inside Int64 range.

Better DivMod version, in case Dividend may be < 0.

This fixes lack of DivMod with negative Remainder (for FPC at least older than 2.2.4, see fpc-devel thread "Math.DivMod results should be signed" on 2006-03-21, http://www.mail-archive.com/fpc-devel@lists.freepascal.org/msg04565.html).

And workarounds faulty DivMod behavior with FPC 2.4.0, see http://bugs.freepascal.org/view.php?id=15453

Like DivMod (return result of Integer division and a remainder), but always return Remainder >= 0.

This is useful in case when Dividend < 0. Standard DivMod (and Pascal div and mod operators) return then Result rounded toward zero, and Remainder may be < 0. This procedure will return Result rounded toward negative infinity, and Remainder will always be >= 0.

Returns Ceil(A / B), but calculated faster and more precisely (without floating-point help).

Calculate Integer division and modulo on two Float arguments. Requires that A >= 0 and B > 0, and the Result is always >= 0.

Tries to secure against floating point imprecision. It's always guaranteed that Remainder >= 0 and <= B (and usually should be < B, but this cannot be guaranteed).

Calculate Float modulo of division on two Float arguments. Works for any A (lesser than zero too). Assumes that B > 0.

Tries to secure against floating point imprecision. It's always guaranteed that Remainder >= 0 and <= B (and usually should be < B, but this cannot be guaranteed).

Our version of CoTan, to workaround http://www.freepascal.org/mantis/view.php?id=9944.

Floor from Sqrt(Value).

Hermite interpolation between two values. For X changing from Edge0 to Edge1, the resulting value changes from 0 to 1, smoothly (not with a linear speed). This is useful to make nicer transition from one value to another, it often looks better than using directly Lerp or MapRange.

Just like GLSL smoothstep: http://www.khronos.org/opengles/sdk/docs/manglsl/xhtml/smoothstep.xml

Utility functions to control the endianess of Single and Double values; no support for Extended though as such values have yet to be encountered when read from a file

Remove from the FileName the last extension (including the dot). Note that if the FileName had a couple of extensions (e.g. blah.x3d.gz) this will remove only the last one. Will remove nothing if filename has no extension.

It is not adviced to use this function, better to operate on URLs and MIME types instead of filenames and extensions, see CastleURIUtils.

Extracts two last extensions from the filename, if it has two extensions. If the filename has only one extension, returns that one extension, if the filename has no extension — returns empty string, similar to ExtractFileExt.

This is useful to detect file types from filenames like model.x3d.gz, where ExtractFileExt returns only .gz. This function will return .x3d.gz.

It is not adviced to use this function, better to operate on URLs and MIME types instead of filenames and extensions, see CastleURIUtils.

Warning: this symbol is deprecated.

Extracts from FileName the name of file, without directory, without last extension and without any Windows drive letter.

Deprecated, since we use URLs everywhere and also because this has very low usage. Use DeleteURIExt(ExtractURIName(URL)) if you really need to.

Warning: this symbol is deprecated.

Returns FileName with directory (path) part replaced with given NewPath. NewPath must contain trailing PathDelim.

Deprecated, since we use URLs everywhere and also because this has very low usage.

Include / exclude the last path delimiter, if necessary. These are just comfortable shorter names for IncludeTrailingPathDelimiter and ExcludeTrailingPathDelimiter.

For Delphi, we also fix treatment of slash on Windows: it should be treated as a path delimiter, as Windows accepts both slashes and backslashes.

Check is the given Path absolute.

Path may point to directory or normal file, it doesn't matter. Also it doesn't matter whether Path ends with PathDelim or not.

Note for Windows: while it's obvious that 'c:\autoexec.bat' is an absolute path, and 'autoexec.bat' is not, there's a question whether path like '\autoexec.bat' is absolute? It doesn't specify drive letter, but it does specify full directory hierarchy on some drive. This function treats this as not absolute, on the reasoning that "not all information is contained in Path".

See also

IsPathAbsoluteOnDrive

Just like IsPathAbsolute, but on Windows accepts also paths that specify full directory tree without drive letter.

Just like IsPathAbsolute, but on Windows accepts also paths that specify full directory tree without drive letter.

See also

IsPathAbsolute

Check is the given Path absolute.

Checks is the directory name special, like "." or "..".

The precise definition of "special" is that you cannot ever create or even have any filenames / directories named like this.

Add Suffix to the filename, right before extension. Returns DeleteFileExt(FileName) + Suffix + ExtractFileExt(FileName).

Pointer arithmetic. Will wrap over if you add too much. Add may be negative. This is just a shortcut for PtrInt(Result) := PtrInt(P)+Add, without any range / overflow checks.

Safer version of FreeMem, checks is parameter Nil, and sets it to Nil afterwards.

Check is memory filled with the given character. Returns -1 is True, or the number (between 0 .. Size - 1) or the first character different than AChar.

Check is memory filled with the given character. Returns simple boolean, use CheckIsMemCharFilled to get more informative result.

Check is memory filled with the Word (2 byte sequence). Size if the number of words (not bytes), this is consequent with Size parameter from FillWord from FPC's RTL.

Check is memory filled with the DWord (4 byte sequence). Size if the number of dwords (not bytes), this is consequent with Size parameter from FillDWord from FPC's RTL.

Calculate shift between A and B addresses (in bytes). Useful to pass as offsets to methods like TGLSLAttribute.EnableArray that wrap OpenGL vertex-array API. This is simply Result := A - B, except we do some typecasting.

Warning: this symbol is deprecated: use SameMethods

Compare two methods.

Write using a dialog box or console.

If we are a Windows GUI program (not IsConsole) then we use native Windows dialog boxes. Otherwise (a console is available, which is always true on non-Windows) we output the message using simple Writeln (to standard output for InfoWrite, or ErrOutput for ErrorWrite and WarningWrite).

Warning: this symbol is deprecated.

Output messages, using console or dialog box.

If we're not on Windows or IsConsole, then we simply output Messages using Writeln.

If we're on Windows and not IsConsole, then every Messages is displayed in a separate dialog box. Dialog box uses our InfoBox routine, with Messages[I] being message content and title being Format(TitleFormat, [I + 1, Messages.Count]).

This is good for outputting a lot of information.

Deprecated. This just looks ugly in GUI version. It's better to present long information using only a console (just use Writeln), or only a full-featured GUI (like Lazarus LCL or our CastleUIControls).

Floating-point type with best precision.

Pointer to a boolean. Defined as ˆByte in some Delphi Windows unit, for FPC 1.0.x PBoolean is not available at all.

Infinite array of bytes.

Pointer to TObject. Don't call this PObject or PTObject to avoid possible name clashes with other units (pointers are often used in situations that prevent good type-checking, so better to avoid name clashes to avoid some nasty errors).

Size (signed) used for various list types Count, Capacity, index variables.

Delphi uses Integer for this. FPC uses SizeInt for this (which may have larger size than Integer, FPC docs say it is matching pointer size, so 64-bit on 64-bit platforms).

Possible platforms supported by CGE. See Platform.

Values

• cpDesktop
• cpAndroid
• cpIOS
• cpNintendoSwitch

Simple notify event with no Sender

Warning: this symbol is deprecated: use EShortErrorMessage

Index of axis in 3D.

When should the complicated sorting algorithm fallback to a simpler one. If number of items is <= CountToUseSimpleSort, then Sort will fallback to SimpleSort (= sort by choosing for now) instead of recursive QuickSort. Set CountToUseSimpleSort = 0 to make it never fall back to SimpleSort.

By default this is DefaultCountToUseSimpleSort.

New line sequence, suitable for current OS. Short name for LineEnding.

Castle Game Engine version.

Pi / 2.

Pi * 2.

Root dir name. Empty if not applicable to this OS.

Are we inside Castle Game Engine designer mode, or (possible in case of TCastleControl) in Lazarus/Delphi form designer.