Merge pull request #3292 from tinmarino/merge_faq_string

Faq: string common operations

Author: JJ

doc/Language/faq.pod6

@@ -299,6 +299,77 @@ dependencies within a single compilation unit (e.g., file) are possible
 through stubbing. Therefore another possible solution is to move
 classes into the same compilation unit.
 
+
+=head1 Common operations
+
+=head2 String: How can I parse and get a L<number|/language/numerics> from a L<string|/language/type/Str>
+
+Use the L<+ prefix|/language/operators#prefix_+>:
+
+=begin code :ok-test<dd>
+say "42.123456789123456789";  # OUTPUT: «42.123456789123456789␤»
+say +"42.4e-2";               # OUTPUT: «0.424␤»
+=end code
+
+This example of L<contextualization|/language/contexts> can numify any string you could enter as a L<literal number|/language/syntax#Number_literals>.
+L<val|/routine/val> routine converts it to L<allomorph|/language/glossary#Allomorph>.
+L<unival|/routine/unival> routine converts one unicode codepoint.
+
+=head2 String: How can I check if a string contains a substring and if so, how can I get indices of matches
+
+Use L<.contains|/type/Str#method_contains> or L<.indices|/type/Str#method_indices>:
+
+=begin code
+"az and az and az again".contains("az"); # OUTPUT: «True␤»
+"az and az and az again".indices("az");  # OUTPUT: «(0 7 14)␤»
+=end code
+
+=head2 String: How can I get the hexadecimal representation of a string
+
+To get an hexadecimal list of each byte of a string (i.e. hex encoder),
+first convert the string to a L<Blob|/type/Blob> with L<.encode|/routine/encode>.
+
+=begin code
+say "I ❤ 🦋".encode>>.base(16);  OUTPUT: «(49 20 E2 9D A4 20 F0 9F A6 8B)␤»
+=end code
+
+Note that L<.gist|/routine/gist> or L<.raku|/routine/perl> methods can be useful for variable introspection:
+
+=begin code
+say "I ❤ 🦋".encode.raku;  # OUTPUT: «utf8.new(73,32,226,157,164,32,240,159,166,139)␤»
+say "I ❤ 🦋".encode.gist;  # OUTPUT: «utf8:0x<49 20 E2 9D A4 20 F0 9F A6 8B>␤»
+=end code
+
+=head2 String: How can I remove from a string some characters by index
+
+Use L<.comb|/routine/comb> to transform it to a L<Seq|/type/Seq>, then the L<(-) infix|/language/operators#infix_(-),_infix_\\> to remove the unwanted indices:
+
+=begin code
+say '0123456789'.comb[(^* (-) (1..3, 8).flat).keys.sort].join;  # OUTPUT: «045679␤»
+=end code
+
+If the string is large, L<.comb|/routine/comb> can take time. In which case, L<.substr-rw|/routine/substr-rw> is faster:
+
+=begin code
+multi postcircumfix:<[- ]> (Str:D $str is copy, +@indices) {
+    for @indices.reverse {
+        when Int   { $str.substr-rw($_,1) = '' }
+        when Range { $str.substr-rw($_  ) = '' }
+    }
+    return $str;
+}
+
+say '0123456789'[- 1..3, 8 ];  # OUTPUT: «045679␤»
+=end code
+
+=head2 String: How can I split a string in equal parts
+
+L<.comb|/routine/comb> is accepting an optional L<Int|/type/Int>:
+
+=begin code
+.say for 'abcdefghijklmnopqrstuvwxyz'.comb: 8;  # OUTPUT: «abcdefgh␤ijklmnop␤qrstuvwx␤yz»
+=end code
+
 =head1 Language features
 
 X<|Data::Dumper (FAQ)>