<?xml version="1.0" encoding="utf-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
====================================================================
LazUtilities
====================================================================
-->
<module name="LazUtilities">
<short>
Contains miscellaneous utility routines and variables used in the Lazarus IDE 
and LCL.
</short>
<descr>
<p>
<file>lazutilities.pas</file> is part of the <file>LazUtils</file> package.
</p>
</descr>

<!-- unresolved external references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="TypInfo"/>

<element name="TGetSkipCheckByKey">
<short>
Specifies a Boolean function type used to implement the GetSkipCheckByKey and 
SetSkipCheckByKeyProc routines.
</short>
<descr>
<p>
The function type includes the <var>AKey</var> string argument which contains 
the key value to locate in the function. TGetSkipCheckByKey is used in the 
Lazarus IDE to implement a routine which checks command line parameters for a 
language identifier.
</p>
</descr>
<version>
Added in LazUtils version 3.0.
</version>
<seealso>
<link id="GetSkipCheckByKey"/>
<link id="SetSkipCheckByKeyProc"/>
</seealso>
</element>

<element name="TStringsSortCompare">
<short>
Specifies a comparison function type for string values in a TStrings instance.
</short>
<descr>
<p>
TStringsSortCompare is an Integer function type used to compare string values 
to determine the relative sort order. The return value indicates the relative 
sort order for the compared items, and normally contains a value like the one 
returned from CompareText. For example:
</p>
<dl>
<dt>&lt;0</dt>
<dd>Item1 has a value that comes before Item2.</dd>
<dt>0</dt>
<dd>Item1 and Item2 have the same value.</dd>
<dt>&gt;0</dt>
<dd>Item1 has a value that comes after Item2.</dd>
</dl>
<p>
The address for a TStringsSortCompare type is passed as an argument to the 
MergeSort routine.
</p>
</descr>
<version>
Added in LazUtils version 4.0. Replaces the TStringsSortCompare type in the 
<file>lclproc.pas</file> unit (<b>LCL</b>).
</version>
<seealso>
<link id="MergeSort"/>
</seealso>
</element>
<element name="TStringsSortCompare.Result">
<short>Integer with the relative sort order for the compared values.</short>
</element>
<element name="TStringsSortCompare.Item1">
<short>First string value for the comparison.</short>
</element>
<element name="TStringsSortCompare.Item2">
<short>Second string value for the comparison.</short>
</element>

<element name="GetSkipCheckByKey">
<short>
Gets and executes the function assigned to an implementation variable using 
the specified argument.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>
<element name="GetSkipCheckByKey.Result">
<short>
<b>True</b> if a function was assigned to the implementation variable, 
executed in the routine, and returned <b>True</b>. Otherwise, <b>False</b>.
</short>
</element>
<element name="GetSkipCheckByKey.AKey">
<short>
Value
</short>
</element>

<element name="SetSkipCheckByKeyProc">
<short>
Sets the value for an implementation variable to the specified function.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>
<element name="SetSkipCheckByKeyProc.AProc">
<short>
Function type assigned to the implementation variable.
</short>
</element>

<element name="FreeThenNil">
<short>
Ensures that the specified object instance is freed and set to Nil.
</short>
<descr>
<var>FreeThenNil</var> is a procedure used to ensure that the object instance 
in <var>obj</var> is freed and set to Nil. If obj has been assigned, it is 
cast to a <var>TObject</var> instance and its Free method is called. Finally, 
the pointer to the address in obj is set to Nil.
</descr>
<seealso/>
</element>
<element name="FreeThenNil.obj">
<short>Object instance modified in the routine.</short>
</element>

<element name="ComparePointers">
<short>Gets the relative order for the specified Pointers.</short>
<descr>
<p>
<var>ComparePointers</var> is an <var>Integer</var> function used to get the 
relative order for the specified Pointer values. The following return values 
are used in the routine:
</p>
<dl>
<dt>1</dt>
<dd>Returned when p1 &gt; p2.</dd>
<dt>0</dt>
<dd>Returned when p1 = p2.</dd>
<dt>-1</dt>
<dd>Returned when p1 &lt; p2.</dd>
</dl>
</descr>
<seealso/>
</element>
<element name="ComparePointers.Result">
<short>
Numeric value with the relative order for the compared Pointers.
</short>
</element>
<element name="ComparePointers.p1">
<short>Pointer compared in the routine.</short>
</element>
<element name="ComparePointers.p2">
<short>Pointer compared in the routine.</short>
</element>

