Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sorted the string.fsi entries and added examples to each one #12130

Merged
merged 8 commits into from
Sep 9, 2021
Merged

Sorted the string.fsi entries and added examples to each one #12130

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0cc05f9
Sorted the string.fsi entries and added examples to each one
MecuStefan Sep 8, 2021
918673f
Applying suggestions to the String examples
MecuStefan Sep 8, 2021
1f4e790
Following the suggestion that is more clear.
MecuStefan Sep 8, 2021
36935c9
Sorted the string.fsi entries and added examples to each one
MecuStefan Sep 8, 2021
712f32f
Applying suggestions to the String examples
MecuStefan Sep 8, 2021
04dc5d6
Following the suggestion that is more clear.
MecuStefan Sep 8, 2021
23d6289
Merge branch 'dotnet:main' into main
MecuStefan Sep 9, 2021
8d161ac
Merge branch 'main' of github.com:MecuStefan/fsharp
MecuStefan Sep 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
254 changes: 194 additions & 60 deletions src/fsharp/FSharp.Core/string.fsi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,30 @@ namespace Microsoft.FSharp.Core
[<RequireQualifiedAccess>]
module String =

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
///
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
/// <param name="str">The input string.</param>
///
/// <returns>The concatenated string.</returns>
///
/// <example id="collect-example-1"> The following samples shows how to interspace spaces in a text
/// <code lang="fsharp">
/// let input = "Stefan says: Hi!"
/// input |> String.collect (sprintf "%c ") // evaluates "S t e f a n s a y s : H i ! "
/// </code>
/// </example>
///
/// <example id="collect-example-2"> How to show the ASCII representation of a very secret text
/// <code lang="fsharp">
/// "Secret" |> String.collect (fun chr -> int chr |> sprintf "%d ") // evaluates "83 101 99 114 101 116 "
/// </code>
/// </example>
[<CompiledName("Collect")>]
val collect: mapping:(char -> string) -> str:string -> string

/// <summary>Returns a new string made by concatenating the given strings
/// with separator <c>sep</c>, that is <c>a1 + sep + ... + sep + aN</c>.</summary>
/// <param name="sep">The separator string to be inserted between the strings
Expand All @@ -27,54 +51,41 @@ namespace Microsoft.FSharp.Core
/// <returns>A new string consisting of the concatenated strings separated by
/// the separation string.</returns>
/// <exception cref="T:System.ArgumentNullException">Thrown when <c>strings</c> is null.</exception>
///
/// <example id="concat-example-1">
/// <code lang="fsharp">
/// let input1 = ["Stefan"; "says:"; "Hello"; "there!"]
/// input1 |> String.concat " " // evaluates "Stefan says: Hello there!"
///
/// let input2 = [0..9] |> List.map string
/// input2 |> String.concat "" // evaluates "0123456789"
/// input2 |> String.concat ", " // evaluates "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
///
/// let input3 = ["No comma"]
/// input3 |> String.concat "," // evaluates "No comma"
/// </code>
MecuStefan marked this conversation as resolved.
Show resolved Hide resolved
/// </example>
[<CompiledName("Concat")>]
val concat: sep:string -> strings: seq<string> -> string

/// <summary>Applies the function <c>action</c> to each character in the string.</summary>
///
/// <param name="action">The function to be applied to each character of the string.</param>
/// <param name="str">The input string.</param>
[<CompiledName("Iterate")>]
val iter: action:(char -> unit) -> str:string -> unit

