HTML API: Track spans of text with (offset, length) instead of (start, end)

src/wp-includes/html-api/class-wp-html-attribute-token.php

@@ -15,6 +15,7 @@
  *
  * @access private
  * @since 6.2.0
+ * @since 6.5.0 Replaced `end` with `length` to more closely match `substr()`.
  *
  * @see WP_HTML_Tag_Processor
  */
@@ -23,6 +24,7 @@ class WP_HTML_Attribute_Token {
 	 * Attribute name.
 	 *
 	 * @since 6.2.0
+	 *
 	 * @var string
 	 */
 	public $name;
@@ -31,6 +33,7 @@ class WP_HTML_Attribute_Token {
 	 * Attribute value.
 	 *
 	 * @since 6.2.0
+	 *
 	 * @var int
 	 */
 	public $value_starts_at;
@@ -39,6 +42,7 @@ class WP_HTML_Attribute_Token {
 	 * How many bytes the value occupies in the input HTML.
 	 *
 	 * @since 6.2.0
+	 *
 	 * @var int
 	 */
 	public $value_length;
@@ -47,22 +51,43 @@ class WP_HTML_Attribute_Token {
 	 * The string offset where the attribute name starts.
 	 *
 	 * @since 6.2.0
+	 *
 	 * @var int
 	 */
 	public $start;
 
 	/**
-	 * The string offset after the attribute value or its name.
+	 * Byte length of text spanning the attribute inside a tag.
+	 *
+	 * This span starts at the first character of the attribute name
+	 * and it ends after one of three cases:
+	 *
+	 *  - at the end of the attribute name for boolean attributes.
+	 *  - at the end of the value for unquoted attributes.
+	 *  - at the final single or double quote for quoted attributes.
+	 *
+	 * Example:
+	 *
+	 *     <div class="post">
+	 *          ------------ length is 12, including quotes
+	 *
+	 *     <input type="checked" checked id="selector">
+	 *                           ------- length is 6
+	 *
+	 *     <a rel=noopener>
+	 *        ------------ length is 11
+	 *
+	 * @since 6.5.0 Replaced `end` with `length` to more closely match `substr()`.
 	 *
-	 * @since 6.2.0
 	 * @var int
 	 */
-	public $end;
+	public $length;
 
 	/**
 	 * Whether the attribute is a boolean attribute with value `true`.
 	 *
 	 * @since 6.2.0
+	 *
 	 * @var bool
 	 */
 	public $is_true;
@@ -71,20 +96,21 @@ class WP_HTML_Attribute_Token {
 	 * Constructor.
 	 *
 	 * @since 6.2.0
+	 * @since 6.5.0 Replaced `end` with `length` to more closely match `substr()`.
 	 *
 	 * @param string $name         Attribute name.
 	 * @param int    $value_start  Attribute value.
 	 * @param int    $value_length Number of bytes attribute value spans.
 	 * @param int    $start        The string offset where the attribute name starts.
-	 * @param int    $end          The string offset after the attribute value or its name.
+	 * @param int    $length       Byte length of the entire attribute name or name and value pair expression.
 	 * @param bool   $is_true      Whether the attribute is a boolean attribute with true value.
 	 */
-	public function __construct( $name, $value_start, $value_length, $start, $end, $is_true ) {
+	public function __construct( $name, $value_start, $value_length, $start, $length, $is_true ) {
 		$this->name            = $name;
 		$this->value_starts_at = $value_start;
 		$this->value_length    = $value_length;
 		$this->start           = $start;
-		$this->end             = $end;
+		$this->length          = $length;
 		$this->is_true         = $is_true;
 	}
 }

src/wp-includes/html-api/class-wp-html-span.php

@@ -18,6 +18,7 @@
  *
  * @access private
  * @since 6.2.0
+ * @since 6.5.0 Replaced `end` with `length` to more closely align with `substr()`.
  *
  * @see WP_HTML_Tag_Processor
  */
@@ -26,28 +27,30 @@ class WP_HTML_Span {
 	 * Byte offset into document where span begins.
 	 *
 	 * @since 6.2.0
+	 *
 	 * @var int
 	 */
 	public $start;
 
 	/**
-	 * Byte offset into document where span ends.
+	 * Byte length of this span.
+	 *
+	 * @since 6.5.0
 	 *
-	 * @since 6.2.0
 	 * @var int
 	 */
-	public $end;
+	public $length;
 
 	/**
 	 * Constructor.
 	 *
 	 * @since 6.2.0
 	 *
-	 * @param int $start Byte offset into document where replacement span begins.
-	 * @param int $end   Byte offset into document where replacement span ends.
+	 * @param int $start  Byte offset into document where replacement span begins.
+	 * @param int $length Byte length of span.
 	 */
-	public function __construct( $start, $end ) {
-		$this->start = $start;
-		$this->end   = $end;
+	public function __construct( $start, $length ) {
+		$this->start  = $start;
+		$this->length = $length;
 	}
 }