`str substring` for strings

Get part of a string. Note that the first character of a string is index 0.

Command Type

built-in

Signature

> str substring {flags} (range) ...rest

Flags

--grapheme-clusters, -g: Count indexes and split using grapheme clusters (all visible chars have length 1).
--utf-8-bytes, -b: Count indexes and split using UTF-8 bytes (default; non-ASCII chars have length 2+).

Parameters

range: The indexes to substring [start end].
...rest: For a data structure input, turn strings at the given cell paths into substrings.

Input/output types:

input	output
string	string
list<string>	list<string>
table	table
record	record

Examples

Get a substring "nushell" from the text "good nushell" using a range.

> 'good nushell' | str substring 5..11
nushell

Count indexes and split using grapheme clusters.

> '🇯🇵ほげ ふが ぴよ' | str substring --grapheme-clusters 4..5
ふが

Get a substring using a negative end index.

> 'good nushell' | str substring 5..-2
nushel

Get a substring from a string field in a record.

> { name: 'Paul Smith', number: 13 } | str substring 0..3 name
╭────────┬──────╮
│ name   │ Paul │
│ number │ 13   │
╰────────┴──────╯

Get substrings from string fields in a table.

> [{name: 'Alice', age: 24}, {name: 'Robert', age: 23}] | str substring 0..2 name
╭───┬──────┬─────╮
│ # │ name │ age │
├───┼──────┼─────┤
│ 0 │ Ali  │  24 │
│ 1 │ Rob  │  23 │
╰───┴──────┴─────╯

Get substrings from a list of strings.

> ['good nushell' 'hello world'] | str substring 0..3
╭───┬──────╮
│ 0 │ good │
│ 1 │ hell │
╰───┴──────╯