/// <summary>Applies the function <c>action</c> to the index of each character in the string and the
/// character itself.</summary>
///
/// <param name="action">The function to apply to each character and index of the string.</param>
/// <param name="str">The input string.</param>
[<CompiledName("IterateIndexed")>]
val iteri: action:(int -> char -> unit) -> str:string -> unit

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string.</summary>
///
/// <param name="mapping">The function to apply to the characters of the string.</param>
/// <param name="str">The input string.</param>
///
/// <returns>The resulting string.</returns>
[<CompiledName("Map")>]
val map: mapping:(char -> char) -> str:string -> string

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each character and index of the input string.</summary>
///
/// <param name="mapping">The function to apply to each character and index of the string.</param>
/// <param name="str">The input string.</param>
///
/// <returns>The resulting string.</returns>
[<CompiledName("MapIndexed")>]
val mapi: mapping:(int -> char -> char) -> str:string -> string

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <summary>Tests if any character of the string satisfies the given predicate.</summary>
///
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
/// <param name="predicate">The function to test each character of the string.</param>
/// <param name="str">The input string.</param>
///
/// <returns>The concatenated string.</returns>
[<CompiledName("Collect")>]
val collect: mapping:(char -> string) -> str:string -> string
/// <returns>True if any character returns true for the predicate and false otherwise.</returns>
///
/// <example id="exists-example-1"> Looking for uppercase characters
/// <code lang="fsharp">
/// open System
///
/// "Yoda" |> String.exists Char.IsUpper // evaluates true
///
/// "nope" |> String.exists Char.IsUpper // evaluates false
/// </code>
MecuStefan marked this conversation as resolved.
Show resolved Hide resolved
/// </example>
[<CompiledName("Exists")>]
val exists: predicate:(char -> bool) -> str:string -> bool

/// <summary>Builds a new string containing only the characters of the input string
/// for which the given predicate returns "true".</summary>
Expand All @@ -85,9 +96,44 @@ namespace Microsoft.FSharp.Core
/// <param name="str">The input string.</param>
///
/// <returns>The resulting string.</returns>
///
/// <example id="filter-example-1"> Filtering out just alphanumeric characters
/// <code lang="fsharp">
/// open System
///
/// let input = "0 1 2 3 4 5 6 7 8 9 a A m M"
/// input |> String.filter Uri.IsHexDigit // evaluates "123456789aA"
/// </code>
/// </example>
/// <example id="filter-example-2"> Filtering out just digits
/// <code lang="fsharp">
/// open System
///
/// "hello" |> String.filter Char.IsDigit // evaluates ""
/// </code>
MecuStefan marked this conversation as resolved.
Show resolved Hide resolved
/// </example>
[<CompiledName("Filter")>]
val filter: predicate:(char -> bool) -> str:string -> string

/// <summary>Tests if all characters in the string satisfy the given predicate.</summary>
///
/// <param name="predicate">The function to test each character of the string.</param>
/// <param name="str">The input string.</param>
///
/// <returns>True if all characters return true for the predicate and false otherwise.</returns>
///
/// <example id="forall-example-1"> Looking for lowercase characters
/// <code lang="fsharp">
/// open System
///
/// "all are lower" |> String.forall Char.IsLower // evaluates false
///
/// "allarelower" |> String.forall Char.IsLower // evaluates true
/// </code>
/// </example>
[<CompiledName("ForAll")>]
val forall: predicate:(char -> bool) -> str:string -> bool

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each index from <c>0</c> to <c>count-1</c> and concatenating the resulting
/// strings.</summary>
Expand All @@ -98,26 +144,115 @@ namespace Microsoft.FSharp.Core
///
/// <returns>The constructed string.</returns>
/// <exception cref="T:System.ArgumentException">Thrown when <c>count</c> is negative.</exception>
///
/// <example id="init-example-1"> Enumerate digits ASCII codes
/// <code lang="fsharp">
/// String.init 10 (fun i -> int '0' + i |> sprintf "%d ") // evaluates "48 49 50 51 52 53 54 55 56 57 "
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These lines are getting too long I think (102 characters), suggest a maximum of 80 with a preference for 60

        /// <code lang="fsharp">
        /// String.init 10 (fun i -> int '0' + i |> sprintf "%d ")
        /// </code>
        /// evaluates to
        /// <code>
        /// "48 49 50 51 52 53 54 55 56 57 "
        /// </code>

across all the samples.

/// </code>
/// </example>
[<CompiledName("Initialize")>]
val init: count:int -> initializer:(int -> string) -> string

/// <summary>Tests if all characters in the string satisfy the given predicate.</summary>
/// <summary>Applies the function <c>action</c> to each character in the string.</summary>
///
/// <param name="predicate">The function to test each character of the string.</param>
/// <param name="action">The function to be applied to each character of the string.</param>
/// <param name="str">The input string.</param>
///
/// <example id="iter-example-1"> Printing the ASCII code for each characater in the string
/// <code lang="fsharp">
/// let input = "Hello"
/// input |> String.iter (fun c -> printfn "%c %d" c (int c))
/// // evaluates unit
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

