From 9737e4b259e5673b055d4c8316d4c9e2892f984b Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Mon, 23 Nov 2020 21:50:15 +0000
Subject: [PATCH] Added documentation for the str_starts_with and str_ends_with
 functions based on
 https://php.watch/versions/8.0/str_starts_with-str_ends_with

Patch contributed by Emmanuel Okeke <emmanix2002@gmail.com>.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351549 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/strings/functions/str-contains.xml  |   6 +-
 reference/strings/functions/str-ends-with.xml | 150 ++++++++++++++++++
 .../strings/functions/str-starts-with.xml     | 150 ++++++++++++++++++
 reference/strings/functions/stripos.xml       |   2 +
 reference/strings/functions/strpos.xml        |   2 +
 reference/strings/versions.xml                |   2 +
 6 files changed, 310 insertions(+), 2 deletions(-)
 create mode 100644 reference/strings/functions/str-ends-with.xml
 create mode 100644 reference/strings/functions/str-starts-with.xml

diff --git a/reference/strings/functions/str-contains.xml b/reference/strings/functions/str-contains.xml
index 0bed156aa2..7ab3098b75 100644
--- a/reference/strings/functions/str-contains.xml
+++ b/reference/strings/functions/str-contains.xml
@@ -81,7 +81,7 @@ Checking the existence of the empty string will always return true
 $string = 'The lazy fox jumped over the fence';
 
 if (str_contains($string, 'lazy')) {
-    echo "The string "lazy" was found in the string\n";
+    echo "The string 'lazy' was found in the string\n";
 }
 
 if (str_contains($string, 'Lazy')) {
@@ -96,7 +96,7 @@ if (str_contains($string, 'Lazy')) {
     &example.outputs;
     <screen role="php">
 <![CDATA[
-The string "lazy" was found in the string
+The string 'lazy' was found in the string
 "Lazy" was not found because the case does not match
 ]]>
     </screen>
@@ -113,6 +113,8 @@ The string "lazy" was found in the string
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>str_ends_with</function></member>
+    <member><function>str_starts_with</function></member>
     <member><function>stripos</function></member>
     <member><function>strrpos</function></member>
     <member><function>strripos</function></member>
diff --git a/reference/strings/functions/str-ends-with.xml b/reference/strings/functions/str-ends-with.xml
new file mode 100644
index 0000000000..5008bb098d
--- /dev/null
+++ b/reference/strings/functions/str-ends-with.xml
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.str-ends-with">
+ <refnamediv>
+  <refname>str_ends_with</refname>
+  <refpurpose>Checks if a string ends with a given substring</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>bool</type><methodname>str_ends_with</methodname>
+   <methodparam><type>string</type><parameter>haystack</parameter></methodparam>
+   <methodparam><type>string</type><parameter>needle</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Performs a case-sensitive check indicating if
+   <parameter>haystack</parameter> ends with <parameter>needle</parameter>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>haystack</parameter></term>
+     <listitem>
+      <para>
+       The string to search in.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>needle</parameter></term>
+     <listitem>
+      <para>
+       The substring to search for in the <parameter>haystack</parameter>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns &true; if <parameter>haystack</parameter> ends with
+   <parameter>needle</parameter>, &false; otherwise.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Using the empty string <literal>''</literal></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+if (str_ends_with('abc', '')) {
+    echo "All strings end with the empty string";
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+All strings end with the empty string
+]]>
+    </screen>
+   </example>
+
+   <example>
+    <title>Showing case-sensitivity</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$string = 'The lazy fox jumped over the fence';
+
+if (str_ends_with($string, 'fence')) {
+    echo "The string ends with 'fence'\n";
+}
+
+if (str_ends_with($string, 'Fence')) {
+    echo 'The string ends with "fence"';
+} else {
+    echo '"fence" was not found because the case does not match';
+}
+
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+The string ends with 'fence'
+"fence" was not found because the case does not match
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+  &reftitle.notes;
+  &note.bin-safe;
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>str_contains</function></member>
+    <member><function>str_starts_with</function></member>
+    <member><function>stripos</function></member>
+    <member><function>strrpos</function></member>
+    <member><function>strripos</function></member>
+    <member><function>strstr</function></member>
+    <member><function>strpbrk</function></member>
+    <member><function>substr</function></member>
+    <member><function>preg_match</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/strings/functions/str-starts-with.xml b/reference/strings/functions/str-starts-with.xml
new file mode 100644
index 0000000000..fe84cc2c77
--- /dev/null
+++ b/reference/strings/functions/str-starts-with.xml
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.str-starts-with">
+ <refnamediv>
+  <refname>str_starts_with</refname>
+  <refpurpose>Checks if a string starts with a given substring</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>bool</type><methodname>str_starts_with</methodname>
+   <methodparam><type>string</type><parameter>haystack</parameter></methodparam>
+   <methodparam><type>string</type><parameter>needle</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Performs a case-sensitive check indicating if
+   <parameter>haystack</parameter> begins with <parameter>needle</parameter>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>haystack</parameter></term>
+     <listitem>
+      <para>
+       The string to search in.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>needle</parameter></term>
+     <listitem>
+      <para>
+       The substring to search for in the <parameter>haystack</parameter>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns &true; if <parameter>haystack</parameter> begins with
+   <parameter>needle</parameter>, &false; otherwise.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Using the empty string <literal>''</literal></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+if (str_starts_with('abc', '')) {
+    echo "All strings start with the empty string";
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+All strings start with the empty string
+]]>
+    </screen>
+   </example>
+
+   <example>
+    <title>Showing case-sensitivity</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$string = 'The lazy fox jumped over the fence';
+
+if (str_starts_with($string, 'The')) {
+    echo "The string starts with 'The'\n";
+}
+
+if (str_starts_with($string, 'the')) {
+    echo 'The string starts with "the"';
+} else {
+    echo '"the" was not found because the case does not match';
+}
+
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+The string starts with 'The'
+"the" was not found because the case does not match
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+  &reftitle.notes;
+  &note.bin-safe;
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>str_contains</function></member>
+    <member><function>str_ends_with</function></member>
+    <member><function>stripos</function></member>
+    <member><function>strrpos</function></member>
+    <member><function>strripos</function></member>
+    <member><function>strstr</function></member>
+    <member><function>strpbrk</function></member>
+    <member><function>substr</function></member>
+    <member><function>preg_match</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/strings/functions/stripos.xml b/reference/strings/functions/stripos.xml
index 3748ffda63..6e5193c37d 100644
--- a/reference/strings/functions/stripos.xml
+++ b/reference/strings/functions/stripos.xml
@@ -144,6 +144,8 @@ if ($pos2 !== false) {
    <simplelist>
     <member><function>mb_stripos</function></member>
     <member><function>str_contains</function></member>
+    <member><function>str_ends_with</function></member>
+    <member><function>str_starts_with</function></member>
     <member><function>strpos</function></member>
     <member><function>strrpos</function></member>
     <member><function>strripos</function></member>
diff --git a/reference/strings/functions/strpos.xml b/reference/strings/functions/strpos.xml
index 3fd328ab29..9aa94c5a22 100644
--- a/reference/strings/functions/strpos.xml
+++ b/reference/strings/functions/strpos.xml
@@ -167,6 +167,8 @@ $pos = strpos($newstring, 'a', 1); // $pos = 7, not 0
    <simplelist>
     <member><function>stripos</function></member>
     <member><function>str_contains</function></member>
+    <member><function>str_ends_with</function></member>
+    <member><function>str_starts_with</function></member>
     <member><function>strrpos</function></member>
     <member><function>strripos</function></member>
     <member><function>strstr</function></member>
diff --git a/reference/strings/versions.xml b/reference/strings/versions.xml
index 21445f0788..d04b0b7896 100644
--- a/reference/strings/versions.xml
+++ b/reference/strings/versions.xml
@@ -56,6 +56,7 @@
  <function name="sprintf" from="PHP 4, PHP 5, PHP 7"/>
  <function name="sscanf" from="PHP 4 &gt;= 4.0.1, PHP 5, PHP 7"/>
  <function name="str_contains" from="PHP 8"/>
+ <function name="str_ends_with" from="PHP 8"/>
  <function name="str_getcsv" from="PHP 5 &gt;= 5.3.0, PHP 7"/>
  <function name="str_ireplace" from="PHP 5, PHP 7"/>
  <function name="str_pad" from="PHP 4 &gt;= 4.0.1, PHP 5, PHP 7"/>
@@ -64,6 +65,7 @@
  <function name="str_rot13" from="PHP 4 &gt;= 4.2.0, PHP 5, PHP 7"/>
  <function name="str_shuffle" from="PHP 4 &gt;= 4.3.0, PHP 5, PHP 7"/>
  <function name="str_split" from="PHP 5, PHP 7"/>
+ <function name="str_starts_with" from="PHP 8"/>
  <function name="str_word_count" from="PHP 4 &gt;= 4.3.0, PHP 5, PHP 7"/>
  <function name="strcasecmp" from="PHP 4, PHP 5, PHP 7"/>
  <function name="strchr" from="PHP 4, PHP 5, PHP 7"/>