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
|
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>string - manipulate strings — fish-shell 4.2.1 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=4da8bbd6" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=f89b4716" />
<script src="../_static/documentation_options.js?v=6fb65176"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="string-collect - join strings into one" href="string-collect.html" />
<link rel="prev" title="status - query fish runtime information" href="status.html" />
<link rel="shortcut icon" type="image/png" href="../_static/fish.png" />
</head><body><div id="fmain">
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li><img src="../_static/fish.png" alt=""
style="width: 80px; height: 80px; vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://fishshell.com/">fish-shell</a> »</li>
<a href="../index.html">fish-shell 4.2.1 documentation</a> »
<li class="nav-item nav-item-1"><a href="../commands.html" accesskey="U">Commands</a> »</li>
<li class="nav-item nav-item-this"><a href="">string - manipulate strings</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</li>
<div id="old-docs-notice" style="display: none">
This documents an old version of fish.
<a href="../../current/">See the latest release.</a>
</div>
</ul>
</div>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../index.html">Documents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently asked questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../interactive.html">Interactive use</a></li>
<li class="toctree-l1"><a class="reference internal" href="../language.html">The fish language</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../commands.html">Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fish_for_bash_users.html">Fish for bash users</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../completions.html">Writing your own completions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../prompt.html">Writing your own prompt</a></li>
<li class="toctree-l1"><a class="reference internal" href="../design.html">Design</a></li>
<li class="toctree-l1"><a class="reference internal" href="../relnotes.html">Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../terminal-compatibility.html">Terminal Compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">Contributing To Fish</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license.html">License</a></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<div>
<h4><a href="../index.html">Sections</a></h4>
<ul>
<li><a class="reference internal" href="#">string - manipulate strings</a><ul>
<li><a class="reference internal" href="#synopsis">Synopsis</a></li>
<li><a class="reference internal" href="#description">Description</a></li>
<li><a class="reference internal" href="#collect-subcommand">“collect” subcommand</a><ul>
<li><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#escape-and-unescape-subcommands">“escape” and “unescape” subcommands</a><ul>
<li><a class="reference internal" href="#id1">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#join-and-join0-subcommands">“join” and “join0” subcommands</a><ul>
<li><a class="reference internal" href="#id2">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#length-subcommand">“length” subcommand</a><ul>
<li><a class="reference internal" href="#id3">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#lower-subcommand">“lower” subcommand</a></li>
<li><a class="reference internal" href="#match-subcommand">“match” subcommand</a><ul>
<li><a class="reference internal" href="#match-glob-examples">Match Glob Examples</a></li>
<li><a class="reference internal" href="#match-regex-examples">Match Regex Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#pad-subcommand">“pad” subcommand</a><ul>
<li><a class="reference internal" href="#id4">Examples</a></li>
<li><a class="reference internal" href="#see-also">See also</a></li>
</ul>
</li>
<li><a class="reference internal" href="#shorten-subcommand">“shorten” subcommand</a><ul>
<li><a class="reference internal" href="#id5">Examples</a></li>
<li><a class="reference internal" href="#id6">See also</a></li>
</ul>
</li>
<li><a class="reference internal" href="#repeat-subcommand">“repeat” subcommand</a><ul>
<li><a class="reference internal" href="#id7">Examples</a></li>
<li><a class="reference internal" href="#repeat-examples">Repeat Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#replace-subcommand">“replace” subcommand</a><ul>
<li><a class="reference internal" href="#replace-literal-examples">Replace Literal Examples</a></li>
<li><a class="reference internal" href="#replace-regex-examples">Replace Regex Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#split-and-split0-subcommands">“split” and “split0” subcommands</a><ul>
<li><a class="reference internal" href="#id8">Examples</a></li>
<li><a class="reference internal" href="#nul-delimited-examples">NUL Delimited Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#sub-subcommand">“sub” subcommand</a><ul>
<li><a class="reference internal" href="#id9">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#trim-subcommand">“trim” subcommand</a><ul>
<li><a class="reference internal" href="#id10">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#upper-subcommand">“upper” subcommand</a></li>
<li><a class="reference internal" href="#regular-expressions">Regular Expressions</a></li>
<li><a class="reference internal" href="#comparison-to-other-tools">Comparison to other tools</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="string-manipulate-strings">
<h1>string - manipulate strings<a class="headerlink" href="#string-manipulate-strings" title="Link to this heading">¶</a></h1>
<section id="synopsis">
<h2>Synopsis<a class="headerlink" href="#synopsis" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">collect</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-a</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--allow-empty</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-N</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-trim-newlines</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">escape</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-quoted</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">--style=</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">join</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-empty</span><span class="g g-Other">]</span><span class="w"> </span><span class="no">SEP</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">join0</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-empty</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">length</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">lower</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-a</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--all</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-e</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--entire</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-i</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--ignore-case</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-g</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--groups-only</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--regex</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--index</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-v</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--invert</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="no">PATTERN</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">pad</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--right</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-C</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--center</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-c</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--char</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">CHAR</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-w</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--width</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">INTEGER</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--count</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">COUNT</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">MAX</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-N</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-newline</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-N</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-newline</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="no">COUNT</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">replace</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-a</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--all</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-f</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--filter</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-i</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--ignore-case</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--regex</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="no">PATTERN</span><span class="w"> </span><span class="no">REPLACE</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">shorten</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-c</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--char</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">CHARS</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">INTEGER</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-N</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-newline</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-l</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--left</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">split</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-f</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--fields</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">FIELDS</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">MAX</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-empty</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--right</span><span class="g g-Other">]</span><span class="w"> </span><span class="no">SEP</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">split0</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-f</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--fields</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">FIELDS</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">MAX</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-empty</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--right</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">sub</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-s</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--start</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">START</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-e</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--end</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">END</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-l</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--length</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">LENGTH</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">trim</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-l</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--left</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--right</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-c</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--chars</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">CHARS</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">unescape</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">--style=</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">upper</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
</section>
<section id="description">
<h2>Description<a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">string</span></code> performs operations on strings.</p>
<p><em>STRING</em> arguments are taken from the command line unless standard input is connected to a pipe or a file, in which case they are read from standard input, one <em>STRING</em> per line. It is an error to supply <em>STRING</em> arguments on the command line and on standard input.</p>
<p>Arguments beginning with <code class="docutils literal notranslate"><span class="pre">-</span></code> are normally interpreted as switches; <code class="docutils literal notranslate"><span class="pre">--</span></code> causes the following arguments not to be treated as switches even if they begin with <code class="docutils literal notranslate"><span class="pre">-</span></code>. Switches and required arguments are recognized only on the command line.</p>
<p>Most subcommands accept a <strong>-q</strong> or <strong>--quiet</strong> switch, which suppresses the usual output but exits with the documented status. In this case these commands will quit early, without reading all of the available input.</p>
<p>The following subcommands are available.</p>
</section>
<section id="collect-subcommand">
<h2>“collect” subcommand<a class="headerlink" href="#collect-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">collect</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-a</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--allow-empty</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-N</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-trim-newlines</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">collect</span></code> collects its input into a single output argument, without splitting the output when used in a command substitution. This is useful when trying to collect multiline output from another command into a variable. Exit status: 0 if any output argument is non-empty, or 1 otherwise.</p>
<p>A command like <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">(cmd</span> <span class="pre">|</span> <span class="pre">string</span> <span class="pre">collect)</span></code> is mostly equivalent to a quoted command substitution (<code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">"$(cmd)"</span></code>). The main difference is that the former evaluates to zero or one elements whereas the quoted command substitution always evaluates to one element due to string interpolation.</p>
<p>If invoked with multiple arguments instead of input, <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">collect</span></code> preserves each argument separately, where the number of output arguments is equal to the number of arguments given to <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">collect</span></code>.</p>
<p>Any trailing newlines on the input are trimmed, just as with <code class="docutils literal notranslate"><span class="pre">"$(cmd)"</span></code> substitution. Use <strong>--no-trim-newlines</strong> to disable this behavior, which may be useful when running a command such as <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">contents</span> <span class="pre">(cat</span> <span class="pre">filename</span> <span class="pre">|</span> <span class="pre">string</span> <span class="pre">collect</span> <span class="pre">-N)</span></code>.</p>
<p>With <strong>--allow-empty</strong>, <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">collect</span></code> always prints one (empty) argument. This can be used to prevent an argument from disappearing.</p>
<section id="examples">
<h3>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="s2">"zero </span><span class="o">$(</span><span class="nf">echo</span><span class="w"> </span><span class="no">one</span><span class="se">\n</span><span class="no">two</span><span class="se">\n</span><span class="no">three</span><span class="o">)</span><span class="s2"> four"</span>
<span class="go">zero one</span>
<span class="go">two</span>
<span class="go">three four</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="se">\"</span><span class="o">(</span><span class="nf">echo</span><span class="w"> </span><span class="no">one</span><span class="se">\n</span><span class="no">two</span><span class="se">\n</span><span class="no">three</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">collect</span><span class="o">)</span><span class="se">\"</span>
<span class="go">"one</span>
<span class="go">two</span>
<span class="go">three"</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="se">\"</span><span class="o">(</span><span class="nf">echo</span><span class="w"> </span><span class="no">one</span><span class="se">\n</span><span class="no">two</span><span class="se">\n</span><span class="no">three</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">collect</span><span class="w"> </span><span class="no">-N</span><span class="o">)</span><span class="se">\"</span>
<span class="go">"one</span>
<span class="go">two</span>
<span class="go">three</span>
<span class="go">"</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="no">foo</span><span class="o">(</span><span class="nf">true</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">collect</span><span class="w"> </span><span class="no">--allow-empty</span><span class="o">)</span><span class="no">bar</span>
<span class="go">foobar</span>
</pre></div>
</div>
</section>
</section>
<section id="escape-and-unescape-subcommands">
<h2>“escape” and “unescape” subcommands<a class="headerlink" href="#escape-and-unescape-subcommands" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">escape</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-quoted</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">--style=</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">unescape</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">--style=</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">escape</span></code> escapes each <em>STRING</em> in one of several ways.</p>
<p><strong>--style=script</strong> (default) alters the string such that it can be passed back to <code class="docutils literal notranslate"><span class="pre">eval</span></code> to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If <strong>-n</strong> or <strong>--no-quoted</strong> is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.</p>
<p><strong>--style=var</strong> ensures the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded.</p>
<p><strong>--style=url</strong> ensures the string can be used as a URL by hex encoding any character which is not legal in a URL. The string is first converted to UTF-8 before being encoded.</p>
<p><strong>--style=regex</strong> escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded.</p>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">unescape</span></code> performs the inverse of the <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">escape</span></code> command. If the string to be unescaped is not properly formatted it is ignored. For example, doing <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">unescape</span> <span class="pre">--style=var</span> <span class="pre">(string</span> <span class="pre">escape</span> <span class="pre">--style=var</span> <span class="pre">$str)</span></code> will return the original string. There is no support for unescaping <strong>--style=regex</strong>.</p>
<section id="id1">
<h3>Examples<a class="headerlink" href="#id1" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="se">\x07</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">escape</span>
<span class="go">\cg</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">escape</span><span class="w"> </span><span class="no">--style=var</span><span class="w"> </span><span class="s1">'a1 b2'</span><span class="se">\u6161</span>
<span class="go">a1_20_b2_E6_85_A1_</span>
</pre></div>
</div>
</section>
</section>
<section id="join-and-join0-subcommands">
<h2>“join” and “join0” subcommands<a class="headerlink" href="#join-and-join0-subcommands" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">join</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-empty</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">--</span><span class="g g-Other">]</span><span class="w"> </span><span class="no">SEP</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">join0</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-empty</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">--</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p>Joins its <em>STRING</em> arguments into a single string separated by <em>SEP</em> (for <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">join</span></code>) or by the
zero byte (NUL) (for <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">join0</span></code>).
Exit status: 0 if at least one join was performed, or 1 otherwise.</p>
<dl class="simple">
<dt><strong>-n</strong>, <strong>--no-empty</strong></dt><dd><p>Exclude empty strings from consideration (e.g. <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">join</span> <span class="pre">-n</span> <span class="pre">+</span> <span class="pre">a</span> <span class="pre">b</span> <span class="pre">""</span> <span class="pre">c</span></code> would expand to <code class="docutils literal notranslate"><span class="pre">a+b+c</span></code> not <code class="docutils literal notranslate"><span class="pre">a+b++c</span></code>).</p>
</dd>
<dt><strong>-q</strong>, <strong>--quiet</strong></dt><dd><p>Do not print the strings, only set the exit status as described above.</p>
</dd>
</dl>
<p><strong>WARNING</strong>:
Insert a <code class="docutils literal notranslate"><span class="pre">--</span></code> before positional arguments to prevent them from being interpreted as flags.
Otherwise, any strings starting with <code class="docutils literal notranslate"><span class="pre">-</span></code> will be treated as flag arguments, meaning they will most likely result in the command failing.
This is also true if you specify a variable which expands to such a string instead of a literal string.
If you don’t need to append flag arguments at the end of the command,
just always use <code class="docutils literal notranslate"><span class="pre">--</span></code> to avoid unwelcome surprises.</p>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">join0</span></code> adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as <code class="docutils literal notranslate"><span class="pre">sort</span> <span class="pre">-z</span></code>.</p>
<p>Because Unix uses NUL as the string terminator, passing the output of <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">join0</span></code> as an <em>argument</em> to a command (via a <a class="reference internal" href="../language.html#expand-command-substitution"><span class="std std-ref">command substitution</span></a>) won’t actually work.
Fish will pass the correct bytes along, but the command won’t be able to tell where the argument ends.
This is a limitation of Unix’ argument passing.</p>
<section id="id2">
<h3>Examples<a class="headerlink" href="#id2" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">seq</span><span class="w"> </span><span class="no">3</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">join</span><span class="w"> </span><span class="no">...</span>
<span class="go">1...2...3</span>
<span class="go"># Give a list of NUL-separated filenames to du (this is a GNU extension)</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">join0</span><span class="w"> </span><span class="no">file1</span><span class="w"> </span><span class="no">file2</span><span class="w"> </span><span class="no">file</span><span class="se">\n</span><span class="no">with</span><span class="se">\n</span><span class="no">multiple</span><span class="se">\n</span><span class="no">lines</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">du</span><span class="w"> </span><span class="no">--files0-from=-</span>
<span class="go"># Just put the strings together without a separator</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">join</span><span class="w"> </span><span class="s1">''</span><span class="w"> </span><span class="no">a</span><span class="w"> </span><span class="no">b</span><span class="w"> </span><span class="no">c</span>
<span class="go">abc</span>
<span class="gp">>_ </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">markdown_list</span><span class="w"> </span><span class="s1">'- first'</span><span class="w"> </span><span class="s1">'- second'</span><span class="w"> </span><span class="s1">'- third'</span>
<span class="go"># Strings with leading hyphens (also in variable expansions) are interpreted as flag arguments by default.</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">join</span><span class="w"> </span><span class="se">\n</span><span class="w"> </span><span class="o">$markdown_list</span>
<span class="go">string join: - first: unknown option</span>
<span class="go"># Use '--' to prevent this.</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">join</span><span class="w"> </span><span class="no">--</span><span class="w"> </span><span class="se">\n</span><span class="w"> </span><span class="o">$markdown_list</span>
<span class="go">- first</span>
<span class="go">- second</span>
<span class="go">- third</span>
</pre></div>
</div>
</section>
</section>
<section id="length-subcommand">
<h2>“length” subcommand<a class="headerlink" href="#length-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">length</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-V</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--visible</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">length</span></code> reports the length of each string argument in characters. Exit status: 0 if at least one non-empty <em>STRING</em> was given, or 1 otherwise.</p>
<p>With <strong>-V</strong> or <strong>--visible</strong>, it uses the visible width of the arguments. That means it will discount escape sequences fish knows about, account for $fish_emoji_width and $fish_ambiguous_width. It will also count each line (separated by <code class="docutils literal notranslate"><span class="pre">\n</span></code>) on its own, and with a carriage return (<code class="docutils literal notranslate"><span class="pre">\r</span></code>) count only the widest stretch on a line. The intent is to measure the number of columns the <em>STRING</em> would occupy in the current terminal.</p>
<section id="id3">
<h3>Examples<a class="headerlink" href="#id3" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">length</span><span class="w"> </span><span class="s1">'hello, world'</span>
<span class="go">12</span>
<span class="gp">>_ </span><span class="nf">set</span><span class="w"> </span><span class="no">str</span><span class="w"> </span><span class="no">foo</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">length</span><span class="w"> </span><span class="no">-q</span><span class="w"> </span><span class="o">$str</span><span class="p">;</span><span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$status</span>
<span class="go">0</span>
<span class="go"># Equivalent to test -n "$str"</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">length</span><span class="w"> </span><span class="no">--visible</span><span class="w"> </span><span class="o">(</span><span class="nf">set_color</span><span class="w"> </span><span class="no">red</span><span class="o">)</span><span class="no">foobar</span>
<span class="go"># the set_color is discounted, so this is the width of "foobar"</span>
<span class="go">6</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">length</span><span class="w"> </span><span class="no">--visible</span><span class="w"> </span><span class="no">🐟🐟🐟🐟</span>
<span class="go"># depending on $fish_emoji_width, this is either 4 or 8</span>
<span class="go"># in new terminals it should be</span>
<span class="go">8</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">length</span><span class="w"> </span><span class="no">--visible</span><span class="w"> </span><span class="no">abcdef</span><span class="se">\r</span><span class="no">123</span>
<span class="go"># this displays as "123def", so the width is 6</span>
<span class="go">6</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">length</span><span class="w"> </span><span class="no">--visible</span><span class="w"> </span><span class="no">a</span><span class="se">\n</span><span class="no">bc</span>
<span class="go"># counts "a" and "bc" as separate lines, so it prints width for each</span>
<span class="go">1</span>
<span class="go">2</span>
</pre></div>
</div>
</section>
</section>
<section id="lower-subcommand">
<h2>“lower” subcommand<a class="headerlink" href="#lower-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">lower</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">lower</span></code> converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the <strong>-q</strong> flag you can readily test whether a string is already lowercase.</p>
</section>
<section id="match-subcommand">
<h2>“match” subcommand<a class="headerlink" href="#match-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-a</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--all</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-e</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--entire</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-i</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--ignore-case</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-g</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--groups-only</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--regex</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--index</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-v</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--invert</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max-matches</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">MAX</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="no">PATTERN</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">match</span></code> tests each <em>STRING</em> against <em>PATTERN</em> and prints matching substrings. Only the first match for each <em>STRING</em> is reported unless <strong>-a</strong> or <strong>--all</strong> is given, in which case all matches are reported.</p>
<p>If you specify the <strong>-e</strong> or <strong>--entire</strong> then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to <code class="docutils literal notranslate"><span class="pre">grep</span></code> without the <strong>-o</strong> flag). You can, obviously, achieve the same result by prepending and appending <strong>*</strong> or <strong>.*</strong> depending on whether or not you have specified the <strong>--regex</strong> flag. The <strong>--entire</strong> flag is a way to avoid having to complicate the pattern in that fashion and make the intent of the <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">match</span></code> clearer. Without <strong>--entire</strong> and <strong>--regex</strong>, a <em>PATTERN</em> will need to match the entire <em>STRING</em> before it will be reported.</p>
<p>Matching can be made case-insensitive with <strong>--ignore-case</strong> or <strong>-i</strong>.</p>
<p>If <strong>--groups-only</strong> or <strong>-g</strong> is given, only the capturing groups will be reported - meaning the full match will be skipped. This is incompatible with <strong>--entire</strong> and <strong>--invert</strong>, and requires <strong>--regex</strong>. It is useful as a simple cutting tool instead of <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">replace</span></code>, so you can choose “this part” of a string.</p>
<p>If <strong>--index</strong> or <strong>-n</strong> is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire <em>STRING</em> argument. A glob pattern is only considered a valid match if it matches the entire <em>STRING</em>.</p>
<p>If <strong>--regex</strong> or <strong>-r</strong> is given, <em>PATTERN</em> is interpreted as a Perl-compatible regular expression, which does not have to match the entire <em>STRING</em>. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. With this, only the matching part of the <em>STRING</em> will be reported, unless <strong>--entire</strong> is given.</p>
<p>When matching via regular expressions, <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">match</span></code> automatically sets variables for all named capturing groups (<code class="docutils literal notranslate"><span class="pre">(?<name>expression)</span></code>). It will create a variable with the name of the group, in the default scope, for each named capturing group, and set it to the value of the capturing group in the first matched argument. If a named capture group matched an empty string, the variable will be set to the empty string (like <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">var</span> <span class="pre">""</span></code>). If it did not match, the variable will be set to nothing (like <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">var</span></code>). When <strong>--regex</strong> is used with <strong>--all</strong>, this behavior changes. Each named variable will contain a list of matches, with the first match contained in the first element, the second match in the second, and so on. If the group was empty or did not match, the corresponding element will be an empty string.</p>
<p>If <strong>--invert</strong> or <strong>-v</strong> is used the selected lines will be only those which do not match the given glob pattern or regular expression.</p>
<p>If <strong>--max-matches MAX</strong> or <strong>-m MAX</strong> is used, <code class="docutils literal notranslate"><span class="pre">string</span></code> will stop checking for matches after MAX lines of input have matched. This can be used as an “early exit” optimization when processing long inputs but expecting a limited and fixed number of outputs that might be found considerably before the input stream has been exhausted. If combined with <strong>--invert</strong> or <strong>-v</strong>, considers only inverted matches.</p>
<p>Exit status: 0 if at least one match was found, or 1 otherwise.</p>
<section id="match-glob-examples">
<h3>Match Glob Examples<a class="headerlink" href="#match-glob-examples" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="s1">'a'</span><span class="w"> </span><span class="no">a</span>
<span class="go">a</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="s1">'a*b'</span><span class="w"> </span><span class="no">axxb</span>
<span class="go">axxb</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-i</span><span class="w"> </span><span class="s1">'a*B'</span><span class="w"> </span><span class="no">Axxb</span>
<span class="go">Axxb</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">--</span><span class="w"> </span><span class="s1">'-*'</span><span class="w"> </span><span class="no">-h</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">--version</span><span class="w"> </span><span class="no">bar</span>
<span class="go"># To match things that look like options, we need a `--`</span>
<span class="go"># to tell string its options end there.</span>
<span class="go">-h</span>
<span class="go">--version</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="s1">'ok?'</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="s1">'*?'</span>
<span class="go">ok?</span>
<span class="go"># Note that only the second STRING will match here.</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="s1">'foo'</span><span class="w"> </span><span class="s1">'foo1'</span><span class="w"> </span><span class="s1">'foo'</span><span class="w"> </span><span class="s1">'foo2'</span>
<span class="go">foo</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="s1">'foo'</span><span class="w"> </span><span class="s1">'foo1'</span><span class="w"> </span><span class="s1">'foo'</span><span class="w"> </span><span class="s1">'foo2'</span>
<span class="go">foo1</span>
<span class="go">foo</span>
<span class="go">foo2</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="s1">'foo*'</span><span class="w"> </span><span class="s1">'foo1'</span><span class="w"> </span><span class="s1">'foo'</span><span class="w"> </span><span class="s1">'foo2'</span>
<span class="go">foo1</span>
<span class="go">foo2</span>
</pre></div>
</div>
</section>
<section id="match-regex-examples">
<h3>Match Regex Examples<a class="headerlink" href="#match-regex-examples" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="s1">'cat|dog|fish'</span><span class="w"> </span><span class="s1">'nice dog'</span>
<span class="go">dog</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="no">-v</span><span class="w"> </span><span class="s2">"c.*[12]"</span><span class="w"> </span><span class="o">{</span><span class="no">cat</span><span class="o">,</span><span class="no">dog</span><span class="o">}(</span><span class="nf">seq</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">4</span><span class="o">)</span>
<span class="go">dog1</span>
<span class="go">dog2</span>
<span class="go">cat3</span>
<span class="go">dog3</span>
<span class="go">cat4</span>
<span class="go">dog4</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="no">--</span><span class="w"> </span><span class="s1">'-.*'</span><span class="w"> </span><span class="no">-h</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">--version</span><span class="w"> </span><span class="no">bar</span>
<span class="go"># To match things that look like options, we need a `--`</span>
<span class="go"># to tell string its options end there.</span>
<span class="go">-h</span>
<span class="go">--version</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="s1">'(\d\d?):(\d\d):(\d\d)'</span><span class="w"> </span><span class="no">2:34:56</span>
<span class="go">2:34:56</span>
<span class="go">2</span>
<span class="go">34</span>
<span class="go">56</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="s1">'^(\w{2,4})\1$'</span><span class="w"> </span><span class="no">papa</span><span class="w"> </span><span class="no">mud</span><span class="w"> </span><span class="no">murmur</span>
<span class="go">papa</span>
<span class="go">pa</span>
<span class="go">murmur</span>
<span class="go">mur</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="no">-a</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="no">at</span><span class="w"> </span><span class="no">ratatat</span>
<span class="go">2 2</span>
<span class="go">4 2</span>
<span class="go">6 2</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="no">-i</span><span class="w"> </span><span class="s1">'0x[0-9a-f]{1,8}'</span><span class="w"> </span><span class="s1">'int magic = 0xBadC0de;'</span>
<span class="go">0xBadC0de</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="o">$version</span>
<span class="go">3.1.2-1575-ga2ff32d90</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-rq</span><span class="w"> </span><span class="s1">'(?<major>\d+).(?<minor>\d+).(?<revision>\d+)'</span><span class="w"> </span><span class="no">--</span><span class="w"> </span><span class="o">$version</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="s2">"You are using fish </span><span class="o">$major</span><span class="s2">!"</span>
<span class="go">You are using fish 3!</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-raq</span><span class="w"> </span><span class="s1">' *(?<sentence>[^.!?]+)(?<punctuation>[.!?])?'</span><span class="w"> </span><span class="s2">"hello, friend. goodbye"</span>
<span class="gp">>_ </span><span class="nf">printf</span><span class="w"> </span><span class="s2">"%s\n"</span><span class="w"> </span><span class="no">--</span><span class="w"> </span><span class="o">$sentence</span>
<span class="go">hello, friend</span>
<span class="go">goodbye</span>
<span class="gp">>_ </span><span class="nf">printf</span><span class="w"> </span><span class="s2">"%s\n"</span><span class="w"> </span><span class="no">--</span><span class="w"> </span><span class="o">$punctuation</span>
<span class="go">.</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-rq</span><span class="w"> </span><span class="s1">'(?<word>hello)'</span><span class="w"> </span><span class="s1">'hi'</span>
<span class="gp">>_ </span><span class="nf">count</span><span class="w"> </span><span class="o">$word</span>
<span class="go">0</span>
</pre></div>
</div>
</section>
</section>
<section id="pad-subcommand">
<h2>“pad” subcommand<a class="headerlink" href="#pad-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">pad</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--right</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-C</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--center</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-c</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--char</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">CHAR</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-w</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--width</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">INTEGER</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">pad</span></code> extends each <em>STRING</em> to the given visible width by adding <em>CHAR</em> to the left. That means the width of all visible characters added together, excluding escape sequences and accounting for <span class="target" id="index-0"></span><a class="reference internal" href="../language.html#envvar-fish_emoji_width"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_emoji_width</span></code></a> and <span class="target" id="index-1"></span><a class="reference internal" href="../language.html#envvar-fish_ambiguous_width"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_ambiguous_width</span></code></a>. It is the amount of columns in a terminal the <em>STRING</em> occupies.</p>
<p>The escape sequences reflect what fish knows about, and how it computes its output. Your terminal might support more escapes, or not support escape sequences that fish knows about.</p>
<p>If <strong>-C</strong> or <strong>--center</strong> is given, add the padding to before and after the string. If it is impossible to perfectly center the result (because the required amount of padding is an odd number), extra padding will be added to the left, unless <strong>--right</strong> is also given.</p>
<p>If <strong>-r</strong> or <strong>--right</strong> is given, add the padding after a string.</p>
<p>If <strong>-c</strong> or <strong>--char</strong> is given, pad with <em>CHAR</em> instead of whitespace.</p>
<p>The output is padded to the maximum width of all input strings. If <strong>-w</strong> or <strong>--width</strong> is given, use at least that.</p>
<section id="id4">
<h3>Examples<a class="headerlink" href="#id4" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">pad</span><span class="w"> </span><span class="no">-w</span><span class="w"> </span><span class="no">10</span><span class="w"> </span><span class="no">abc</span><span class="w"> </span><span class="no">abcdef</span>
<span class="go"> abc</span>
<span class="go"> abcdef</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">pad</span><span class="w"> </span><span class="no">--right</span><span class="w"> </span><span class="no">--char=🐟</span><span class="w"> </span><span class="s2">"fish are pretty"</span><span class="w"> </span><span class="s2">"rich. "</span>
<span class="go">fish are pretty</span>
<span class="go">rich. 🐟🐟🐟🐟</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">pad</span><span class="w"> </span><span class="no">-w</span><span class="o">$COLUMNS</span><span class="w"> </span><span class="o">(</span><span class="nf">date</span><span class="o">)</span>
<span class="go"># Prints the current time on the right edge of the screen.</span>
</pre></div>
</div>
</section>
<section id="see-also">
<h3>See also<a class="headerlink" href="#see-also" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>The <a class="reference internal" href="printf.html"><span class="doc">printf</span></a> command can do simple padding, for example <code class="docutils literal notranslate"><span class="pre">printf</span> <span class="pre">%10s\n</span></code> works like <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">pad</span> <span class="pre">-w10</span></code>.</p></li>
<li><p><a class="reference internal" href="string-length.html"><span class="doc">string length</span></a> with the <code class="docutils literal notranslate"><span class="pre">--visible</span></code> option can be used to show what fish thinks the width is.</p></li>
</ul>
</section>
</section>
<section id="shorten-subcommand">
<h2>“shorten” subcommand<a class="headerlink" href="#shorten-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">shorten</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-c</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--char</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">CHARS</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">INTEGER</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-N</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-newline</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-l</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--left</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">shorten</span></code> truncates each <em>STRING</em> to the given visible width and adds an ellipsis to indicate it. “Visible width” means the width of all visible characters added together, excluding escape sequences and accounting for <span class="target" id="index-2"></span><a class="reference internal" href="../language.html#envvar-fish_emoji_width"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_emoji_width</span></code></a> and <span class="target" id="index-3"></span><a class="reference internal" href="../language.html#envvar-fish_ambiguous_width"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_ambiguous_width</span></code></a>. It is the amount of columns in a terminal the <em>STRING</em> occupies.</p>
<p>The escape sequences reflect what fish knows about, and how it computes its output. Your terminal might support more escapes, or not support escape sequences that fish knows about.</p>
<p>If <strong>-m</strong> or <strong>--max</strong> is given, truncate at the given width. Otherwise, the lowest non-zero width of all input strings is used. A max of 0 means no shortening takes place, all STRINGs are printed as-is.</p>
<p>If <strong>-N</strong> or <strong>--no-newline</strong> is given, only the first line (or last line with <strong>--left</strong>) of each STRING is used, and an ellipsis is added if it was multiline. This only works for STRINGs being given as arguments, multiple lines given on stdin will be interpreted as separate STRINGs instead.</p>
<p>If <strong>-c</strong> or <strong>--char</strong> is given, add <em>CHAR</em> instead of an ellipsis. This can also be empty or more than one character.</p>
<p>If <strong>-l</strong> or <strong>--left</strong> is given, remove text from the left on instead, so this prints the longest <em>suffix</em> of the string that fits. With <strong>--no-newline</strong>, this will take from the last line instead of the first.</p>
<p>If <strong>-q</strong> or <strong>--quiet</strong> is given, <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">shorten</span></code> only runs for the return value - if anything would be shortened, it returns 0, else 1.</p>
<p>The default ellipsis is <code class="docutils literal notranslate"><span class="pre">…</span></code>. If fish thinks your system is incapable because of your locale, it will use <code class="docutils literal notranslate"><span class="pre">...</span></code> instead.</p>
<p>The return value is 0 if any shortening occurred, 1 otherwise.</p>
<section id="id5">
<h3>Examples<a class="headerlink" href="#id5" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">shorten</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">foobar</span>
<span class="go"># No width was given, we infer, and "foo" is the shortest.</span>
<span class="go">foo</span>
<span class="go">fo…</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">shorten</span><span class="w"> </span><span class="no">--char=</span><span class="s2">"..."</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">foobar</span>
<span class="go"># The target width is 3 because of "foo",</span>
<span class="go"># and our ellipsis is 3 too, so we can't really show anything.</span>
<span class="go"># This is the default ellipsis if your locale doesn't allow "…".</span>
<span class="go">foo</span>
<span class="go">...</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">shorten</span><span class="w"> </span><span class="no">--char=</span><span class="s2">""</span><span class="w"> </span><span class="no">--max</span><span class="w"> </span><span class="no">4</span><span class="w"> </span><span class="no">abcdef</span><span class="w"> </span><span class="no">123456</span>
<span class="go"># Leaving the char empty makes us not add an ellipsis</span>
<span class="go"># So this truncates at 4 columns:</span>
<span class="go">abcd</span>
<span class="go">1234</span>
<span class="gp">>_ </span><span class="nf">touch</span><span class="w"> </span><span class="s2">"a multiline"</span><span class="se">\n</span><span class="s2">"file"</span>
<span class="gp">>_ </span><span class="nf">for</span><span class="w"> </span><span class="no">file</span><span class="w"> </span><span class="nf">in</span><span class="w"> </span><span class="o">*</span><span class="p">;</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">shorten</span><span class="w"> </span><span class="no">-N</span><span class="w"> </span><span class="no">--</span><span class="w"> </span><span class="o">$file</span><span class="p">;</span><span class="w"> </span><span class="nf">end</span>
<span class="go"># Shorten the multiline file so we only show one line per file:</span>
<span class="go">a multiline…</span>
<span class="gp">>_ </span><span class="nf">ss</span><span class="w"> </span><span class="no">-p</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">shorten</span><span class="w"> </span><span class="no">-m</span><span class="o">$COLUMNS</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="s2">""</span>
<span class="go"># `ss` from Linux' iproute2 shows socket information, but prints extremely long lines.</span>
<span class="go"># This shortens input so it fits on the screen without overflowing lines.</span>
<span class="gp">>_ </span><span class="nf">git</span><span class="w"> </span><span class="no">branch</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-rg</span><span class="w"> </span><span class="s1">'^\* (.*)'</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">shorten</span><span class="w"> </span><span class="no">-m20</span>
<span class="go"># Take the current git branch and shorten it at 20 columns.</span>
<span class="go"># Here the branch is "builtin-path-with-expand"</span>
<span class="go">builtin-path-with-e…</span>
<span class="gp">>_ </span><span class="nf">git</span><span class="w"> </span><span class="no">branch</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="no">-rg</span><span class="w"> </span><span class="s1">'^\* (.*)'</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">shorten</span><span class="w"> </span><span class="no">-m20</span><span class="w"> </span><span class="no">--left</span>
<span class="go"># Taking 20 columns from the right instead:</span>
<span class="go">…in-path-with-expand</span>
</pre></div>
</div>
</section>
<section id="id6">
<h3>See also<a class="headerlink" href="#id6" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p><a class="reference internal" href="string-pad.html"><span class="doc">string pad</span></a> does the inverse of this command, adding padding to a specific width instead.</p></li>
<li><p>The <a class="reference internal" href="printf.html"><span class="doc">printf</span></a> command can do simple padding, for example <code class="docutils literal notranslate"><span class="pre">printf</span> <span class="pre">%10s\n</span></code> works like <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">pad</span> <span class="pre">-w10</span></code>.</p></li>
<li><p><a class="reference internal" href="string-length.html"><span class="doc">string length</span></a> with the <code class="docutils literal notranslate"><span class="pre">--visible</span></code> option can be used to show what fish thinks the width is.</p></li>
</ul>
</section>
</section>
<section id="repeat-subcommand">
<h2>“repeat” subcommand<a class="headerlink" href="#repeat-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--count</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">COUNT</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">MAX</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-N</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-newline</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-N</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-newline</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="no">COUNT</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">repeat</span></code> repeats the <em>STRING</em> <strong>-n</strong> or <strong>--count</strong> times. The <strong>-m</strong> or <strong>--max</strong> option will limit the number of outputted characters (excluding the newline). This option can be used by itself or in conjunction with <strong>--count</strong>. If both <strong>--count</strong> and <strong>--max</strong> are present, max char will be outputted unless the final repeated string size is less than max, in that case, the string will repeat until count has been reached. Both <strong>--count</strong> and <strong>--max</strong> will accept a number greater than or equal to zero, in the case of zero, nothing will be outputted. The first argument is interpreted as <em>COUNT</em> if <strong>--count</strong> or <strong>--max</strong> are not explicitly specified. If <strong>-N</strong> or <strong>--no-newline</strong> is given, the output won’t contain a newline character at the end. Exit status: 0 if yielded string is not empty, 1 otherwise.</p>
<section id="id7">
<h3>Examples<a class="headerlink" href="#id7" title="Link to this heading">¶</a></h3>
</section>
<section id="repeat-examples">
<h3>Repeat Examples<a class="headerlink" href="#repeat-examples" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="s1">'foo '</span>
<span class="go">foo foo</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="no">2</span>
<span class="go">foofoo</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">-m</span><span class="w"> </span><span class="no">5</span><span class="w"> </span><span class="s1">'foo'</span>
<span class="go">foofo</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="no">-m</span><span class="w"> </span><span class="no">5</span><span class="w"> </span><span class="s1">'foo'</span>
<span class="go">foofo</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="s1">'foo'</span>
<span class="go">foofoo</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">repeat</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="no">3</span>
<span class="go">222</span>
</pre></div>
</div>
</section>
</section>
<section id="replace-subcommand">
<h2>“replace” subcommand<a class="headerlink" href="#replace-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">replace</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-a</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--all</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-f</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--filter</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-i</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--ignore-case</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--regex</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max-matches</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">MAX</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="no">PATTERN</span><span class="w"> </span><span class="no">REPLACEMENT</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">replace</span></code> is similar to <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">match</span></code> but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, <em>PATTERN</em> is treated as a literal substring to be matched.</p>
<p>If <strong>-r</strong> or <strong>--regex</strong> is given, <em>PATTERN</em> is interpreted as a Perl-compatible regular expression, and <em>REPLACEMENT</em> can contain C-style escape sequences like <strong>t</strong> as well as references to capturing groups by number or name as <em>$n</em> or <em>${n}</em>.</p>
<p>If you specify the <strong>-f</strong> or <strong>--filter</strong> flag then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: <code class="docutils literal notranslate"><span class="pre">a_cmd</span> <span class="pre">|</span> <span class="pre">string</span> <span class="pre">match</span> <span class="pre">pattern</span> <span class="pre">|</span> <span class="pre">string</span> <span class="pre">replace</span> <span class="pre">pattern</span> <span class="pre">new_pattern</span></code>. You can instead just write <code class="docutils literal notranslate"><span class="pre">a_cmd</span> <span class="pre">|</span> <span class="pre">string</span> <span class="pre">replace</span> <span class="pre">--filter</span> <span class="pre">pattern</span> <span class="pre">new_pattern</span></code>.</p>
<p>If <strong>--max-matches MAX</strong> or <strong>-m MAX</strong> is used, <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">replace</span></code> will stop all processing after MAX lines of input have matched the specified pattern. In the event of <code class="docutils literal notranslate"><span class="pre">--filter</span></code> or <code class="docutils literal notranslate"><span class="pre">-f</span></code>, this means the output will be MAX lines in length. This can be used as an “early exit” optimization when processing long inputs but expecting a limited and fixed number of outputs that might be found considerably before the input stream has been exhausted.</p>
<p>Exit status: 0 if at least one replacement was performed, or 1 otherwise.</p>
<section id="replace-literal-examples">
<h3>Replace Literal Examples<a class="headerlink" href="#replace-literal-examples" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">replace</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="no">was</span><span class="w"> </span><span class="s1">'blue is my favorite'</span>
<span class="go">blue was my favorite</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">replace</span><span class="w"> </span><span class="no">3rd</span><span class="w"> </span><span class="no">last</span><span class="w"> </span><span class="no">1st</span><span class="w"> </span><span class="no">2nd</span><span class="w"> </span><span class="no">3rd</span>
<span class="go">1st</span>
<span class="go">2nd</span>
<span class="go">last</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">replace</span><span class="w"> </span><span class="no">-a</span><span class="w"> </span><span class="s1">' '</span><span class="w"> </span><span class="no">_</span><span class="w"> </span><span class="s1">'spaces to underscores'</span>
<span class="go">spaces_to_underscores</span>
</pre></div>
</div>
</section>
<section id="replace-regex-examples">
<h3>Replace Regex Examples<a class="headerlink" href="#replace-regex-examples" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">replace</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="no">-a</span><span class="w"> </span><span class="s1">'[^\d.]+'</span><span class="w"> </span><span class="s1">' '</span><span class="w"> </span><span class="s1">'0 one two 3.14 four 5x'</span>
<span class="go">0 3.14 5</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">replace</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="s1">'(\w+)\s+(\w+)'</span><span class="w"> </span><span class="s1">'$2 $1 $$'</span><span class="w"> </span><span class="s1">'left right'</span>
<span class="go">right left $</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">replace</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="s1">'\s*newline\s*'</span><span class="w"> </span><span class="s1">'\n'</span><span class="w"> </span><span class="s1">'put a newline here'</span>
<span class="go">put a</span>
<span class="go">here</span>
</pre></div>
</div>
</section>
</section>
<section id="split-and-split0-subcommands">
<h2>“split” and “split0” subcommands<a class="headerlink" href="#split-and-split0-subcommands" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">split</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-f</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--fields</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">FIELDS</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-a</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--allow-empty</span><span class="g g-Other">]]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">MAX</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-empty</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--right</span><span class="g g-Other">]</span><span class="w"> </span><span class="no">SEP</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
<span class="nf">string</span><span class="w"> </span><span class="no">split0</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-f</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--fields</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">FIELDS</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-a</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--allow-empty</span><span class="g g-Other">]]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-m</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--max</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">MAX</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-n</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--no-empty</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--right</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">split</span></code> splits each <em>STRING</em> on the separator <em>SEP</em>, which can be an empty string. If <strong>-m</strong> or <strong>--max</strong> is specified, at most MAX splits are done on each <em>STRING</em>. If <strong>-r</strong> or <strong>--right</strong> is given, splitting is performed right-to-left. This is only useful in combination with <strong>-m</strong> or <strong>--max</strong>. With <strong>-n</strong> or <strong>--no-empty</strong>, empty results are excluded from consideration (e.g. <code class="docutils literal notranslate"><span class="pre">hello\n\nworld</span></code> would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise.</p>
<p>Use <strong>-f</strong> or <strong>--fields</strong> to print out specific fields. FIELDS is a comma-separated string of field numbers and/or spans. Each field is one-indexed, and will be printed on separate lines. If a given field does not exist, then the command exits with status 1 and does not print anything, unless <strong>--allow-empty</strong> is used.</p>
<p>See also the <strong>--delimiter</strong> option of the <a class="reference internal" href="read.html"><span class="doc">read</span></a> command.</p>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">split0</span></code> splits each <em>STRING</em> on the zero byte (NUL). Options are the same as <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">split</span></code> except that no separator is given.</p>
<p><code class="docutils literal notranslate"><span class="pre">split0</span></code> has the important property that its output is not further split when used in a command substitution, allowing for the command substitution to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as <code class="docutils literal notranslate"><span class="pre">find</span> <span class="pre">-print0</span></code> or <code class="docutils literal notranslate"><span class="pre">sort</span> <span class="pre">-z</span></code>. See split0 examples below.</p>
<p>Be aware that commandline arguments cannot include NULs, so you likely want to pass to <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">split0</span></code> via a pipe, not a command substitution.</p>
<section id="id8">
<h3>Examples<a class="headerlink" href="#id8" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">split</span><span class="w"> </span><span class="no">.</span><span class="w"> </span><span class="no">example.com</span>
<span class="go">example</span>
<span class="go">com</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">split</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="no">-m1</span><span class="w"> </span><span class="no">/</span><span class="w"> </span><span class="no">/usr/local/bin/fish</span>
<span class="go">/usr/local/bin</span>
<span class="go">fish</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">split</span><span class="w"> </span><span class="s1">''</span><span class="w"> </span><span class="no">abc</span>
<span class="go">a</span>
<span class="go">b</span>
<span class="go">c</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">split</span><span class="w"> </span><span class="no">--allow-empty</span><span class="w"> </span><span class="no">-f1,3-4,5</span><span class="w"> </span><span class="s1">''</span><span class="w"> </span><span class="no">abcd</span>
<span class="go">a</span>
<span class="go">c</span>
<span class="go">d</span>
</pre></div>
</div>
</section>
<section id="nul-delimited-examples">
<h3>NUL Delimited Examples<a class="headerlink" href="#nul-delimited-examples" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="c"># Count files in a directory, without being confused by newlines.</span>
<span class="gp">>_ </span><span class="c"># Note: Don't use `string split0 (find . -print0)`, because arguments cannot include NUL.</span>
<span class="gp">>_ </span><span class="nf">count</span><span class="w"> </span><span class="o">(</span><span class="nf">find</span><span class="w"> </span><span class="no">.</span><span class="w"> </span><span class="no">-print0</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">split0</span><span class="o">)</span>
<span class="go">42</span>
<span class="gp">>_ </span><span class="c"># Sort a list of elements which may contain newlines</span>
<span class="gp">>_ </span><span class="nf">set</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">beta</span><span class="w"> </span><span class="no">alpha</span><span class="se">\n</span><span class="no">gamma</span>
<span class="gp">>_ </span><span class="nf">set</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="o">(</span><span class="nf">string</span><span class="w"> </span><span class="no">join0</span><span class="w"> </span><span class="o">$foo</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">sort</span><span class="w"> </span><span class="no">-z</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">split0</span><span class="o">)</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">escape</span><span class="w"> </span><span class="o">$foo[</span><span class="no">1</span><span class="o">]</span>
<span class="go">alpha\ngamma</span>
</pre></div>
</div>
</section>
</section>
<section id="sub-subcommand">
<h2>“sub” subcommand<a class="headerlink" href="#sub-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">sub</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-s</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--start</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">START</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-e</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--end</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">END</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-l</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--length</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">LENGTH</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">sub</span></code> prints a substring of each string argument. The start/end of the substring can be specified with <strong>-s</strong>/<strong>-e</strong> or <strong>--start</strong>/<strong>--end</strong> followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with <strong>-l</strong> or <strong>--length</strong>. If the length or end is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise. <strong>--length</strong> is mutually exclusive with <strong>--end</strong>.</p>
<section id="id9">
<h3>Examples<a class="headerlink" href="#id9" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">sub</span><span class="w"> </span><span class="no">--length</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">abcde</span>
<span class="go">ab</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">sub</span><span class="w"> </span><span class="no">-s</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">abcde</span>
<span class="go">bc</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">sub</span><span class="w"> </span><span class="no">--start=-2</span><span class="w"> </span><span class="no">abcde</span>
<span class="go">de</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">sub</span><span class="w"> </span><span class="no">--end=3</span><span class="w"> </span><span class="no">abcde</span>
<span class="go">abc</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">sub</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="no">-1</span><span class="w"> </span><span class="no">abcde</span>
<span class="go">abcd</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">sub</span><span class="w"> </span><span class="no">-s</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="no">-1</span><span class="w"> </span><span class="no">abcde</span>
<span class="go">bcd</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">sub</span><span class="w"> </span><span class="no">-s</span><span class="w"> </span><span class="no">-3</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="no">-2</span><span class="w"> </span><span class="no">abcde</span>
<span class="go">c</span>
</pre></div>
</div>
</section>
</section>
<section id="trim-subcommand">
<h2>“trim” subcommand<a class="headerlink" href="#trim-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">trim</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-l</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--left</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-r</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--right</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[(</span><span class="no">-c</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--chars</span><span class="g g-Other">)</span><span class="w"> </span><span class="no">CHARS</span><span class="g g-Other">]</span>
<span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">trim</span></code> removes leading and trailing whitespace from each <em>STRING</em>. If <strong>-l</strong> or <strong>--left</strong> is given, only leading whitespace is removed. If <strong>-r</strong> or <strong>--right</strong> is given, only trailing whitespace is trimmed.</p>
<p>The <strong>-c</strong> or <strong>--chars</strong> switch causes the set of characters in <em>CHARS</em> to be removed instead of whitespace. This is a set of characters, not a string - if you pass <code class="docutils literal notranslate"><span class="pre">-c</span> <span class="pre">foo</span></code>, it will remove any “f” or “o”, not just “foo” as a whole.</p>
<p>Exit status: 0 if at least one character was trimmed, or 1 otherwise.</p>
<section id="id10">
<h3>Examples<a class="headerlink" href="#id10" title="Link to this heading">¶</a></h3>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">trim</span><span class="w"> </span><span class="s1">' abc '</span>
<span class="go">abc</span>
<span class="gp">>_ </span><span class="nf">string</span><span class="w"> </span><span class="no">trim</span><span class="w"> </span><span class="no">--right</span><span class="w"> </span><span class="no">--chars=yz</span><span class="w"> </span><span class="no">xyzzy</span><span class="w"> </span><span class="no">zany</span>
<span class="go">x</span>
<span class="go">zan</span>
</pre></div>
</div>
</section>
</section>
<section id="upper-subcommand">
<h2>“upper” subcommand<a class="headerlink" href="#upper-subcommand" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">string</span><span class="w"> </span><span class="no">upper</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">-q</span><span class="w"> </span><span class="g g-Other">|</span><span class="w"> </span><span class="no">--quiet</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">STRING</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">upper</span></code> converts each string argument to uppercase. Exit status: 0 if at least one string was converted to uppercase, else 1. This means that in conjunction with the <strong>-q</strong> flag you can readily test whether a string is already uppercase.</p>
</section>
<section id="regular-expressions">
<h2>Regular Expressions<a class="headerlink" href="#regular-expressions" title="Link to this heading">¶</a></h2>
<p>Both the <code class="docutils literal notranslate"><span class="pre">match</span></code> and <code class="docutils literal notranslate"><span class="pre">replace</span></code> subcommand support regular expressions when used with the <strong>-r</strong> or <strong>--regex</strong> option. The dialect is that of PCRE2.</p>
<p>In general, special characters are special by default, so <code class="docutils literal notranslate"><span class="pre">a+</span></code> matches one or more “a”s, while <code class="docutils literal notranslate"><span class="pre">a\+</span></code> matches an “a” and then a “+”. <code class="docutils literal notranslate"><span class="pre">(a+)</span></code> matches one or more “a”s in a capturing group (<code class="docutils literal notranslate"><span class="pre">(?:XXXX)</span></code> denotes a non-capturing group). For the replacement parameter of <code class="docutils literal notranslate"><span class="pre">replace</span></code>, <code class="docutils literal notranslate"><span class="pre">$n</span></code> refers to the n-th group of the match. In the match parameter, <code class="docutils literal notranslate"><span class="pre">\n</span></code> (e.g. <code class="docutils literal notranslate"><span class="pre">\1</span></code>) refers back to groups.</p>
<p>Some features include repetitions:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">*</span></code> refers to 0 or more repetitions of the previous expression</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">+</span></code> 1 or more</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">?</span></code> 0 or 1.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">{n}</span></code> to exactly n (where n is a number)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">{n,m}</span></code> at least n, no more than m.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">{n,}</span></code> n or more</p></li>
</ul>
<p>Character classes, some of the more important:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">.</span></code> any character except newline</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\d</span></code> a decimal digit and <code class="docutils literal notranslate"><span class="pre">\D</span></code>, not a decimal digit</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\s</span></code> whitespace and <code class="docutils literal notranslate"><span class="pre">\S</span></code>, not whitespace</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\w</span></code> a “word” character and <code class="docutils literal notranslate"><span class="pre">\W</span></code>, a “non-word” character</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[...]</span></code> (where “…” is some characters) is a character set</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[^...]</span></code> is the inverse of the given character set</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[x-y]</span></code> is the range of characters from x-y</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:xxx:]]</span></code> is a named character set</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:^xxx:]]</span></code> is the inverse of a named character set</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:alnum:]]</span></code> : “alphanumeric”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:alpha:]]</span></code> : “alphabetic”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:ascii:]]</span></code> : “0-127”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:blank:]]</span></code> : “space or tab”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:cntrl:]]</span></code> : “control character”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:digit:]]</span></code> : “decimal digit”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:graph:]]</span></code> : “printing, excluding space”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:lower:]]</span></code> : “lower case letter”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:print:]]</span></code> : “printing, including space”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:punct:]]</span></code> : “printing, excluding alphanumeric”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:space:]]</span></code> : “white space”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:upper:]]</span></code> : “upper case letter”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:word:]]</span></code> : “same as w”</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">[[:xdigit:]]</span></code> : “hexadecimal digit”</p></li>
</ul>
<p>Groups:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(...)</span></code> is a capturing group</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(?:...)</span></code> is a non-capturing group</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\n</span></code> is a backreference (where n is the number of the group, starting with 1)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$n</span></code> is a reference from the replacement expression to a group in the match expression.</p></li>
</ul>
<p>And some other things:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">\b</span></code> denotes a word boundary, <code class="docutils literal notranslate"><span class="pre">\B</span></code> is not a word boundary.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">^</span></code> is the start of the string or line, <code class="docutils literal notranslate"><span class="pre">$</span></code> the end.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|</span></code> is “alternation”, i.e. the “or”.</p></li>
</ul>
</section>
<section id="comparison-to-other-tools">
<h2>Comparison to other tools<a class="headerlink" href="#comparison-to-other-tools" title="Link to this heading">¶</a></h2>
<p>Most operations <code class="docutils literal notranslate"><span class="pre">string</span></code> supports can also be done by external tools. Some of these include <code class="docutils literal notranslate"><span class="pre">grep</span></code>, <code class="docutils literal notranslate"><span class="pre">sed</span></code> and <code class="docutils literal notranslate"><span class="pre">cut</span></code>.</p>
<p>If you are familiar with these, it is useful to know how <code class="docutils literal notranslate"><span class="pre">string</span></code> differs from them.</p>
<p>In contrast to these classics, <code class="docutils literal notranslate"><span class="pre">string</span></code> reads input either from stdin or as arguments. <code class="docutils literal notranslate"><span class="pre">string</span></code> also does not deal with files, so it requires redirections to be used with them.</p>
<p>In contrast to <code class="docutils literal notranslate"><span class="pre">grep</span></code>, <code class="docutils literal notranslate"><span class="pre">string</span></code>’s <code class="docutils literal notranslate"><span class="pre">match</span></code> defaults to glob-mode, while <code class="docutils literal notranslate"><span class="pre">replace</span></code> defaults to literal matching. If set to regex-mode, they use PCRE regular expressions, which is comparable to <code class="docutils literal notranslate"><span class="pre">grep</span></code>’s <code class="docutils literal notranslate"><span class="pre">-P</span></code> option. <code class="docutils literal notranslate"><span class="pre">match</span></code> defaults to printing just the match, which is like <code class="docutils literal notranslate"><span class="pre">grep</span></code> with <code class="docutils literal notranslate"><span class="pre">-o</span></code> (use <strong>--entire</strong> to enable grep-like behavior).</p>
<p>Like <code class="docutils literal notranslate"><span class="pre">sed</span></code>’s <code class="docutils literal notranslate"><span class="pre">s/old/new/</span></code> command, <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">replace</span></code> still prints strings that don’t match. <code class="docutils literal notranslate"><span class="pre">sed</span></code>’s <code class="docutils literal notranslate"><span class="pre">-n</span></code> in combination with a <code class="docutils literal notranslate"><span class="pre">/p</span></code> modifier or command is like <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">replace</span> <span class="pre">-f</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">split</span> <span class="pre">somedelimiter</span></code> is a replacement for <code class="docutils literal notranslate"><span class="pre">tr</span> <span class="pre">somedelimiter</span> <span class="pre">\n</span></code>.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li><img src="../_static/fish.png" alt=""
style="width: 80px; height: 80px; vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://fishshell.com/">fish-shell</a> »</li>
<a href="../index.html">fish-shell 4.2.1 documentation</a> »
<li class="nav-item nav-item-1"><a href="../commands.html" >Commands</a> »</li>
<li class="nav-item nav-item-this"><a href="">string - manipulate strings</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</li>
<div id="old-docs-notice" style="display: none">
This documents an old version of fish.
<a href="../../current/">See the latest release.</a>
</div>
</ul>
</div>
<div class="footer">
© Copyright fish-shell developers.
<br />
<a href="https://github.com/fish-shell/fish-shell/issues">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</div>
<script type="text/javascript">
FISH_DOCS_VERSION = "4.2";
function copy_to_clipboard(it) {
// Find the pre tag we're interested in.
var pre = it.target;
while (pre.tagName != "PRE") pre = pre.parentNode;
var txt = "";
// Cheesy: If we have a prompt,
// we only copy prompted lines,
// by splitting and matching and stuff
if (pre.querySelector('span.gp')) {
var texts= [];
for (var line of pre.innerText.split('\n')) {
if (line.match(/^>_?.*/)) {
texts.push(line.replace(/^>_?/, ""));
}
}
txt = texts.join("\n");
} else {
// Even cheesier: If we don't have a prompt, we remove the button text from the end.
var txt = pre.innerText.substring(0, pre.innerText.length - it.target.innerText.length).trim();
}
navigator.clipboard.writeText(txt).then(function() {
// Success - set the text to indicate it,
// then set it back after 2 seconds.
var span = pre.querySelector("button span");
if (span) {
var oldText = span.innerText;
span.innerText = "COPIED!";
setTimeout(function() {
span.innerText = oldText;
}, 2000);
}
}, function() {
});
}
(function () {
// Add copy buttons to all the codeblocks.
var codeblocks = document.querySelectorAll('div > pre');
var button = document.createElement('button');
var span = document.createElement('span');
span.innerText = "COPY";
button.appendChild(span);
for (var i of codeblocks) {
var newButton = button.cloneNode(true);
newButton.addEventListener('click', copy_to_clipboard);
i.appendChild(newButton);
}
})();
</script>
</body>
</html>
|
