-
Notifications
You must be signed in to change notification settings - Fork 292
/
Cool.rakudoc
1462 lines (1009 loc) · 49.8 KB
/
Cool.rakudoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=begin pod :kind("Type") :subkind("class") :category("basic")
=TITLE class Cool
=SUBTITLE Object that can be treated as both a string and number
class Cool is Any { }
C<Cool>, also known as the B<C>onvenient B<OO> B<L>oop, is a base class employed
by a number of built-in classes whose instances can be meaningfully coerced to a
string and a number. For example, an L<Array|/type/Array> can be used in
mathematical operations, where its numerical representation is the number of
elements it contains. At the same time, it can be concatenated to a string,
where its stringy representation is all of its elements L<joined|/routine/join>
by a space. Because L<Array|/type/Array> is C<Cool>, the appropriate
coercion happens automatically.
Methods in C<Cool> coerce the invocant to a more specific type, and then call
the same method on that type. For example both L<Int|/type/Int> and
L<Str|/type/Str> inherit from C<Cool>, and calling method C<substr> on an C<Int>
converts the integer to C<Str> first.
123.substr(1, 1); # '2', same as 123.Str.substr(1, 1)
The following built-in types inherit from C<Cool>: L<Array|/type/Array>
L<Bool|/type/Bool> L<Complex|/type/Complex> L<Cool|/type/Cool>
L<Duration|/type/Duration> L<Map|/type/Map> L<FatRat|/type/FatRat>
L<Hash|/type/Hash> L<Instant|/type/Instant> L<Int|/type/Int> L<List|/type/List>
L<Match|/type/Match> L<Nil|/type/Nil> L<Num|/type/Num> L<Range|/type/Range>
L<Seq|/type/Seq> L<Stash|/type/Stash> L<Str|/type/Str>.
The following table summarizes the methods that C<Cool> provides, and
what type they coerce to:
=begin table
method coercion type
abs Numeric
conj Numeric
sqrt Numeric
sign Real
rand Numeric
sin Numeric
asin Numeric
cos Numeric
acos Numeric
tan Numeric
tanh Numeric
atan Numeric
atan2 Numeric
atanh Numeric
sec Numeric
asec Numeric
cosec Numeric
acosec Numeric
cotan Numeric
cotanh Numeric
acotan Numeric
sinh Numeric
asinh Numeric
cosh Numeric
acosh Numeric
sech Numeric
asech Numeric
cosech Numeric
acosech Numeric
acotanh Numeric
cis Numeric
log Numeric
exp Numeric
roots Numeric
log10 Numeric
log2 Numeric
unpolar Numeric
round Numeric
floor Numeric
ceiling Numeric
truncate Numeric
chr Int
ord Str
chars Str
fmt Str
uniname Str
uninames Seq
unival Str
univals Str
uniprop Str
unimatch Str
uc Str
lc Str
fc Str
tc Str
tclc Str
flip Str
trans Str
contains Str
index Str
rindex Str
ords Str
split Str
match Str
comb Str
subst Str
sprintf Str
printf Str
samecase Str
trim Str
trim-leading Str
trim-trailing Str
EVAL Str
chomp Str
chop Str
codes Str
Complex Numeric
FatRat Numeric
Int Numeric
Num Numeric
Rat Numeric
Real Numeric
UInt Numeric
=end table
=head1 Methods
=head2 routine abs
sub abs(Numeric() $x)
method abs()
Coerces the invocant (or in the sub form, the argument) to
L<Numeric|/type/Numeric> and returns the absolute value (that is, a
non-negative number).
say (-2).abs; # OUTPUT: «2»
say abs "6+8i"; # OUTPUT: «10»
=head2 method conj
method conj()
Coerces the invocant to L<Numeric|/type/Numeric> and returns the
L<complex|/type/Complex> conjugate (that is, the number with the sign of the
imaginary part negated).
say (1+2i).conj; # OUTPUT: «1-2i»
=head2 method EVAL
=for code :method
method EVAL(*%_)
It calls the L<subroutine form|/language/independent-routines#routine_EVAL> with the
invocant as the first argument, C<$code>, passing along named args, if any.
=head2 routine sqrt
sub sqrt(Numeric(Cool) $x)
method sqrt()
Coerces the invocant to L<Numeric|/type/Numeric> (or in the sub form, the
argument) and returns the square root, that is, a number that, when
multiplied with itself, produces the original number.
say 4.sqrt; # OUTPUT: «2»
say sqrt(2); # OUTPUT: «1.4142135623731»
Returns C<NaN> for negative arguments. As of 6.e language version (early
implementation exists in Rakudo compiler 2023.02+), will return a
L<Complex|/type/Complex> value for negative arguments.
say sqrt(-1); # OUTPUT: «0+1i»
=head2 method sign
method sign()
Coerces the invocant to L<Numeric|/type/Real> and returns its sign, that
is, 0 if the number is 0, 1 for positive and -1 for negative values.
say 6.sign; # OUTPUT: «1»
say (-6).sign; # OUTPUT: «-1»
say "0".sign; # OUTPUT: «0»
=head2 method rand
method rand()
Coerces the invocant to L<Num|/type/Num> and returns a pseudo-random value
between zero and the number.
say 1e5.rand; # OUTPUT: «33128.495184283»
=head2 routine sin
sub sin(Numeric(Cool))
method sin()
Coerces the invocant (or in the sub form, the argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<sine|https://en.wikipedia.org/wiki/Sine>.
say sin(0); # OUTPUT: «0»
say sin(pi/4); # OUTPUT: «0.707106781186547»
say sin(pi/2); # OUTPUT: «1»
Note that Raku is no computer algebra system, so C<sin(pi)> typically does
not produce an exact 0, but rather a very small L<floating-point
number|/type/Num>.
=head2 routine asin
sub asin(Numeric(Cool))
method asin()
Coerces the invocant (or in the sub form, the argument) to
L<Numeric|/type/Numeric>, and returns its
L<arc-sine|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.
say 0.1.asin; # OUTPUT: «0.10016742116156»
say asin(0.1); # OUTPUT: «0.10016742116156»
=head2 routine cos
sub cos(Numeric(Cool))
method cos()
Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>,
interprets it as radians, returns its
L<cosine|https://en.wikipedia.org/wiki/Cosine>.
say 0.cos; # OUTPUT: «1»
say pi.cos; # OUTPUT: «-1»
say cos(pi/2); # OUTPUT: «6.12323399573677e-17»
=head2 routine acos
sub acos(Numeric(Cool))
method acos()
Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-cosine|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.
say 1.acos; # OUTPUT: «0»
say acos(-1); # OUTPUT: «3.14159265358979»
=head2 routine tan
sub tan(Numeric(Cool))
method tan()
Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<tangent|https://en.wikipedia.org/wiki/Tangent>.
say tan(3); # OUTPUT: «-0.142546543074278»
say 3.tan; # OUTPUT: «-0.142546543074278»
=head2 routine atan
sub atan(Numeric(Cool))
method atan()
Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-tangent|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.
say atan(3); # OUTPUT: «1.24904577239825»
say 3.atan; # OUTPUT: «1.24904577239825»
=head2 routine atan2
sub atan2($y, $x = 1e0)
method atan2($x = 1e0)
The sub should usually be written with two arguments for clarity as it
is seen in other languages and in mathematical texts, but the
single-argument form is available; its result will always match that of
L<atan|/routine/atan>.
say atan2 3, 1; # OUTPUT: «1.2490457723982544»
say atan2 3; # OUTPUT: «1.2490457723982544»
say atan2 ⅔, ⅓; # OUTPUT: «1.1071487177940904»
The method coerces self and its single argument to
L<Numeric|/type/Numeric>, using them to compute the two-argument
L<arc-tangent|https://en.wikipedia.org/wiki/Atan2> in radians.
say 3.atan2; # OUTPUT: «1.24904577239825»
say ⅔.atan2(⅓); # OUTPUT: «1.1071487177940904»
The $x argument in either the method or the sub defaults to 1 so, in both
single-argument cases, the function will return the angle θ in radians
between the x-axis and a vector that goes from the origin to the point
(3, 1).
=head2 routine sec
sub sec(Numeric(Cool))
method sec()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<secant|https://en.wikipedia.org/wiki/Trigonometric_functions#Reciprocal_functions>,
that is, the reciprocal of its cosine.
say 45.sec; # OUTPUT: «1.90359440740442»
say sec(45); # OUTPUT: «1.90359440740442»
=head2 routine asec
sub asec(Numeric(Cool))
method asec()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>,
and returns its
L<arc-secant|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.
say 1.asec; # OUTPUT: «0»
say sqrt(2).asec; # OUTPUT: «0.785398163397448»
=head2 routine cosec
sub cosec(Numeric(Cool))
method cosec()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>,
interprets it as radians, returns its
L<cosecant|https://en.wikipedia.org/wiki/Trigonometric_functions#Reciprocal_functions>,
that is, the reciprocal of its sine.
say 0.45.cosec; # OUTPUT: «2.29903273150897»
say cosec(0.45); # OUTPUT: «2.29903273150897»
=head2 routine acosec
sub acosec(Numeric(Cool))
method acosec()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>,
and returns its
L<arc-cosecant|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.
say 45.acosec; # OUTPUT: «0.0222240516182672»
say acosec(45) # OUTPUT: «0.0222240516182672»
=head2 routine cotan
sub cotan(Numeric(Cool))
method cotan()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>,
interprets it as radians, returns its
L<cotangent|https://en.wikipedia.org/wiki/Trigonometric_functions#Reciprocal_functions>,
that is, the reciprocal of its tangent.
say 45.cotan; # OUTPUT: «0.617369623783555»
say cotan(45); # OUTPUT: «0.617369623783555»
=head2 routine acotan
sub acotan(Numeric(Cool))
method acotan()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>,
and returns its
L<arc-cotangent|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions>
in radians.
say 45.acotan; # OUTPUT: «0.0222185653267191»
say acotan(45) # OUTPUT: «0.0222185653267191»
=head2 routine sinh
sub sinh(Numeric(Cool))
method sinh()
Coerces the invocant (or in method form, its argument) to
L<Numeric|/type/Numeric>, and returns its
L<Sine hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.
say 1.sinh; # OUTPUT: «1.1752011936438»
say sinh(1); # OUTPUT: «1.1752011936438»
=head2 routine asinh
sub asinh(Numeric(Cool))
method asinh()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse Sine hyperbolicus|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.
say 1.asinh; # OUTPUT: «0.881373587019543»
say asinh(1); # OUTPUT: «0.881373587019543»
=head2 routine cosh
sub cosh(Numeric(Cool))
method cosh()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Cosine hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.
say cosh(0.5); # OUTPUT: «1.12762596520638»
=head2 routine acosh
sub acosh(Numeric(Cool))
method acosh()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse Cosine hyperbolicus|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.
say acosh(45); # OUTPUT: «4.4996861906715»
=head2 routine tanh
sub tanh(Numeric(Cool))
method tanh()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, interprets it as
radians and returns its L<Tangent hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.
say tanh(0.5); # OUTPUT: «0.46211715726001»
say tanh(atanh(0.5)); # OUTPUT: «0.5»
=head2 routine atanh
sub atanh(Numeric(Cool))
method atanh()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse tangent hyperbolicus|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.
say atanh(0.5); # OUTPUT: «0.549306144334055»
=head2 routine sech
sub sech(Numeric(Cool))
method sech()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Secant hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.
say 0.sech; # OUTPUT: «1»
=head2 routine asech
sub asech(Numeric(Cool))
method asech()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse hyperbolic secant|https://en.wikipedia.org/wiki/Hyperbolic_function>.
say 0.8.asech; # OUTPUT: «0.693147180559945»
=head2 routine cosech
sub cosech(Numeric(Cool))
method cosech()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Hyperbolic cosecant|https://en.wikipedia.org/wiki/Hyperbolic_function>.
say cosech(pi/2); # OUTPUT: «0.434537208094696»
=head2 routine acosech
sub acosech(Numeric(Cool))
method acosech()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse hyperbolic cosecant|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.
say acosech(4.5); # OUTPUT: «0.220432720979802»
=head2 routine cotanh
sub cotanh(Numeric(Cool))
method cotanh()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Hyperbolic cotangent|https://en.wikipedia.org/wiki/Hyperbolic_function>.
say cotanh(pi); # OUTPUT: «1.00374187319732»
=head2 routine acotanh
sub acotanh(Numeric(Cool))
method acotanh()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse hyperbolic cotangent|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.
say acotanh(2.5); # OUTPUT: «0.423648930193602»
=head2 routine cis
sub cis(Numeric(Cool))
method cis()
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns
L<cos(argument) + i*sin(argument)|https://en.wikipedia.org/wiki/Cis_%28mathematics%29>.
say cis(pi/4); # OUTPUT: «0.707106781186548+0.707106781186547i»
=head2 routine log
multi sub log(Numeric(Cool) $number, Numeric(Cool) $base?)
multi method log(Cool:D: Cool:D $base?)
Coerces the arguments (including the invocant in the method form) to
L<Numeric|/type/Numeric>, and returns its
L<Logarithm|https://en.wikipedia.org/wiki/Logarithm> to base C<$base>, or to
base C<e> (Euler's Number) if no base was supplied
(L<Natural logarithm|https://en.wikipedia.org/wiki/Natural_logarithm>).
Throws an exception if C<$base> is C<1>.
say (e*e).log; # OUTPUT: «2»
Returns C<NaN> for negative arguments. As of 6.e language version (early
implementation exists in Rakudo compiler 2023.02+), will return a
L<Complex|/type/Complex> value for negative arguments.
=head2 routine log10
multi method log10()
multi sub log10(Numeric $x)
multi sub log10(Cool $x)
Coerces the invocant (or in the sub form, the argument) to
L<Numeric|/type/Numeric> (or uses it directly if it's already in that form), and
returns its L<Logarithm|https://en.wikipedia.org/wiki/Logarithm> in base 10,
that is, a number that approximately produces the original number when 10 is
raised to its power. Returns C<-Inf> for C<0>.
say log10(1001); # OUTPUT: «3.00043407747932»
Returns C<NaN> for negative arguments. As of 6.e language version (early
implementation exists in Rakudo compiler 2023.02+), will return a
L<Complex|/type/Complex> value for negative arguments.
=head2 routine log2
multi method log2()
multi sub log2(Numeric $x)
multi sub log2(Cool $x)
Coerces the invocant to L<Numeric|/type/Numeric>, and returns its
L<Logarithm|https://en.wikipedia.org/wiki/Logarithm> in base 2, that is, a
number that approximately (due to computer precision limitations) produces the
original number when 2 is raised to its power. Returns C<-Inf> for C<0>.
say log2(5); # OUTPUT: «2.321928094887362»
say "4".log2; # OUTPUT: «2»
say 4.log2; # OUTPUT: «2»
Returns C<NaN> for negative arguments. As of 6.e language version (early
implementation exists in Rakudo compiler 2023.02+), will return a
L<Complex|/type/Complex> value for negative arguments.
=head2 routine exp
multi sub exp(Cool:D $pow, Cool:D $base?)
multi method exp(Cool:D: Cool:D $base?)
Coerces the arguments (including the invocant in the method from) to L<Numeric|/type/Numeric>, and returns C<$base>
raised to the power of the first number. If no C<$base> is supplied, C<e> (Euler's
Number) is used.
say 0.exp; # OUTPUT: «1»
say 1.exp; # OUTPUT: «2.71828182845905»
say 10.exp; # OUTPUT: «22026.4657948067»
=head2 method unpolar
method unpolar(Numeric(Cool))
Coerces the arguments (including the invocant in the method form) to L<Numeric|/type/Numeric>, and returns
a complex number from the given polar coordinates. The invocant (or the first argument in sub form) is the magnitude while
the argument (i.e. the second argument in sub form) is the angle. The angle is assumed to be in radians.
say sqrt(2).unpolar(pi/4); # OUTPUT: «1+1i»
=head2 routine round
multi sub round(Numeric(Cool), $scale = 1)
multi method round(Cool:D: $scale = 1)
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and rounds it to the unit of
C<$scale>. If C<$scale> is 1, rounds to the nearest integer; an arbitrary scale will result in the closest
multiple of that number.
say 1.7.round; # OUTPUT: «2»
say 1.07.round(0.1); # OUTPUT: «1.1»
say 21.round(10); # OUTPUT: «20»
say round(1000, 23.01) # OUTPUT: «989.43»
Always rounds B<up> if the number is at mid-point:
say (−.5 ).round; # OUTPUT: «0»
say ( .5 ).round; # OUTPUT: «1»
say (−.55).round(.1); # OUTPUT: «-0.5»
say ( .55).round(.1); # OUTPUT: «0.6»
B<Pay attention> to types when using this method, as ending up with the wrong type may
affect the precision you seek to achieve. For L<Real|/type/Real> types, the type of the result
is the type of the argument (L<Complex|/type/Complex> argument gets coerced to L<Real|/type/Real>, ending up a L<Num|/type/Num>).
If rounding a L<Complex|/type/Complex>, the result is L<Complex|/type/Complex> as well, regardless of the type of the argument.
9930972392403501.round(1) .raku.say; # OUTPUT: «9930972392403501»
9930972392403501.round(1e0) .raku.say; # OUTPUT: «9.9309723924035e+15»
9930972392403501.round(1e0).Int.raku.say; # OUTPUT: «9930972392403500»
=head2 routine floor
multi sub floor(Numeric(Cool))
multi method floor
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and rounds it downwards to
the nearest integer.
say "1.99".floor; # OUTPUT: «1»
say "-1.9".floor; # OUTPUT: «-2»
say 0.floor; # OUTPUT: «0»
=head2 method fmt
method fmt($format = '%s')
Uses C<$format> to return a formatted representation of the invocant; equivalent
to calling L<sprintf|/routine/sprintf> with C<$format> as format and the
invocant as the second argument. The C<$format> will be coerced to
L<Stringy|/type/Stringy> and defaults to C<'%s'>.
For more information about formats strings, see L<sprintf|/routine/sprintf>.
say 11.fmt('This Int equals %03d'); # OUTPUT: «This Int equals 011»
say '16'.fmt('Hexadecimal %x'); # OUTPUT: «Hexadecimal 10»
=head2 routine ceiling
multi sub ceiling(Numeric(Cool))
multi method ceiling
Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>,
and rounds it upwards to the nearest integer.
say "1".ceiling; # OUTPUT: «1»
say "-0.9".ceiling; # OUTPUT: «0»
say "42.1".ceiling; # OUTPUT: «43»
=head2 routine truncate
multi sub truncate(Numeric(Cool))
multi method truncate()
Coerces the invocant (or in sub form, its argument) to
L<Numeric|/type/Numeric>, and rounds it towards zero.
say 1.2.truncate; # OUTPUT: «1»
say truncate -1.2; # OUTPUT: «-1»
=head2 routine ord
sub ord(Str(Cool))
method ord()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the L<Unicode code point|https://en.wikipedia.org/wiki/Code_point>
number of the first code point.
say 'a'.ord; # OUTPUT: «97»
The inverse operation is L<chr|/routine/chr>.
Mnemonic: returns an ordinal number
=head2 method path
method path(Cool:D: --> IO::Path:D)
B<DEPRECATED>. I<It's been deprecated as of the 6.d version. Will be removed in
the next ones.>
Stringifies the invocant and converts it to L<IO::Path|/type/IO::Path> object.
Use the L«C<.IO method>|/routine/IO» instead.
=head2 routine chr
sub chr(Int(Cool))
method chr()
Coerces the invocant (or in sub form, its argument) to L<Int|/type/Int>,
interprets it as a
L<Unicode code points|https://en.wikipedia.org/wiki/Code_point>, and returns a
L<string|/type/Str> made of that code point.
say '65'.chr; # OUTPUT: «A»
The inverse operation is L<ord|/routine/ord>.
Mnemonic: turns an integer into a I<char>acter.
=head2 routine chars
multi sub chars(Cool $x)
multi sub chars(Str:D $x)
multi sub chars(str $x --> int)
method chars(--> Int:D)
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the number of characters in the string. Please note that on the JVM, you
currently get codepoints instead of graphemes.
say 'møp'.chars; # OUTPUT: «3»
say 'ã̷̠̬̊'.chars; # OUTPUT: «1»
say '👨👩👧👦🏿'.chars; # OUTPUT: «1»
If the string is native, the number of chars will be also returned as a native
C<int>.
X<|Syntax,Grapheme>
Graphemes are user visible characters. That is, this is what the user
thinks of as a “character”.
Graphemes can contain more than one
codepoint. Typically the number of graphemes and codepoints differs
when C<Prepend> or C<Extend> characters are involved (also known as
L<Combining characters|https://en.wikipedia.org/wiki/Combining_character>), but
there are many other cases when this may happen. Another example is C<\c[ZWJ]>
(L<Zero-width joiner|https://en.wikipedia.org/wiki/Zero-width_joiner>).
You can check C<Grapheme_Cluster_Break> property of a character in
order to see how it is going to behave:
say ‘ã̷̠̬̊’.uniprops(‘Grapheme_Cluster_Break’); # OUTPUT: «(Other Extend Extend Extend Extend)»
say ‘👨👩👧👦🏿’.uniprops(‘Grapheme_Cluster_Break’); # OUTPUT: «(E_Base_GAZ ZWJ E_Base_GAZ ZWJ E_Base_GAZ ZWJ E_Base_GAZ E_Modifier)»
You can read more about graphemes in the
L<Unicode Standard|https://unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries>,
which Raku tightly follows, using a method called L<NFG, normal form graphemes|/language/glossary#NFG> for efficiently representing them.
=head2 routine codes
sub codes(Str(Cool))
method codes()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the number of L<Unicode code points|https://en.wikipedia.org/wiki/Code_point>.
say 'møp'.codes; # OUTPUT: «3»
The same result will be obtained with
say +'møp'.ords; # OUTPUT: «3»
L<ords|/routine/ords> first obtains the actual codepoints, so there might be a difference in speed.
=head2 routine flip
sub flip(Cool $s --> Str:D)
method flip()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns a reversed version.
say 421.flip; # OUTPUT: «124»
=head2 routine trim
sub trim(Str(Cool))
method trim()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the string with both leading and trailing whitespace stripped.
my $stripped = ' abc '.trim;
say "<$stripped>"; # OUTPUT: «<abc>»
=head2 routine trim-leading
sub trim-leading(Str(Cool))
method trim-leading()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the string with leading whitespace stripped.
my $stripped = ' abc '.trim-leading;
say "<$stripped>"; # OUTPUT: «<abc >»
=head2 routine trim-trailing
sub trim-trailing(Str(Cool))
method trim-trailing()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the string with trailing whitespace stripped.
my $stripped = ' abc '.trim-trailing;
say "<$stripped>"; # OUTPUT: «< abc>»
=head2 routine lc
sub lc(Str(Cool))
method lc()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns it case-folded to lower case.
say "ABC".lc; # OUTPUT: «abc»
=head2 routine uc
sub uc(Str(Cool))
method uc()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns it case-folded to upper case (capital letters).
say "Abc".uc; # OUTPUT: «ABC»
=head2 routine fc
sub fc(Str(Cool))
method fc()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the result a Unicode "case fold" operation suitable for doing caseless
string comparisons. (In general, the returned string is unlikely to be useful
for any purpose other than comparison.)
say "groß".fc; # OUTPUT: «gross»
=head2 routine tc
sub tc(Str(Cool))
method tc()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns it with the first letter case-folded to title case (or where not
available, upper case).
say "abC".tc; # OUTPUT: «AbC»
=head2 routine tclc
sub tclc(Str(Cool))
method tclc()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it with the first letter
case-folded to title case (or where not available, upper case), and the rest
of the string case-folded to lower case.
say 'abC'.tclc; # OUTPUT: «Abc»
=head2 routine wordcase
sub wordcase(Str(Cool) $input, :&filter = &tclc, Mu :$where = True)
method wordcase(:&filter = &tclc, Mu :$where = True)
Coerces the invocant (or in sub form, the first argument) to L<Str|/type/Str>, and filters each word that
smartmatches against C<$where> through the C<&filter>. With the default
filter (first character to upper case, rest to lower) and matcher (which
accepts everything), this title-cases each word:
say "raku programming".wordcase; # OUTPUT: «Raku Programming»
With a matcher:
say "have fun working on raku".wordcase(:where({ .chars > 3 }));
# Have fun Working on Raku
With a customer filter too:
say "have fun working on raku".wordcase(:filter(&uc), :where({ .chars > 3 }));
# HAVE fun WORKING on RAKU
=head2 routine samecase
sub samecase(Cool $string, Cool $pattern)
method samecase(Cool:D: Cool $pattern)
Coerces the invocant (or in sub form, the
first argument) to L<Str|/type/Str>, and calls
L«C<Str.samecase>|/type/Str#method_samecase» on it.
say "raKu".samecase("A_a_"); # OUTPUT: «Raku»
say "rAKU".samecase("Ab"); # OUTPUT: «Raku»
=head2 routine uniprop
multi sub uniprop(Str:D, |c)
multi sub uniprop(Int:D $code)
multi sub uniprop(Int:D $code, Stringy:D $propname)
multi method uniprop(|c)
Returns the L<unicode property|http://userguide.icu-project.org/strings/properties>
of the first character. If no property is specified returns the
L<General Category|https://en.wikipedia.org/wiki/Unicode_character_property#General_Category>.
Returns a Bool for Boolean properties. A L<uniprops|/routine/uniprops> routine can be used
to get the property for every character in a string.
say 'a'.uniprop; # OUTPUT: «Ll»
say '1'.uniprop; # OUTPUT: «Nd»
say 'a'.uniprop('Alphabetic'); # OUTPUT: «True»
say '1'.uniprop('Alphabetic'); # OUTPUT: «False»
=head2 sub uniprops
sub uniprops(Str:D $str, Stringy:D $propname = "General_Category")
Interprets the invocant as a L<Str|/type/Str>, and returns the
L<unicode property|http://userguide.icu-project.org/strings/properties> for each character
as a Seq. If no property is specified returns the
L<General Category|https://en.wikipedia.org/wiki/Unicode_character_property#General_Category>.
Returns a Bool for Boolean properties. Similar to
L<uniprop|/routine/uniprop>, but for each character in the passed
string.
=head2 routine uniname
sub uniname(Str(Cool) --> Str)
method uniname(--> Str)
Interprets the invocant or first argument as a L<Str|/type/Str>, and returns the
Unicode codepoint name of the first codepoint of the first character. See
L<uninames|/routine/uninames> for a routine that works with multiple
codepoints, and L<uniparse|/routine/uniparse> for the opposite direction.
# Camelia in Unicode
say ‘»ö«’.uniname;
# OUTPUT: «RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK»
say "Ḍ̇".uniname; # Note, doesn't show "COMBINING DOT ABOVE"
# OUTPUT: «LATIN CAPITAL LETTER D WITH DOT BELOW»
# Find the char with the longest Unicode name.
say (0..0x1FFFF).sort(*.uniname.chars)[*-1].chr.uniname;
# OUTPUT: «BOX DRAWINGS LIGHT DIAGONAL UPPER CENTRE TO MIDDLE RIGHT AND MIDDLE LEFT TO LOWER CENTRE»
=head2 routine uninames
sub uninames(Str:D)
method uninames()
Returns of a Seq of Unicode names for the all the codepoints in the Str
provided.
say ‘»ö«’.uninames.raku;
# OUTPUT: «("RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK", "LATIN SMALL LETTER O WITH DIAERESIS", "LEFT-POINTING DOUBLE ANGLE QUOTATION MARK").Seq»
Note this example, which gets a Seq where each element is a Seq of all the
codepoints in that character.
say "Ḍ̇'oh".comb>>.uninames.raku;
# OUTPUT: «(("LATIN CAPITAL LETTER D WITH DOT BELOW", "COMBINING DOT ABOVE").Seq, ("APOSTROPHE",).Seq, ("LATIN SMALL LETTER O",).Seq, ("LATIN SMALL LETTER H",).Seq)»
See L<uniparse|/routine/uniparse> for the opposite direction.
=head2 routine unimatch
multi sub unimatch(Str:D $str, |c)
multi sub unimatch(Int:D $code, Stringy:D $pvalname, Stringy:D $propname = $pvalname)
Checks if the given integer codepoint or the first letter of the given string
has a unicode property equal to the value you give. If you supply the Unicode
property to be checked it will only return True if that property matches the
given value.
say unimatch 'A', 'Latin'; # OUTPUT: «True»
say unimatch 'A', 'Latin', 'Script'; # OUTPUT: «True»
say unimatch 'A', 'Ll'; # OUTPUT: «False»
The last property corresponds to "lowercase letter", which explains why it
returns false.
=head2 routine chop
sub chop(Str(Cool))
method chop()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns it with the last character removed.
say 'raku'.chop; # OUTPUT: «rak»
=head2 routine chomp
sub chomp(Str(Cool))
method chomp()
Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns it with the last character removed, if it is a logical newline.