English language parts outside of <code>

/// // prints:
/// H 72
/// e 101
/// l 108
/// l 108
/// o 111
/// </code>
/// </example>
[<CompiledName("Iterate")>]
val iter: action:(char -> unit) -> str:string -> unit

/// <summary>Applies the function <c>action</c> to the index of each character in the string and the
/// character itself.</summary>
///
/// <returns>True if all characters return true for the predicate and false otherwise.</returns>
[<CompiledName("ForAll")>]
val forall: predicate:(char -> bool) -> str:string -> bool
/// <param name="action">The function to apply to each character and index of the string.</param>
/// <param name="str">The input string.</param>
///
/// <example id="iteri-example-1"> Numbering the characters and printing the associated ASCII code
/// for each characater in the input string
/// <code lang="fsharp">
/// let input = "Hello"
/// input |> String.iteri (fun i c -> printfn "%d. %c %d" (i + 1) c (int c))
/// // evaluates unit
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these english language parts should not be in <code>

/// // prints:
/// 1. H 72
/// 2. e 101
/// 3. l 108
/// 4. l 108
/// 5. o 111
/// </code>
/// </example>
[<CompiledName("IterateIndexed")>]
val iteri: action:(int -> char -> unit) -> str:string -> unit

/// <summary>Tests if any character of the string satisfies the given predicate.</summary>
/// <summary>Returns the length of the string.</summary>
///
/// <param name="predicate">The function to test each character of the string.</param>
/// <param name="str">The input string.</param>
///
/// <returns>True if any character returns true for the predicate and false otherwise.</returns>
[<CompiledName("Exists")>]
val exists: predicate:(char -> bool) -> str:string -> bool
/// <returns>The number of characters in the string.</returns>
///
/// <example id="length-example-1"> Getting the length of different strings
/// <code lang="fsharp">
/// String.length null // evaluates 0
/// String.length "" // evaluates 0
/// String.length "123" // evaluates 3
/// </code>
/// </example>
[<CompiledName("Length")>]
val length: str:string -> int

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string.</summary>
///
/// <param name="mapping">The function to apply to the characters of the string.</param>
/// <param name="str">The input string.</param>
///
/// <returns>The resulting string.</returns>
///
/// <example id="map-example-1"> Changing case to upper for all characters in the input string
/// <code lang="fsharp">
/// open System
/// let input = "Hello there!"
/// input |> String.map Char.ToUpper // evaluates "HELLO THERE!"
/// </code>
/// </example>
[<CompiledName("Map")>]
val map: mapping:(char -> char) -> str:string -> string

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each character and index of the input string.</summary>
///
/// <param name="mapping">The function to apply to each character and index of the string.</param>
/// <param name="str">The input string.</param>
///
/// <returns>The resulting string.</returns>
///
/// <example id="mapi-example-1"> Alternating case for all characters in the input string
/// <code lang="fsharp">
/// open System
///
/// let alternateCase indx chr =
/// if 0 = indx % 2
/// then Char.ToUpper chr
/// else Char.ToLower chr
/// let input = "Hello there!"
/// input |> String.mapi alternateCase // evaluates "HeLlO ThErE!"
/// </code>
/// </example>
[<CompiledName("MapIndexed")>]
val mapi: mapping:(int -> char -> char) -> str:string -> string

/// <summary>Returns a string by concatenating <c>count</c> instances of <c>str</c>.</summary>
///
Expand All @@ -126,14 +261,13 @@ namespace Microsoft.FSharp.Core
///
/// <returns>The concatenated string.</returns>
/// <exception cref="T:System.ArgumentException">Thrown when <c>count</c> is negative.</exception>
///
/// <example id="replicate-example-1">
/// <code lang="fsharp">
/// "Do it!" |> String.replicate 3 // evaluates "Do it!Do it!Do it!"
/// </code>
/// </example>
[<CompiledName("Replicate")>]
val replicate: count:int -> str: string -> string

/// <summary>Returns the length of the string.</summary>
///
/// <param name="str">The input string.</param>
///
/// <returns>The number of characters in the string.</returns>
[<CompiledName("Length")>]
val length: str:string -> int