Merge branch 'release/2.3.0'

Release v2.3.0

Author: delphidabbler

CHANGELOG.md

@@ -8,6 +8,26 @@ From v2.0.0 all notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v2.3.0 of 2025/09/13
+
+* Updated the collection specification:
+    * Added snippet properties to enable recording of compilation results with Delphi 13 (issue [62](https://github.com/delphidabbler/code-snippets/issues/62)).
+    * Deprecated compiler results with value `W` (issue [63](https://github.com/delphidabbler/code-snippets/issues/63)).
+* Changes were made to the _Structures_ category:
+    * Added a new `TIntegerRange` advanced record (issue [56](https://github.com/delphidabbler/code-snippets/issues/56)).
+    * Fixed an error in the description of the `Range` snippet.
+    * Added a warning to the `TRangeEx` advanced record to note potentially buggy behaviour if the range lower bound is greater than the upper bound.
+* Added new `RandomString` routine to the _String Management_ category (issue [28](https://github.com/delphidabbler/code-snippets/issues/28)).
+* Added results of compiling every snippet with Delphi 13 (issue [60](https://github.com/delphidabbler/code-snippets/issues/60)).
+* Fixed bug that was preventing the `Softmax` routine in the _Mathematics_ category from compiling due to a missing unit declaration (issue [61](https://github.com/delphidabbler/code-snippets/issues/61)).
+* Changes to unit tests:
+    * Added a new DUnit test project for the _Structures_ category and added it to the _CodeSnippetsTestsXE_ project group. Unit tests for all snippets in the _Structures_ category were created (issue [58](https://github.com/delphidabbler/code-snippets/issues/58)).
+    * Added further unit tests for all snippets in the _Arrays_ category that did not already have them (issue [38](https://github.com/delphidabbler/code-snippets/issues/38)).
+    * Added unit tests for the new `RandomString` routine.
+* Documentation:
+    * Updated `tests/README.md` re the unit test changes in this release and other minor revisions.
+    * Fixed typo in `README.md`. 
+
 ## v2.2.3 of 2025/04/03
 
 * Added results of compiling with Delphi 12 for all snippets with no pre-existing compile results for that compiler (issue [#27](https://github.com/delphidabbler/code-snippets/issues/27)).

README.md

@@ -36,7 +36,7 @@ See the `README.md` file in the `tests` directory for full details.
 
 Releases can be found on the `releases` tab on the GitHub project page.
 
-Each release[^1] comprises three zip files, as follows (replace `X.Y.X` in the file names with the release version number):
+Each release[^1] comprises three zip files, as follows (replace `X.Y.Z` in the file names with the release version number):
 
 * `csdb-vX.Y.Z-data.zip` - Contains all the data in the collection. Required by applications that access the collection.
 * `csdb-vX.Y.Z-docs.zip` - Contains the documentation developers need to understand the structure of the data.

collection/706.dat

@@ -0,0 +1,261 @@
+type
+  TIntegerRange = record
+  strict private
+    var
+      fLowerBound: Integer;
+      fUpperBound: Integer;
+    function GetLowerBound: Integer;
+    function GetUpperBound: Integer;
+    function IsSubrangeOf(const ARange: TIntegerRange): Boolean;
+  public
+    // Constructs a range whose bounds are A and B. The lowest of the two
+    // parameters is taken as the lower bound of the range with the other
+    // parameter taken as the upper bound.
+    // Valid bounds must fall in the range -MaxInt..MaxInt. An
+    // EArgumentException exception is raised otherwise.
+    constructor Create(const A, B: Integer);
+
+    // Constructs an empty range.
+    class function CreateEmpty: TIntegerRange; static;
+
+    // Checks if the range is empty.
+    function IsEmpty: Boolean;
+
+    // Returns the length of the range, i.e. the number of integers in the range.
+    function Length: Cardinal;
+
+    // Constrains AValue to fall within this range. If the value lies within the
+    // range it is returned unchanged. If it is outside the range then either
+    // LowerBound or UpperBound is returned, depending on whether the value
+    // falls below or above the range, respectively.
+    // An EInvalidOpException exception is raised if the range is empty.
+    function Constrain(const AValue: Integer): Integer;
+
+    // Checks if this range overlaps with ARange, i.e. the interection of the
+    // ranges is non empty. Empty ranges cannot overlap with any range.
+    function OverlapsWith(const ARange: TIntegerRange): Boolean;
+
+    // Checks if this range is immediately adjacent to ARange, with no overlap.
+    // Empty ranges are never contiguous with other ranges or themselves.
+    function IsContiguousWith(const ARange: TIntegerRange): Boolean;
+
+    // Checks if the set of all values in this range and ARange form a
+    // continuous sequence. This implies that a range is continuous with itself.
+    // Since adding an empty range to a non-empty range doesn't change the
+    // non-empty range we define empty ranges to be continuous with any range.
+    function IsContinuousWith(const ARange: TIntegerRange): Boolean;
+
+    // Checks if ranges A and B are the same
+    class operator Equal(const A, B: TIntegerRange): Boolean;
+
+    // Checks if ranges A and B are not the same
+    class operator NotEqual(const A, B: TIntegerRange): Boolean;
+
+    // Checks if range A is contained in, or is the same as, range B.
+    // An empty range is deemed to be contained in any other range.
+    class operator LessThanOrEqual(const A, B: TIntegerRange): Boolean;
+
+    // Checks if range A is contains, or is the same as, range B.
+    // A non-empty range is never contained in an empty range.
+    class operator GreaterThanOrEqual(const A, B: TIntegerRange): Boolean;
+
+    // Combine two ranges, A and B. The result is the smallest range that
+    // contains both A and B.
+    // If A and B are not continuous the resulting range will contain values
+    // that were not in either A or B.
+    // Combining any range either with itself or with an empty range is a no-op.
+    class operator Add(const A, B: TIntegerRange): TIntegerRange;
+
+    // Returns a range that is the intersection of ranges A and B.
+    // Returns an empty range if A and B do not overlap.
+    class operator Multiply(const A, B: TIntegerRange): TIntegerRange;
+
+    // Checks if integer AValue is contained within range ARange.
+    class operator In(const AValue: Integer; const ARange: TIntegerRange):
+      Boolean;
+
+    // Implicitly casts ARange to a string. If ARange is non-empty the string
+    // has format [X..Y], where X and Y are the lower and upper bounds of
+    // ARange respectively. If ARange is empty then [] is returned.
+    // This means that ARange can be assigned directly to a string.
+    class operator Implicit(const ARange: TIntegerRange): string;
+
+    // Explicitly casts ARange to a string. If ARange is non-empty the string
+    // has format [X..Y], where X and Y are the lower and upper bounds of
+    // ARange respectively. If ARange is empty then [] is returned.
+    // This means that ARange can be explicitly cast to a string using
+    // string(ARange).
+    class operator Explicit(const ARange: TIntegerRange): string;
+
+    // The lower bound of a non-empty range.
+    // EInvalidOpException is raised if the property is read when the range is
+    // empty.
+    property LowerBound: Integer read GetLowerBound;
+
+    // The upper bound of a non-empty range.
+    // EInvalidOpException is raised if the property is read when the range is
+    // empty.
+    property UpperBound: Integer read GetUpperBound;
+  end;
+
+class operator TIntegerRange.Add(const A, B: TIntegerRange): TIntegerRange;
+begin
+  if A.IsEmpty then
+    Exit(B);
+  if B.IsEmpty then
+    Exit(A);
+  Result := TIntegerRange.Create(
+    Math.Min(A.fLowerBound, B.fLowerBound),
+    Math.Max(A.fUpperBound, B.fUpperBound)
+  );
+end;
+
+function TIntegerRange.Constrain(const AValue: Integer): Integer;
+begin
+  if IsEmpty then
+    raise Sysutils.EInvalidOpException.Create(
+      'TIntegerRange.Constrain not valid for an empty range.'
+    );
+  Result := Math.EnsureRange(AValue, fLowerBound, fUpperBound);
+end;
+
+constructor TIntegerRange.Create(const A, B: Integer);
+begin
+  // Normalise range so that smallest parameter is the lower bound
+  fLowerBound := Math.Min(A, B);
+  fUpperBound := Math.Max(A, B);
+  if fLowerBound = Low(Integer) then
+    // This restriction is required to prevent the Length method's Cardinal
+    // return value from wrapping around / overflowing
+    raise SysUtils.EArgumentException.CreateFmt(
+      'TIntegerRange.Create: Arguments must be greater than %d', [Low(Integer)]
+    );
+end;
+
+class function TIntegerRange.CreateEmpty: TIntegerRange;
+begin
+  Result.fLowerBound := High(Integer);
+  Result.fUpperBound := Low(Integer);
+end;
+
+class operator TIntegerRange.Equal(const A, B: TIntegerRange): Boolean;
+begin
+  if A.IsEmpty or B.IsEmpty then
+    Exit(A.IsEmpty and B.IsEmpty);
+  Result := (A.fLowerBound = B.fLowerBound) and (A.fUpperBound = B.fUpperBound);
+end;
+
+class operator TIntegerRange.Explicit(const ARange: TIntegerRange): string;
+begin
+  if ARange.IsEmpty then
+    Exit('[]');
+  Result := SysUtils.Format(
+    '[%d..%d]', [ARange.fLowerBound, ARange.fUpperBound]
+  );
+end;
+
+function TIntegerRange.GetLowerBound: Integer;
+begin
+  if IsEmpty then
+    raise Sysutils.EInvalidOpException.Create(
+      'TIntegerRange.LowerBound not valid for an empty range.'
+    );
+  Result := fLowerBound;
+end;
+
+function TIntegerRange.GetUpperBound: Integer;
+begin
+  if IsEmpty then
+    raise Sysutils.EInvalidOpException.Create(
+      'TIntegerRange.LowerBound not valid for an empty range.'
+    );
+  Result := fUpperBound;
+end;
+
+class operator TIntegerRange.GreaterThanOrEqual(const A, B: TIntegerRange):
+  Boolean;
+begin
+  Result := B.IsSubrangeOf(A);
+end;
+
+class operator TIntegerRange.Implicit(const ARange: TIntegerRange): string;
+begin
+  Result := string(ARange); // calls Explicit cast operator
+end;
+
+class operator TIntegerRange.In(const AValue: Integer;
+  const ARange: TIntegerRange): Boolean;
+begin
+  if ARange.IsEmpty then
+    Exit(False);
+  Result := (AValue >= ARange.fLowerBound) and (AValue <= ARange.fUpperBound);
+end;
+
+function TIntegerRange.IsContiguousWith(const ARange: TIntegerRange): Boolean;
+begin
+  if Self.IsEmpty or ARange.IsEmpty then
+    Exit(False);
+  Result := (Self + ARange).Length = (Self.Length + ARange.Length);
+end;
+
+function TIntegerRange.IsContinuousWith(const ARange: TIntegerRange): Boolean;
+begin
+  if Self.IsEmpty or ARange.IsEmpty then
+    // Empty ranges are only continuous with other empty ranges
+    Exit(True);
+  Result := IsContiguousWith(ARange) or OverlapsWith(ARange);
+end;
+
+function TIntegerRange.IsEmpty: Boolean;
+begin
+  Result := fLowerBound > fUpperBound;
+end;
+
+function TIntegerRange.IsSubrangeOf(const ARange: TIntegerRange): Boolean;
+begin
+  if ARange.IsEmpty then
+    Exit(Self.IsEmpty);
+  Result := (Self.fLowerBound >= ARange.fLowerBound)
+    and (Self.fUpperBound <= ARange.fUpperBound)
+    or Self.IsEmpty
+end;
+
+function TIntegerRange.Length: Cardinal;
+begin
+  if IsEmpty then
+    Exit(0);
+  Result := fUpperBound - fLowerBound + 1
+end;
+
+class operator TIntegerRange.LessThanOrEqual(const A, B: TIntegerRange):
+  Boolean;
+begin
+  Result := A.IsSubrangeOf(B);
+end;
+
+class operator TIntegerRange.Multiply(const A, B: TIntegerRange): TIntegerRange;
+var
+  Up, Lo: Integer;
+begin
+  if A.IsEmpty or B.IsEmpty then
+    Exit(TIntegerRange.CreateEmpty);
+  Lo := Math.Max(A.fLowerBound, B.fLowerBound);
+  Up := Math.Min(A.fUpperBound, B.fUpperBound);
+  if Lo <= Up then
+    Result := TIntegerRange.Create(Lo, Up)
+  else
+    Result := TIntegerRange.CreateEmpty;
+end;
+
+class operator TIntegerRange.NotEqual(const A, B: TIntegerRange): Boolean;
+begin
+  if A.IsEmpty or B.IsEmpty then
+    Exit(A.IsEmpty <> B.IsEmpty);
+  Result := (A.fLowerBound <> B.fLowerBound)
+    or (A.fUpperBound <> B.fUpperBound);
+end;
+
+function TIntegerRange.OverlapsWith(const ARange: TIntegerRange): Boolean;
+begin
+  Result := not (Self * ARange).IsEmpty;
+end;

collection/707.dat

@@ -0,0 +1,8 @@
+function RandomString(const SL: Classes.TStrings): string; overload;
+begin
+  if SL.Count = 0 then
+    raise SysUtils.EArgumentException.Create(
+      'RandomString called with empty string list'
+    );
+  Result := SL[Random(SL.Count)];
+end;

collection/VERSION

@@ -1 +1 @@
-2.2.3
+2.3.0