From 9d08de450b30644ca6ced27e0a667d60b0ae12c7 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 7 Oct 2019 16:19:18 +0200 Subject: [PATCH] Documented the String component --- .../string/bytes-points-graphemes.png | Bin 0 -> 75459 bytes components/string.rst | 465 ++++++++++++++++++ 2 files changed, 465 insertions(+) create mode 100644 _images/components/string/bytes-points-graphemes.png create mode 100644 components/string.rst diff --git a/_images/components/string/bytes-points-graphemes.png b/_images/components/string/bytes-points-graphemes.png new file mode 100644 index 0000000000000000000000000000000000000000..18d971cecf7a625f3f68e1235721137a2f199e87 GIT binary patch literal 75459 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%0AhJ5+KUdoq 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 literal 0 HcmV?d00001 diff --git a/components/string.rst b/components/string.rst new file mode 100644 index 00000000000..51c6d83b2d4 --- /dev/null +++ b/components/string.rst @@ -0,0 +1,465 @@ +.. index:: + single: String + single: Components; String + +The String Component +==================== + + The String component provides a single object-oriented API to work with + three "unit systems" of strings: bytes, code points and grapheme clusters. + +.. versionadded:: 5.0 + + The String component was introduced in 5.0 as an + :doc:`experimental feature `. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/string + +.. include:: /components/require_autoload.rst.inc + +What is a String? +----------------- + +You can skip this section if you already know what a *"code point"* or a +*"grapheme cluster"* are in the context of handling strings. Otherwise, read +this section to learn about the terminology used by this component. + +Languages like English require a very limited set of characters and symbols to +display any content. Each string is a series of characters (letters or symbols) +and they can be encoded even with the most limited standards (e.g. `ASCII`_). + +However, other languages require thousands of symbols to display their contents. +They need complex encoding standards such as `Unicode`_ and concepts like +"character" no longer make sense. Instead, you have to deal with these terms: + +* `Code points`_: they are the atomic unit of information. A string is a series + of code points. Each code point is a number whose meaning is given by the + `Unicode`_ standard. For example, the English letter ``A`` is the ``U+0041`` + code point and the Japanese *kana* ``の`` is the ``U+306E`` code point. +* `Grapheme clusters`_: they are a sequence of one or more code points which are + displayed as a single graphical unit. For example, the Spanish letter ``ñ`` is + a grapheme cluster that contains two code points: ``U+006E`` = ``n`` (*"latin + small letter N"*) + ``U+0303`` = ``◌̃`` (*"combining tilde"*). +* Bytes: they are the actual information stored for the string contents. Each + code point can require one or more bytes of storage depending on the standard + being used (UTF-8, UTF-16, etc.). + +The following image displays the bytes, code points and grapheme clusters for +the same word written in English (``hello``) and Hindi (``नमस्ते``): + +.. image:: /_images/components/string/bytes-points-graphemes.png + :align: center + +Usage +----- + +Create a new object of type :class:`Symfony\\Component\\String\\ByteString`, +:class:`Symfony\\Component\\String\\CodePointString` or +:class:`Symfony\\Component\\String\\UnicodeString`, pass the string contents as +their arguments and then use the object-oriented API to work with those strings:: + + use Symfony\Component\String\UnicodeString; + + $text = (new UnicodeString('This is a déjà-vu situation.')) + ->trimEnd('.') + ->replace('déjà-vu', 'jamais-vu') + ->append('!'); + // $text = 'This is a jamais-vu situation!' + + $content = new UnicodeString('नमस्ते दुनिया'); + if ($content->ignoreCase()->startsWith('नमस्ते')) { + // ... + } + +Method Reference +---------------- + +Methods to Create String Objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, you can create objects prepared to store strings as bytes, code points +and grapheme clusters with the following classes:: + + use Symfony\Component\String\ByteString; + use Symfony\Component\String\CodePointString; + use Symfony\Component\String\UnicodeString; + + $foo = new ByteString('hello'); + $bar = new CodePointString('hello'); + // UnicodeString is the most commonly used class + $baz = new UnicodeString('hello'); + +Use the ``wrap()`` static method to instantiate more than one string object:: + + $contents = ByteString::wrap(['hello', 'world']); // $contents = ByteString[] + $contents = UnicodeString::wrap(['I', '❤️', 'Symfony']); // $contents = UnicodeString[] + + // use the unwrap method to make the inverse conversion + $contents = UnicodeString::unwrap([ + new UnicodeString('hello'), new UnicodeString('world'), + ]); // $contents = ['hello', 'world'] + +There are two shortcut functions called ``b()`` and ``u()`` to create +``ByteString`` and ``UnicodeString`` objects:: + + // ... + use function Symfony\Component\String\b; + use function Symfony\Component\String\u; + + // both are equivalent + $foo = new ByteString('hello'); + $foo = b('hello'); + + // both are equivalent + $baz = new UnicodeString('hello'); + $baz = u('hello'); + +There are also some specialized constructors:: + + // ByteString can create a random string of the given length + $foo = ByteString::fromRandom(12); + + // CodePointString and UnicodeString can create a string from code points + $foo = UnicodeString::fromCodePoints(0x928, 0x92E, 0x938, 0x94D, 0x924, 0x947); + // $foo = 'नमस्ते' + +Methods to Transform String Objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each string object can be transformed into the other two types of objects:: + + $foo = ByteString::fromRandom(12)->toCodePointString(); + $foo = (new CodePointString('hello'))->toUnicodeString(); + $foo = UnicodeString::fromCodePoints(0x68, 0x65, 0x6C, 0x6C, 0x6F)->toByteString(); + + // the optional $toEncoding argument defines the encoding of the target string + $foo = (new CodePointString('hello'))->toByteString('Windows-1252'); + // the optional $fromEncoding argument defines the encoding of the original string + $foo = (new ByteString('さよなら'))->toCodePointString('ISO-2022-JP'); + +If the conversion is not possible for any reason, you'll get an +:class:`Symfony\\Component\\String\\Exception\\InvalidArgumentException`. + +Methods Related to Length and White Spaces +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + // returns the number of graphemes, code points or bytes of the given string + $word = 'नमस्ते'; + (new ByteString($word))->length(); // 18 (bytes) + (new CodePointString($word))->length(); // 6 (code points) + (new UnicodeString($word))->length(); // 4 (graphemes) + + // some symbols require double the width of others to represent them when using + // a monospaced font (e.g. in a console). This method returns the total width + // needed to represent the entire word + $word = 'नमस्ते'; + (new ByteString($word))->width(); // 18 + (new CodePointString($word))->width(); // 4 + (new UnicodeString($word))->width(); // 4 + // if the text contains multiple lines, it returns the max width of all lines + $text = "<<width(); // 14 + + // only returns TRUE if the string is exactly an empty string (not even white spaces) + u('hello world')->isEmpty(); // false + u(' ')->isEmpty(); // false + u('')->isEmpty(); // true + + // removes all white spaces from the start and end of the string and replaces two + // or more consecutive white spaces inside contents by a single white space + u(" \n\n hello world \n \n")->collapseWhitespace(); // 'hello world' + +Methods to Change Case +~~~~~~~~~~~~~~~~~~~~~~ + +:: + + // changes all graphemes/code points to lower case + u('FOO Bar')->lower(); // 'foo bar' + + // when dealing with different languages, uppercase/lowercase is not enough + // there are three cases (lower, upper, title), some characters have no case, + // case is context-sensitive and locale-sensitive, etc. + // this method returns a string that you can use in case-insensitive comparisons + u('FOO Bar')->folded(); // 'foo bar' + u('Die O\'Brian Straße')->folded(); // "die o'brian strasse" + + // changes all graphemes/code points to upper case + u('foo BAR')->upper(); // 'FOO BAR' + + // changes all graphemes/code points to "title case" + u('foo bar')->title(); // 'Foo bar' + u('foo bar')->title(true); // 'Foo Bar' + + // changes all graphemes/code points to camelCase + u('Foo: Bar-baz.')->camel(); // 'fooBarBaz' + // changes all graphemes/code points to snake_case + u('Foo: Bar-baz.')->snake(); // 'foo_bar_baz' + // other cases can be achieved by chaining methods. E.g. PascalCase: + u('Foo: Bar-baz.')->camel()->title(); // 'FooBarBaz' + +The methods of all string classes are case-sensitive by default. You can perform +case-insensitive operations with the ``ignoreCase()`` method:: + + u('abc')->indexOf('B'); // null + u('abc')->ignoreCase()->indexOf('B'); // 1 + +Methods to Append and Prepend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + // adds the given content (one or more strings) at the beginning/end of the string + u('world')->prepend('hello'); // 'helloworld' + u('world')->prepend('hello', ' '); // 'hello world' + + u('hello')->append('world'); // 'helloworld' + u('hello')->append(' ', 'world'); // 'hello world' + + // adds the given content at the beginning of the string (or removes it) to + // make sure that the content starts exactly with that content + u('Name')->ensureStart('get'); // 'getName' + u('getName')->ensureStart('get'); // 'getName' + u('getgetName')->ensureStart('get'); // 'getName' + // this method is similar, but works on the end of the content instead of on the beginning + u('User')->ensureEnd('Controller'); // 'UserController' + u('UserController')->ensureEnd('Controller'); // 'UserController' + u('UserControllerController')->ensureEnd('Controller'); // 'UserController' + + // returns the contents found before/after the first occurrence of the given string + u('hello world')->before('world'); // 'hello ' + u('hello world')->before('o'); // 'hell ' + u('hello world')->before('o', true); // 'hello' + + u('hello world')->after('hello'); // ' world' + u('hello world')->after('o'); // ' world' + u('hello world')->after('o', true); // 'o world' + + // returns the contents found before/after the last occurrence of the given string + u('hello world')->beforeLast('o'); // 'hello w' + u('hello world')->beforeLast('o', true); // 'hello wo' + + u('hello world')->afterLast('o'); // 'rld' + u('hello world')->afterLast('o', true); // 'orld' + +Methods to Pad and Trim +~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + // makes a string as long as the first argument by adding the given + // string at the beginning, end or both sides of the string + u(' Lorem Ipsum ')->padBoth(20, '-'); // '--- Lorem Ipsum ----' + u(' Lorem Ipsum')->padStart(20, '-'); // '-------- Lorem Ipsum' + u('Lorem Ipsum ')->padEnd(20, '-'); // 'Lorem Ipsum --------' + + // repeats the given string the number of times passed as argument + u('_.')->repeat(10); // '_._._._._._._._._._.' + + // removes the given characters (by default, white spaces) from the string + u(' Lorem Ipsum ')->trim(); // 'Lorem Ipsum' + u('Lorem Ipsum ')->trim('m'); // 'Lorem Ipsum ' + u('Lorem Ipsum')->trim('m'); // 'Lorem Ipsu' + + u(' Lorem Ipsum ')->trimStart(); // 'Lorem Ipsum ' + u(' Lorem Ipsum ')->trimEnd(); // ' Lorem Ipsum' + +Methods to Search and Replace +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + // checks if the string starts/ends with the given string + u('https://symfony.com')->startsWith('https'); // true + u('report-1234.pdf')->endsWith('.pdf'); // true + + // checks if the string contents are exactly the same as the given contents + u('foo')->equalsTo('foo'); // true + + // checks if the string content match the given regular expression + u('avatar-73647.png')->match('/avatar-(\d+)\.png/'); + // result = ['avatar-73647.png', '73647'] + + // finds the position of the first occurrence of the given string + // (the second argument is the position where the search starts and negative + // values have the same meaning as in PHP functions) + u('abcdeabcde')->indexOf('c'); // 2 + u('abcdeabcde')->indexOf('c', 2); // 2 + u('abcdeabcde')->indexOf('c', -4); // 7 + u('abcdeabcde')->indexOf('eab'); // 4 + u('abcdeabcde')->indexOf('k'); // null + + // finds the position of the last occurrence of the given string + // (the second argument is the position where the search starts and negative + // values have the same meaning as in PHP functions) + u('abcdeabcde')->indexOfLast('c'); // 7 + u('abcdeabcde')->indexOfLast('c', 2); // 7 + u('abcdeabcde')->indexOfLast('c', -4); // 2 + u('abcdeabcde')->indexOfLast('eab'); // 4 + u('abcdeabcde')->indexOfLast('k'); // null + + // replaces all occurrences of the given string + u('http://symfony.com')->replace('http://', 'https://'); // 'https://symfony.com' + // replaces all occurrences of the given regular expression + u('(+1) 206-555-0100')->replaceMatches('/[^A-Za-z0-9]++/', ''); // '12065550100' + // you can pass a callable as the second argument to perform advanced replacements + u('123')->replaceMatches('/\d/', function ($match) { + return '['.$match[0].']'; + }); // result = '[1][2][3]' + +Methods to Join, Split and Truncate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + // uses the string as the "glue" to merge all the given strings + u(', ')->join(['foo', 'bar']); // 'foo, bar' + + // breaks the string into pieces using the given delimiter + u('template_name.html.twig')->split('.'); // ['template_name', 'html', 'twig'] + // you can set the maximum number of pieces as the second argument + u('template_name.html.twig')->split('.', 2); // ['template_name', 'html.twig'] + + // returns a substring which starts at the first argument and has the length of the + // second optional argument (negative values have the same meaning as in PHP functions) + u('Symfony is great')->slice(0, 7); // 'Symfony' + u('Symfony is great')->slice(0, -6); // 'Symfony is' + u('Symfony is great')->slice(11); // 'great' + u('Symfony is great')->slice(-5); // 'great' + + // reduces the string to the length given as argument (if it's longer) + u('Lorem Ipsum')->truncate(80); // 'Lorem Ipsum' + u('Lorem Ipsum')->truncate(3); // 'Lor' + u('Lorem Ipsum')->truncate(8, '…'); // 'Lorem I…' + + // breaks the string into lines of the given length + u('Lorem Ipsum')->wordwrap(4); // 'Lorem\nIpsum' + // by default it breaks by white space; pass TRUE to break unconditionally + u('Lorem Ipsum')->wordwrap(4, "\n", true); // 'Lore\nm\nIpsu\nm' + + // replaces a portion of the string with the given contents: + // the second argument is the position where the replacement starts; + // the third argument is the number of graphemes/code points removed from the string + u('0123456789')->splice('xxx'); // 'xxx' + u('0123456789')->splice('xxx', 0, 2); // 'xxx23456789' + u('0123456789')->splice('xxx', 0, 6); // 'xxx6789' + u('0123456789')->splice('xxx', 6); // '012345xxx' + + // breaks the string into pieces of the length given as argument + u('0123456789')->chunk(3); // ['012', '345', '678', '9'] + +Methods Added by ByteString +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These methods are only available for ``ByteString`` objects:: + + // returns TRUE if the string contents are valid UTF-8 contents + b('Lorem Ipsum')->isUtf8(); // true + b("\xc3\x28")->isUtf8(); // false + + // returns the value of the byte stored at the given position + // ('नमस्ते' bytes = [224, 164, 168, 224, 164, 174, 224, 164, 184, + // 224, 165, 141, 224, 164, 164, 224, 165, 135]) + b('नमस्ते')->byteCode(0); // 224 + b('नमस्ते')->byteCode(17); // 135 + +Methods Added by CodePointString and UnicodeString +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These methods are only available for ``CodePointString`` and ``UnicodeString`` +objects:: + + // transliterates any string into the latin alphabet defined by the ASCII encoding + // (don't use this method to build a slugger because this component already provides + // a slugger, as explained later in this article) + u('नमस्ते')->ascii(); // 'namaste' + u('さよなら')->ascii(); // 'sayonara' + u('спасибо')->ascii(); // 'spasibo' + + // returns the value of the code point stored at the given position + // (code points of 'नमस्ते' graphemes = [2344, 2350, 2360, 2340] + u('नमस्ते')->codePoint(0); // 2344 + u('नमस्ते')->codePoint(2); // 2360 + +`Unicode equivalence`_ is the specification by the Unicode standard that +different sequences of code points represent the same character. For example, +the Swedish letter ``å`` can be a single code point (``U+00E5`` = *"latin small +letter A with ring above"*) or a sequence of two code points (``U+0061`` = +*"latin small letter A"* + ``U+030A`` = *"combining ring above"*). The +``normalize()`` method allows to pick the normalization mode:: + + // these encode the letter as a single code point: U+00E5 + u('å')->normalize(UnicodeString::NFC); + u('å')->normalize(UnicodeString::NFKC); + // these encode the letter as two code points: U+0061 + U+030A + u('å')->normalize(UnicodeString::NFD); + u('å')->normalize(UnicodeString::NFKD); + +Slugger +------- + +In some contexts, such as URLs and file/directory names, it's not safe to use +any Unicode character. A *slugger* transforms a given string into another string +that only includes safe ASCII characters:: + + use Symfony\Component\String\Slugger\AsciiSlugger; + + $slugger = new AsciiSlugger(); + $slug = $slugger->slug('Wôrķšƥáçè ~~sèťtïñğš~~'); + // $slug = 'Workspace-settings' + +The separator between words is a dash (``-``) by default, but you can define +another separator as the second argument:: + + $slug = $slugger->slug('Wôrķšƥáçè ~~sèťtïñğš~~', '/'); + // $slug = 'Workspace/settings' + +The slugger transliterates the original string into the Latin script before +applying the other transformations. The locale of the original string is +detected automatically, but you can define it explicitly:: + + // this tells the slugger to transliterate from Korean language + $slugger = new AsciiSlugger('ko'); + + // you can override the locale as the third optional parameter of slug() + $slug = $slugger->slug('...', '-', 'fa'); + +In a Symfony application, you don't need to create the slugger yourself. Thanks +to :doc:`service autowiring `, you can inject a +slugger by type-hinting a service constructor argument with the +:class:`Symfony\\Component\\String\\Slugger\\SluggerInterface`. The locale of +the injected slugger is the value of the application's +:ref:`default_locale option `:: + + use Symfony\Component\String\Slugger\SluggerInterface; + + class MyService + { + private $slugger; + + public function __construct(SluggerInterface $slugger) + { + $this->slugger = $slugger; + } + + public function someMethod() + { + $slug = $slugger->slug('...'); + } + } + +.. _`ASCII`: https://en.wikipedia.org/wiki/ASCII +.. _`Unicode`: https://en.wikipedia.org/wiki/Unicode +.. _`Code points`: https://en.wikipedia.org/wiki/Code_point +.. _`Grapheme clusters`: https://en.wikipedia.org/wiki/Grapheme +.. _`Unicode equivalence`: https://en.wikipedia.org/wiki/Unicode_equivalence