blob: c2bb547bc0aca5643f9441230c5a534bdade9175 [file]
/-
Copyright (c) 2016 Microsoft Corporation. All rights reserved.
Released under Apache 2.0 license as described in the file LICENSE.
Author: Leonardo de Moura, Mario Carneiro, Markus Himmel
-/
module
prelude
public import Init.Data.String.Substring
set_option doc.verso true
/-!
# `String.take` and variants
This file contains the implementations of `String.take` and its variants.
-/
public section
namespace String
variable {ρ : Type}
open Slice.Pattern
/--
Returns a {name}`String.Slice` obtained by removing the specified number of characters (Unicode code
points) from the start of the string.
If {name}`n` is greater than {lean}`s.length`, returns an empty slice.
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
Examples:
* {lean}`"red green blue".drop 4 == "green blue".toSlice`
* {lean}`"red green blue".drop 10 == "blue".toSlice`
* {lean}`"red green blue".drop 50 == "".toSlice`
* {lean}`"مرحبا بالعالم".drop 3 == "با بالعالم".toSlice`
-/
@[inline] def drop (s : String) (n : Nat) : Slice :=
s.toSlice.drop n
@[export lean_string_drop]
def Internal.dropImpl (s : String) (n : Nat) : String :=
(String.drop s n).copy
/--
Returns a {name}`String.Slice` obtained by removing the specified number of characters (Unicode code
points) from the end of the string.
If {name}`n` is greater than {lean}`s.length`, returns an empty slice.
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
Examples:
* {lean}`"red green blue".dropEnd 5 == "red green".toSlice`
* {lean}`"red green blue".dropEnd 11 == "red".toSlice`
* {lean}`"red green blue".dropEnd 50 == "".toSlice`
* {lean}`"مرحبا بالعالم".dropEnd 3 == "مرحبا بالع".toSlice`
-/
@[inline] def dropEnd (s : String) (n : Nat) : Slice :=
s.toSlice.dropEnd n
@[deprecated String.dropEnd (since := "2025-11-14")]
def dropRight (s : String) (n : Nat) : String :=
(s.dropEnd n).copy
@[deprecated Slice.dropEnd (since := "2025-11-20")]
def Slice.dropRight (s : Slice) (n : Nat) : Slice :=
s.dropEnd n
@[export lean_string_dropright]
def Internal.dropRightImpl (s : String) (n : Nat) : String :=
(String.dropEnd s n).copy
/--
Returns a {name}`String.Slice` that contains the first {name}`n` characters (Unicode code points) of
{name}`s`.
If {name}`n` is greater than {lean}`s.length`, returns {lean}`s.toSlice`.
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
Examples:
* {lean}`"red green blue".take 3 == "red".toSlice`
* {lean}`"red green blue".take 1 == "r".toSlice`
* {lean}`"red green blue".take 0 == "".toSlice`
* {lean}`"red green blue".take 100 == "red green blue".toSlice`
* {lean}`"مرحبا بالعالم".take 5 == "مرحبا".toSlice`
-/
@[inline] def take (s : String) (n : Nat) : String.Slice :=
s.toSlice.take n
/--
Returns a {name}`String.Slice` that contains the last {name}`n` characters (Unicode code points) of
{name}`s`.
If {name}`n` is greater than {lean}`s.length`, returns {lean}`s.toSlice`.
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
Examples:
* {lean}`"red green blue".takeEnd 4 == "blue".toSlice`
* {lean}`"red green blue".takeEnd 1 == "e".toSlice`
* {lean}`"red green blue".takeEnd 0 == "".toSlice`
* {lean}`"red green blue".takeEnd 100 == "red green blue".toSlice`
* {lean}`"مرحبا بالعالم".takeEnd 5 == "لعالم".toSlice`
-/
@[inline] def takeEnd (s : String) (n : Nat) : String.Slice :=
s.toSlice.takeEnd n
@[deprecated String.takeEnd (since := "2025-11-14")]
def takeRight (s : String) (n : Nat) : String :=
(s.takeEnd n).toString
@[deprecated Slice.takeEnd (since := "2025-11-20")]
def Slice.takeRight (s : Slice) (n : Nat) : Slice :=
s.takeEnd n
/--
Creates a string slice that contains the longest prefix of {name}`s` in which {name}`pat` matched
(potentially repeatedly).
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
This function is generic over all currently supported patterns.
Examples:
* {lean}`"red green blue".takeWhile Char.isLower == "red".toSlice`
* {lean}`"red green blue".takeWhile 'r' == "r".toSlice`
* {lean}`"red red green blue".takeWhile "red " == "red red ".toSlice`
* {lean}`"red green blue".takeWhile (fun (_ : Char) => true) == "red green blue".toSlice`
-/
@[inline] def takeWhile (s : String) (pat : ρ) [ForwardPattern pat] : String.Slice :=
s.toSlice.takeWhile pat
/--
Creates a string slice by removing the longest prefix from {name}`s` in which {name}`pat` matched
(potentially repeatedly).
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
This function is generic over all currently supported patterns.
Examples:
* {lean}`"red green blue".dropWhile Char.isLower == " green blue".toSlice`
* {lean}`"red green blue".dropWhile 'r' == "ed green blue".toSlice`
* {lean}`"red red green blue".dropWhile "red " == "green blue".toSlice`
* {lean}`"red green blue".dropWhile (fun (_ : Char) => true) == "".toSlice`
-/
@[inline] def dropWhile (s : String) (pat : ρ) [ForwardPattern pat] : String.Slice :=
s.toSlice.dropWhile pat
/--
Creates a string slice that contains the longest suffix of {name}`s` in which {name}`pat` matched
(potentially repeatedly).
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
This function is generic over all currently supported patterns.
Examples:
* {lean}`"red green blue".takeEndWhile Char.isLower == "blue".toSlice`
* {lean}`"red green blue".takeEndWhile 'e' == "e".toSlice`
* {lean}`"red green blue".takeEndWhile (fun (_ : Char) => true) == "red green blue".toSlice`
-/
@[inline] def takeEndWhile (s : String) (pat : ρ) [BackwardPattern pat] : String.Slice :=
s.toSlice.takeEndWhile pat
@[deprecated String.takeEndWhile (since := "2025-11-17")]
def takeRightWhile (s : String) (p : Char → Bool) : String :=
(s.takeEndWhile p).toString
@[deprecated Slice.takeEndWhile (since := "2025-11-20")]
def Slice.takeRightWhile (s : Slice) (p : Char → Bool) : Slice :=
s.takeEndWhile p
/--
Creates a new string by removing the longest suffix from {name}`s` in which {name}`pat` matches
(potentially repeatedly).
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
This function is generic over all currently supported patterns.
Examples:
* {lean}`"red green blue".dropEndWhile Char.isLower == "red green ".toSlice`
* {lean}`"red green blue".dropEndWhile 'e' == "red green blu".toSlice`
* {lean}`"red green blue".dropEndWhile (fun (_ : Char) => true) == "".toSlice`
-/
@[inline] def dropEndWhile (s : String) (pat : ρ) [BackwardPattern pat] : String.Slice :=
s.toSlice.dropEndWhile pat
@[deprecated String.dropEndWhile (since := "2025-11-17")]
def dropRightWhile (s : String) (p : Char → Bool) : String :=
(s.dropEndWhile p).toString
@[deprecated Slice.dropEndWhile (since := "2025-11-20")]
def Slice.dropRightWhile (s : Slice) (p : Char → Bool) : Slice :=
s.dropEndWhile p
/--
Checks whether the first string ({name}`s`) begins with the pattern ({name}`pat`).
{name (scope := "Init.Data.String.TakeDrop")}`String.isPrefixOf` is a version that takes the
potential prefix before the string.
Examples:
* {lean}`"red green blue".startsWith "red" = true`
* {lean}`"red green blue".startsWith "green" = false`
* {lean}`"red green blue".startsWith "" = true`
* {lean}`"red green blue".startsWith 'r' = true`
* {lean}`"red green blue".startsWith Char.isLower = true`
-/
@[inline] def startsWith (s : String) (pat : ρ) [ForwardPattern pat] : Bool :=
s.toSlice.startsWith pat
/--
Checks whether the second string ({name}`s`) begins with a prefix ({name}`p`).
This function is generic over all currently supported patterns.
{name}`String.startsWith` is a version that takes the potential prefix after the string.
Examples:
* {lean}`"red".isPrefixOf "red green blue" = true`
* {lean}`"green".isPrefixOf "red green blue" = false`
* {lean}`"".isPrefixOf "red green blue" = true`
-/
@[inline] def isPrefixOf (p : String) (s : String) : Bool :=
s.startsWith p
@[export lean_string_isprefixof]
def Internal.isPrefixOfImpl (p : String) (s : String) : Bool :=
String.isPrefixOf p s
/--
Checks whether the string ({name}`s`) ends with the pattern ({name}`pat`).
This function is generic over all currently supported patterns.
Examples:
* {lean}`"red green blue".endsWith "blue" = true`
* {lean}`"red green blue".endsWith "green" = false`
* {lean}`"red green blue".endsWith "" = true`
* {lean}`"red green blue".endsWith 'e' = true`
* {lean}`"red green blue".endsWith Char.isLower = true`
-/
@[inline] def endsWith (s : String) (pat : ρ) [BackwardPattern pat] : Bool :=
s.toSlice.endsWith pat
/--
Removes trailing whitespace from a string by returning a slice whose end position is the last
non-whitespace character, or the start position if there is no non-whitespace character.
“Whitespace” is defined as characters for which {name}`Char.isWhitespace` returns {name}`true`.
Examples:
* {lean}`"abc".trimAsciiEnd == "abc".toSlice`
* {lean}`" abc".trimAsciiEnd == " abc".toSlice`
* {lean}`"abc \t ".trimAsciiEnd == "abc".toSlice`
* {lean}`" abc ".trimAsciiEnd == " abc".toSlice`
* {lean}`"abc\ndef\n".trimAsciiEnd == "abc\ndef".toSlice`
-/
@[inline] def trimAsciiEnd (s : String) : String.Slice :=
s.toSlice.trimAsciiEnd
@[deprecated String.trimAsciiEnd (since := "2025-11-17")]
def trimRight (s : String) : String :=
s.trimAsciiEnd.copy
@[deprecated Slice.trimAsciiEnd (since := "2025-11-20")]
def Slice.trimRight (s : Slice) : Slice :=
s.trimAsciiEnd
/--
Removes leading whitespace from a string by returning a slice whose start position is the first
non-whitespace character, or the end position if there is no non-whitespace character.
“Whitespace” is defined as characters for which {name}`Char.isWhitespace` returns {name}`true`.
Examples:
* {lean}`"abc".trimAsciiStart == "abc".toSlice`
* {lean}`" abc".trimAsciiStart == "abc".toSlice`
* {lean}`"abc \t ".trimAsciiStart == "abc \t ".toSlice`
* {lean}`" abc ".trimAsciiStart == "abc ".toSlice`
* {lean}`"abc\ndef\n".trimAsciiStart == "abc\ndef\n".toSlice`
-/
@[inline] def trimAsciiStart (s : String) : String.Slice :=
s.toSlice.trimAsciiStart
@[deprecated String.trimAsciiStart (since := "2025-11-17")]
def trimLeft (s : String) : String :=
s.trimAsciiStart.copy
@[deprecated Slice.trimAsciiStart (since := "2025-11-20")]
def Slice.trimLeft (s : Slice) : Slice :=
s.trimAsciiStart
/--
Removes leading and trailing whitespace from a string.
“Whitespace” is defined as characters for which {name}`Char.isWhitespace` returns {name}`true`.
Examples:
* {lean}`"abc".trimAscii == "abc".toSlice`
* {lean}`" abc".trimAscii == "abc".toSlice`
* {lean}`"abc \t ".trimAscii == "abc".toSlice`
* {lean}`" abc ".trimAscii == "abc".toSlice`
* {lean}`"abc\ndef\n".trimAscii == "abc\ndef".toSlice`
-/
@[inline] def trimAscii (s : String) : String.Slice :=
s.toSlice.trimAscii
@[deprecated String.trimAscii (since := "2025-11-17")]
def trim (s : String) : String :=
s.trimAscii.copy
@[deprecated Slice.trimAscii (since := "2025-11-20")]
def Slice.trim (s : Slice) : Slice :=
s.trimAscii
@[export lean_string_trim]
def Internal.trimImpl (s : String) : String :=
(String.trimAscii s).copy
/--
Repeatedly increments a position in a string, as if by {name}`String.Pos.Raw.next`, while the
predicate {name}`p` returns {lean}`true` for the character at the position. Stops incrementing at
the end of the string or when {name}`p` returns {lean}`false` for the current character.
Examples:
* {lean}`let s := " a "; ((0 : Pos.Raw).nextWhile s Char.isWhitespace).get s = 'a'`
* {lean}`let s := "a "; ((0 : Pos.Raw).nextWhile s Char.isWhitespace).get s = 'a'`
* {lean}`let s := "ba "; (Pos.Raw.nextWhile s Char.isWhitespace 0).get s = 'b'`
-/
@[inline] def Pos.Raw.nextWhile (s : String) (p : Char → Bool) (i : String.Pos.Raw) : String.Pos.Raw :=
Substring.Raw.takeWhileAux s s.rawEndPos p i
@[deprecated Pos.Raw.nextWhile (since := "2025-10-10")]
abbrev nextWhile (s : String) (p : Char → Bool) (i : String.Pos.Raw) : String.Pos.Raw :=
Pos.Raw.nextWhile s p i
@[export lean_string_nextwhile]
def Internal.nextWhileImpl (s : String) (p : Char → Bool) (i : String.Pos.Raw) : String.Pos.Raw :=
i.nextWhile s p
/--
Repeatedly increments a position in a string, as if by {name}`String.Pos.Raw.next`, while the predicate
{name}`p` returns {lean}`false` for the character at the position. Stops incrementing at the end of
the string or when {name}`p` returns {lean}`true` for the current character.
Examples:
* {lean}`let s := " a "; (Pos.Raw.nextUntil s Char.isWhitespace 0).get s = ' '`
* {lean}`let s := " a "; (Pos.Raw.nextUntil s Char.isAlpha 0).get s = 'a'`
* {lean}`let s := "a "; (Pos.Raw.nextUntil s Char.isWhitespace 0).get s = ' '`
-/
@[inline] def Pos.Raw.nextUntil (s : String) (p : Char → Bool) (i : String.Pos.Raw) : String.Pos.Raw :=
nextWhile s (fun c => !p c) i
@[deprecated Pos.Raw.nextUntil (since := "2025-10-10")]
def nextUntil (s : String) (p : Char → Bool) (i : String.Pos.Raw) : String.Pos.Raw :=
i.nextUntil s p
/--
If {name}`pat` matches a prefix of {name}`s`, returns the remainder. Returns {name}`none` otherwise.
Use {name (scope := "Init.Data.String.Slice")}`String.dropPrefix` to return the slice
unchanged when {name}`pat` does not match a prefix.
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
This function is generic over all currently supported patterns.
Examples:
* {lean}`"red green blue".dropPrefix? "red " == some "green blue".toSlice`
* {lean}`"red green blue".dropPrefix? "reed " == none`
* {lean}`"red green blue".dropPrefix? 'r' == some "ed green blue".toSlice`
* {lean}`"red green blue".dropPrefix? Char.isLower == some "ed green blue".toSlice`
-/
def dropPrefix? (s : String) (pat : ρ) [ForwardPattern pat] : Option String.Slice :=
s.toSlice.dropPrefix? pat
/--
If {name}`pat` matches a suffix of {name}`s`, returns the remainder. Returns {name}`none` otherwise.
Use {name (scope := "Init.Data.String.TakeDrop")}`String.dropSuffix` to return the slice
unchanged when {name}`pat` does not match a prefix.
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
This function is generic over all currently supported patterns.
Examples:
* {lean}`"red green blue".dropSuffix? " blue" == some "red green".toSlice`
* {lean}`"red green blue".dropSuffix? "bluu " == none`
* {lean}`"red green blue".dropSuffix? 'e' == some "red green blu".toSlice`
* {lean}`"red green blue".dropSuffix? Char.isLower == some "red green blu".toSlice`
-/
def dropSuffix? (s : String) (pat : ρ) [BackwardPattern pat] : Option String.Slice :=
s.toSlice.dropSuffix? pat
/--
If {name}`pat` matches a prefix of {name}`s`, returns the remainder. Returns {name}`s` unmodified
otherwise.
Use {name}`String.dropPrefix?` to return {name}`none` when {name}`pat` does not match a prefix.
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
This function is generic over all currently supported patterns.
Examples:
* {lean}`"red green blue".dropPrefix "red " == "green blue".toSlice`
* {lean}`"red green blue".dropPrefix "reed " == "red green blue".toSlice`
* {lean}`"red green blue".dropPrefix 'r' == "ed green blue".toSlice`
* {lean}`"red green blue".dropPrefix Char.isLower == "ed green blue".toSlice`
-/
def dropPrefix (s : String) (pat : ρ) [ForwardPattern pat] : String.Slice :=
s.toSlice.dropPrefix pat
@[deprecated String.dropPrefix (since := "2025-11-17")]
def stripPrefix (s pre : String) : String :=
(s.dropPrefix pre).toString
@[deprecated Slice.dropPrefix (since := "2025-11-20")]
def Slice.stripPrefix (s pre : Slice) : Slice :=
s.dropPrefix pre
/--
If {name}`pat` matches a suffix of {name}`s`, returns the remainder. Returns {name}`s` unmodified
otherwise.
Use {name}`String.dropSuffix?` to return {name}`none` when {name}`pat` does not match a prefix.
This is a cheap operation because it does not allocate a new string to hold the result.
To convert the result into a string, use {name}`String.Slice.copy`.
This function is generic over all currently supported patterns.
Examples:
* {lean}`"red green blue".dropSuffix " blue" == "red green".toSlice`
* {lean}`"red green blue".dropSuffix "bluu " == "red green blue".toSlice`
* {lean}`"red green blue".dropSuffix 'e' == "red green blu".toSlice`
* {lean}`"red green blue".dropSuffix Char.isLower == "red green blu".toSlice`
-/
def dropSuffix (s : String) (pat : ρ) [BackwardPattern pat] : String.Slice :=
s.toSlice.dropSuffix pat
@[deprecated String.dropSuffix (since := "2025-11-17")]
def stripSuffix (s : String) (suff : String) : String :=
(s.dropSuffix suff).toString
@[deprecated Slice.dropSuffix (since := "2025-11-20")]
def Slice.stripSuffix (s : Slice) (suff : Slice) : Slice :=
s.dropSuffix suff
end String