<element name="CompareBoolean">
<short>Compares the specified Boolean values.</short>
<descr>
<dl>
<dt>0</dt>
<dd>Returned when b1 and b2 have the same value.</dd>
<dt>1</dt>
<dd>Returned when b1 is <b>True</b>.</dd>
<dt>-1</dt>
<dd>Returned as the default value (when b1 is <b>False</b>).</dd>
</dl>
</descr>
<seealso/>
</element>
<element name="CompareBoolean.Result">
<short>Numeric value for the comparison.</short>
</element>
<element name="CompareBoolean.b1">
<short>Boolean value compared in the routine.</short>
</element>
<element name="CompareBoolean.b2">
<short>Boolean value compared in the routine.</short>
</element>

<element name="GetEnumValueDef">
<short>
Gets the ordinal position for an enumeration value with the specified name.
</short>
<descr>
<p>
<var>GetEnumValueDef</var> is an <var>Integer</var> function used to get the 
ordinal position in the specified enumeration type insformation for the value 
with the given name.
</p>
<p>
The return value contains the ordinal position in <var>TypeInfo</var> for the 
enumeration value with the given <var>Name</var>. GetEnumValueDef calls 
<var>GetEnumValue</var> to find the value in Name in the type information. If 
the return value is <b>-1</b>, an enumeration value with the specified name 
is not found in TypeInfo and the value in <var>DefaultValue</var> is used as 
the return value.
</p>
</descr>
<seealso>
<link id="#rtl.typinfo.GetEnumValue">GetEnumValue</link>
<link id="#rtl.typinfo.PTypeInfo">PTypeInfo</link>
</seealso>
</element>
<element name="GetEnumValueDef.Result">
<short>
Ordinal position for the enumeration value with the specified name.
</short>
</element>
<element name="GetEnumValueDef.TypeInfo">
<short>Pointer to the type information examined in the routine.</short>
</element>
<element name="GetEnumValueDef.Name">
<short>Name for the enumeration value to locate in TypeInfo.</short>
</element>
<element name="GetEnumValueDef.DefaultValue">
<short>
Default ordinal position for the enumeration value used when Name is not 
found.
</short>
</element>

<element name="RoundToInt">
<short>Rounds the specified Extended value to an Integer value.</short>
<descr>
<p>
Calls <var>Round</var> to round the <var>Extended</var> value, and casts the 
result to the <var>Integer</var> type used as the return value.
</p>
</descr>
<seealso/>
</element>
<element name="RoundToInt.Result">
<short>Integer value for the rounded numeric value.</short>
</element>
<element name="RoundToInt.e">
<short>Extended type rounded and converted in the routine.</short>
</element>

<element name="RoundToCardinal">
<short>Rounds the specified Extended value to a Cardinal value.</short>
<descr>
<p>
Calls <var>Round</var> to round the <var>Extended</var> value, and casts the 
result to the <var>Cardinal</var> type used as the return value.
</p>
</descr>
<seealso/>
</element>
<element name="RoundToCardinal.Result">
<short>Cardinal value for the rounded numeric value.</short>
</element>
<element name="RoundToCardinal.e">
<short>Extended type rounded and converted in the routine.</short>
</element>

<element name="TruncToInt">
<short>Truncates the extended value and returns an Integer type.</short>
<descr/>
<seealso/>
</element>
<element name="TruncToInt.Result">
<short>Integer type with the truncated value.</short>
</element>
<element name="TruncToInt.e">
<short>Extended value truncated and converted in the routine.</short>
</element>

<element name="TruncToCardinal">
<short>Truncates the extended value and returns a Cardinal type.</short>
<descr/>
<seealso/>
</element>
<element name="TruncToCardinal.Result">
<short>Cardinal type with the truncated value.</short>
</element>
<element name="TruncToCardinal.e">
<short>Extended value truncated and converted in the routine.</short>
</element>

<element name="StrToDouble">
<short>Converts the specified string value to a Double type.</short>
<descr>
<p>
Calls <var>StrToFloat</var> to convert the value in <var>s</var>, and casts 
the result to the <var>Double</var> data type used as the return value.
</p>
</descr>
<seealso/>
</element>
<element name="StrToDouble.Result">
<short>Double type with the converted value.</short>
</element>
<element name="StrToDouble.s">
<short>String value converted in the routine.</short>
</element>

<element name="CreateFirstIdentifier">
<short>
Gets the name for the first identifier represented by the value specified in 
Identifier.
</short>
<descr>
<p>
<var>CreateFirstIdentifier</var> removes any numeric characters found at the 
end of <var>Identifier</var>, and replaces them with the value '1'.
</p>
<p>
For example:
</p>
<code>
AIdent := CreateFirstIdentifier('Edit9');
// AIdent = 'Edit1'
</code>
<p>
CreateFirstIdentifier is used to implement code macros, key mappings, and menu 
items in the Lazarus IDE.
</p>
<p>
Use CreateNextIdentifier to get the next name for a specified identifier value.
</p>
</descr>
<version>
Added in LazUtils version 4.0. Replaces the CreateFirstIdentifier routine in 
the <file>lclproc.pas</file> unit (<b>LCL</b>).
</version>
<seealso>
<link id="CreateNextIdentifier"/>
</seealso>
</element>
<element name="CreateFirstIdentifier.Result">
<short>
First identifier name for the value specified in Identifier.
</short>
</element>
<element name="CreateFirstIdentifier.Identifier">
<short>
Name for an identifier used as the base name in the generated value.
</short>
</element>

