Nushell
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
  • Introduction
  • Installation
    • Default Shell
  • Getting Started
    • Quick Tour
    • Moving Around the System
    • Thinking in Nu
    • Nushell Cheat Sheet
  • Nu Fundamentals
    • Types of Data
    • Loading Data
    • Data Formats
    • Working with SQLite
    • Pipelines
    • Working with Strings
    • Regular Expressions
    • Working with Binary Data
    • Working with Lists
    • Working with Records
    • Working with Numbers
    • Working with Tables
    • Working with Paths
    • Navigating and Accessing Structured Data
    • Special Variables
  • Programming in Nu
    • Custom Commands
    • Aliases
    • Operators
    • Variables
    • Control Flow
    • Scripts
    • Modules
      • Using Modules
      • Creating Modules
    • Overlays
    • Sorting
    • Testing your Nushell Code
    • Debugging Scripts
    • Language Server
    • Best Practices
  • Nu as a Shell
    • Configuration
    • Configuration Reference
    • Environment
    • Stdout, Stderr, and Exit Codes
    • Working with the Terminal
    • Running System (External) Commands
    • How to Configure 3rd Party Prompts
    • Directory Stack
    • Reedline, Nu's Line Editor
    • Custom Completions
    • Externs
    • Coloring and Theming in Nu
    • Hooks
    • Background Jobs
  • Coming to Nu
    • Coming from Bash
    • Coming from CMD.EXE
    • Coming from PowerShell
    • Nu map from other shells and domain specific languages
    • Nu Map from Imperative Languages
    • Nu Map from Functional Languages
    • Nushell operator map
  • Design Notes
    • How Nushell Code Gets Run
  • (Not So) Advanced
    • Standard Library
      • std/assert
      • std/bench
      • std/clip
      • std/config
      • std/dt
      • std/formats
      • std/help
      • std/input
      • std/iter
      • std/log
      • std/math
      • std/random
      • std/util
      • std/xml
      • std-rfc
    • Dataframes
      • Dataframe Operations
      • Column Selectors
      • Math Expressions
      • String Expressions
      • Dates and Times in Dataframes
      • Masks and Conditionals
      • Aggregations and Window Functions
    • Metadata
    • Creating Your Own Errors
    • Parallelism
    • Plugins
    • explore
    • Building TUIs with tui
    • MCP Server

std/iter

The std/iter module has commands for working through lists, in the style of the iterator functions of other languages. They are prefixed with iter so they don't clash with built-in commands such as find. Import the module without a glob to keep the prefix:

use std/iter

Each command takes a list or a range as input, and most of them take a closure.

  • iter find
  • iter find-index
  • iter intersperse
  • iter scan
  • iter filter-map
  • iter flat-map
  • iter zip-with
  • iter zip-into-record

iter find

iter find returns the first item for which the closure returns true, or null if there is none:

["shell" "abc" "around" "nushell"] | iter find {|e| $e starts-with "a" }
# => abc

An error inside the closure counts as false for that item, and so does a result that isn't a boolean. The search goes on with the next item:

[1 "two" 3 4] | iter find {|e| $e mod 2 == 0 }
# => 4

Here "two" mod 2 is an error, so "two" is skipped. The same leniency hides mistakes. A closure that never returns a boolean makes iter find return null for every input.

iter find-index

iter find-index works like iter find but returns the index of the first matching item:

[a b c] | iter find-index {|x| $x == "b" }
# => 1

When nothing matches, it returns null:

[3 5 13 91] | iter find-index {|x| $x mod 2 == 0 } | describe
# => nothing

iter intersperse

iter intersperse puts a separator between each pair of neighboring items:

[1 2 3 4] | iter intersperse 0 | to nuon
# => [1, 0, 2, 0, 3, 0, 4]

A list with one item or none comes back unchanged. The separator can be any value. To join strings with a separator into one string, use str join instead.

iter scan

iter scan works like reduce but returns every intermediate result instead of only the last one. The closure receives the current item first and the accumulator second. The accumulator is also its pipeline input, $in, so {|x| $in + $x } works as well as {|x, acc| $acc + $x }. What the closure returns becomes the next accumulator.

Without --fold, the first item is the starting accumulator, and it is also the first item of the result:

[1 2 3 4] | iter scan {|x, acc| $acc + $x } | to nuon
# => [1, 3, 6, 10]

--fold (-f) gives the starting accumulator. It becomes the first item of the result, so the result is one item longer than the input:

[a b c] | iter scan --fold "" {|x, acc| $acc + $x } | to nuon
# => ["", a, ab, abc]

An empty input gives an empty list without --fold, and a list holding only the --fold value with it.

iter filter-map

iter filter-map calls the closure on each item and keeps the results, except null results and errors, which it drops. Use it to transform items and skip the ones that don't fit in one step:

[2 5 "4" 7] | iter filter-map {|e| $e ** 2 } | to nuon
# => [4, 25, 49]
[{a: 1} {b: 2} {a: 3}] | iter filter-map {|r| $r.a? } | to nuon
# => [1, 3]

Only null is dropped. A result of false or 0 stays in the list.

iter flat-map

iter flat-map calls the closure on each item and flattens the lists it returns into one list. It is the same as each --flatten with the closure:

1..3 | iter flat-map {|e| 0..<$e | each { $e } } | to nuon
# => [1, 2, 2, 3, 3, 3]

iter zip-with

iter zip-with pairs each item of the input with the item at the same position in another list, as zip does, and then calls the closure with the two items as its two parameters. It returns the closure's results:

[1 2 3] | iter zip-with [10 20 30] {|a, b| $a + $b } | to nuon
# => [11, 22, 33]

As with zip, the result is as long as the shorter of the two.

iter zip-into-record

iter zip-into-record uses the input items as keys and the items of another list as values. Despite its name, it returns a table with one row, not a record:

[name size] | iter zip-into-record [report.txt 12kb]
# => ╭───┬────────────┬─────────╮
# => │ # │    name    │  size   │
# => ├───┼────────────┼─────────┤
# => │ 0 │ report.txt │ 12.0 kB │
# => ╰───┴────────────┴─────────╯

Add | first to get the record. Keys that aren't strings are converted to strings, the extra items of the longer list are dropped, and if a key appears twice, the later value wins.

Edit this page on GitHub
Contributors: fdncred
Prev
std/input
Next
std/log