diff --git a/CHANGELOG.md b/CHANGELOG.md
index 88e792ea..00277ca8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
All Notable changes to `Csv` will be documented in this file
-## [Next](https://github.com/thephpleague/csv/compare/9.17.0...master) - TBD
+## [9.18.0](https://github.com/thephpleague/csv/compare/9.17.0...9.18.0) - 2024-10-18
### Added
@@ -12,6 +12,7 @@ All Notable changes to `Csv` will be documented in this file
### Deprecated
- `League\Csv\AbstractCsv::output` use `League\Csv\AbstractCsv::download` instead
+- `League\Csv\FragmentFinder` and derived methods are marked as **experimental** as their results will be changed in the next major version.
### Fixed
diff --git a/docs/9.0/reader/statement.md b/docs/9.0/reader/statement.md
index 1ba8766a..1043834f 100644
--- a/docs/9.0/reader/statement.md
+++ b/docs/9.0/reader/statement.md
@@ -409,6 +409,10 @@ documents or `TabularDataReader` instances if needed.
## FragmentFinder
This mechanism is introduced with version 9.12.0
.
+This implementation is marked as experimetal since version 9.12.0
.
+The public API is stable but the implementation and returned value will change in the next version to
+take into account edge cases and improve error and selection handling. It is recommended to avoid using
+the current implementation or restrict its usage for simple selection in version 9.
The second mechanism is based on [RFC7111](https://www.rfc-editor.org/rfc/rfc7111) and allow selecting
part of your document according to its rows, columns or cells coordinates. The RFC, and thus, our class
diff --git a/src/FragmentFinder.php b/src/FragmentFinder.php
index d0bc54c0..51178fd8 100644
--- a/src/FragmentFinder.php
+++ b/src/FragmentFinder.php
@@ -25,7 +25,11 @@
use const FILTER_VALIDATE_INT;
/**
+ * EXPERIMENTAL WARNING! This class implementation will change in the next major point release.
+ *
* @phpstan-type selection array{selection:string, start:int<-1, max>, end:?int, length:int, columns:array}
+ *
+ * @experimental
*/
class FragmentFinder
{
@@ -42,8 +46,13 @@ public static function create(): self
}
/**
- * @throws SyntaxError
+ * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
*
+ * Extract all found fragment identifiers for the specifield tabular data
+ *
+ * @experimental since version 9.12.0
+ *
+ * @throws SyntaxError
* @return iterable
*/
public function findAll(string $expression, TabularDataReader $tabularDataReader): iterable
@@ -52,6 +61,12 @@ public function findAll(string $expression, TabularDataReader $tabularDataReader
}
/**
+ * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+ *
+ * Extract the first found fragment identifier of the tabular data or returns null
+ *
+ * @experimental since version 9.12.0
+ *
* @throws SyntaxError
*/
public function findFirst(string $expression, TabularDataReader $tabularDataReader): ?TabularDataReader
@@ -65,6 +80,12 @@ public function findFirst(string $expression, TabularDataReader $tabularDataRead
}
/**
+ * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+ *
+ * Extract the first found fragment identifier of the tabular data or fail
+ *
+ * @experimental since version 9.12.0
+ *
* @throws SyntaxError
* @throws FragmentNotFound if the expression can not be parsed
*/
diff --git a/src/Reader.php b/src/Reader.php
index d41e63f3..5168d1c8 100644
--- a/src/Reader.php
+++ b/src/Reader.php
@@ -411,17 +411,42 @@ public function sorted(Query\Sort|Closure $orderBy): TabularDataReader
return Statement::create()->orderBy($orderBy)->process($this);
}
+ /**
+ * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+ *
+ * Extract all found fragment identifiers for the specifield tabular data
+ *
+ * @experimental since version 9.12.0
+ *
+ * @throws SyntaxError
+ * @return iterable
+ */
public function matching(string $expression): iterable
{
return FragmentFinder::create()->findAll($expression, $this);
}
+ /**
+ * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+ *
+ * Extract the first found fragment identifier of the tabular data or returns null
+ *
+ * @experimental since version 9.12.0
+ *
+ * @throws SyntaxError
+ */
public function matchingFirst(string $expression): ?TabularDataReader
{
return FragmentFinder::create()->findFirst($expression, $this);
}
/**
+ * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+ *
+ * Extract the first found fragment identifier of the tabular data or fail
+ *
+ * @experimental since version 9.12.0
+ *
* @throws SyntaxError
* @throws FragmentNotFound
*/
diff --git a/src/ResultSet.php b/src/ResultSet.php
index bfde262d..013d0424 100644
--- a/src/ResultSet.php
+++ b/src/ResultSet.php
@@ -259,17 +259,42 @@ public function select(string|int ...$columns): TabularDataReader
return new self(new MapIterator($this, $callback), $hasHeader ? $header : []);
}
+ /**
+ * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+ *
+ * Extract all found fragment identifiers for the specifield tabular data
+ *
+ * @experimental since version 9.12.0
+ *
+ * @throws SyntaxError
+ * @return iterable
+ */
public function matching(string $expression): iterable
{
return FragmentFinder::create()->findAll($expression, $this);
}
+ /**
+ * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+ *
+ * Extract the first found fragment identifier of the tabular data or returns null
+ *
+ * @experimental since version 9.12.0
+ *
+ * @throws SyntaxError
+ */
public function matchingFirst(string $expression): ?TabularDataReader
{
return FragmentFinder::create()->findFirst($expression, $this);
}
/**
+ * EXPERIMENTAL WARNING! This method implementation will change in the next major point release.
+ *
+ * Extract the first found fragment identifier of the tabular data or fail
+ *
+ * @experimental since version 9.12.0
+ *
* @throws SyntaxError
* @throws FragmentNotFound
*/