<element name="CreateNextIdentifier">
<short>
Gets the name for the next identifier following the value specified in 
Identifier.
</short>
<descr>
<p>
<var>CreateNextIdentifier</var> examines the value in <var>Identifier</var> to 
get the numeric characters in the suffix for the identifier name. It converts 
the digits to an Integer and increments the value. The value is converted to a 
String and appended as the numeric suffix for the base identifier name.
</p>
<p>
For example:
</p>
<code>
AIdent := CreateNextIdentifier('Edit19');
// AIdent = 'Edit20'
</code>
<p>
CreateNextIdentifier is used to implement commands, menu items, component 
editors, and design-time layouts in the Lazarus IDE.
</p>
<p>
Use CreateFirstIdentifier to get the first identifier name for a specified 
value.
</p>
</descr>
<version>
Added in LazUtils version 4.0. Replaces the CreateNextIdentifier routine in the 
<file>lclproc.pas</file> unit (<b>LCL</b>).
</version>
<seealso>
<link id="CreateFirstIdentifier"/>
</seealso>
</element>
<element name="CreateNextIdentifier.Result">
Next identifier name for the value specified in Identifier.
</element>
<element name="CreateNextIdentifier.Identifier">
<short>
Name for an identifier with the base name and numeric suffix used to generate 
the return value.
</short>
</element>

<element name="MergeSort">
<short>Implements a merge/sort for TStrings or TFPList.</short>
<descr>
<p>
MergeSort is an overloaded routine used to implement a comparison-based sort 
routine for values in List. List can be a TStrings or TFPList instance. No 
actions are performed in the routine when List has not been assigned 
(contains <b>Nil</b>).
</p>
<p>
The StartIndex and EndIndex arguments allow the initial and final entries in 
a TFPList instance to be specified. When the values are omitted, they default 
to the first value (position 0) and the last value (Count-1) in List.
</p>
<p>
OnCompare is the comparison routine used to determine the order for the 
sorted values. It can be a TListSortCompare or TStringsSortCompare function, 
depending on the overloaded variant of the called routine.
</p>
<p>
MergeSort implements the J. von Nuemann divide-and-conquer algorithm, with an 
insertion sort used for lists with 6 or fewer elements.
</p>
</descr>
<version>
Added in LazUtils version 4.0. Replaces the MergeSort routine in the 
<file>lclproc.pas</file> unit (<b>LCL</b>).
</version>
<seealso>
<link id="TStringsSortCompare"/>
<link id="#rtl.classes.TListSortCompare">TListSortCompare</link>
</seealso>
<seealso/>
</element>
<element name="MergeSort.List">
<short>
The list of values to sort (overloaded type).
</short>
</element>
<element name="MergeSort.OnCompare">
<short>
The sort compare function used to compare items in the list.
</short>
</element>
<element name="MergeSort.StartIndex">
<short>
The initial entry in List used in the merge/sort.
</short>
</element>
<element name="MergeSort.EndIndex">
<short>
The final entry in List used in the merge/sort.
</short>
</element>

<element name="MergeSortWithLen">
<short>
Implements a merge/sort algorithm for a list of pointers with the given 
length.
</short>
<descr/>
<seealso/>
</element>
<element name="MergeSortWithLen.List">
<short>
PPointer to the list of items examined in the merge/sort routine.
</short>
</element>
<element name="MergeSortWithLen.ListLength">
<short>
PtrInt with the length for the List argument.
</short>
</element>
<element name="MergeSortWithLen.Compare">
<short>
TListSortCompare routine used to compare items for the merge/sort algorithm.
</short>
</element>

<element name="ConsoleVerbosity">
<short>Level of detail displayed in IDE console output windows.</short>
<descr>
<p>
<var>ConsoleVerbosity</var> is an Integer variable which indicates the level 
of detail output from tools like pas2js and CodeTools. ConsoleVerbosity 
enables debugger output for specific levels of detail.
</p>
<dl>
<dt>-1</dt>
<dd>Quiet</dd>
<dt>0</dt>
<dd>Normal verbosity (No debugger output)</dd>
<dt>1</dt>
<dd>Verbose (Debugger output enabled)</dd>
<dt>2</dt>
<dd>Very verbose (Debugger output enabled)</dd>
</dl>
</descr>
<seealso/>
</element>

</module>
<!-- LazUtilities -->
</package>
</fpdoc-descriptions>