From 768d537a0f6974da8882e16552292545246d344e Mon Sep 17 00:00:00 2001
From: Jishnu Bhattacharya <jishnub.github@gmail.com>
Date: Wed, 1 Feb 2023 02:15:25 +0400
Subject: [PATCH] Link to `sort!` in the docs of `searchsorted*` and update
 examples (#48449)

The keyword arguments are explained in `sort!`, and it would be good to know where to look. Also, I've added an example of how to use the `by` keyword argument in each case.
---
 base/sort.jl | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/base/sort.jl b/base/sort.jl
index b3dbaf9ac2d79..2ecc7ff62b291 100644
--- a/base/sort.jl
+++ b/base/sort.jl
@@ -295,6 +295,8 @@ according to the order specified by the `by`, `lt` and `rev` keywords, assuming
 is already sorted in that order. Return an empty range located at the insertion point
 if `a` does not contain values equal to `x`.
 
+See [`sort!`](@ref) for an explanation of the keyword arguments `by`, `lt` and `rev`.
+
 See also: [`insorted`](@ref), [`searchsortedfirst`](@ref), [`sort`](@ref), [`findall`](@ref).
 
 # Examples
@@ -313,6 +315,9 @@ julia> searchsorted([1, 2, 4, 5, 5, 7], 9) # no match, insert at end
 
 julia> searchsorted([1, 2, 4, 5, 5, 7], 0) # no match, insert at start
 1:0
+
+julia> searchsorted([1=>"one", 2=>"two", 2=>"two", 4=>"four"], 2=>"two", by=first) # compare the keys of the pairs
+2:3
 ```
 """ searchsorted
 
@@ -325,6 +330,8 @@ specified order. Return `lastindex(a) + 1` if `x` is greater than all values in
 
 `insert!`ing `x` at this index will maintain sorted order.
 
+See [`sort!`](@ref) for an explanation of the keyword arguments `by`, `lt` and `rev`.
+
 See also: [`searchsortedlast`](@ref), [`searchsorted`](@ref), [`findfirst`](@ref).
 
 # Examples
@@ -343,6 +350,9 @@ julia> searchsortedfirst([1, 2, 4, 5, 5, 7], 9) # no match, insert at end
 
 julia> searchsortedfirst([1, 2, 4, 5, 5, 7], 0) # no match, insert at start
 1
+
+julia> searchsortedfirst([1=>"one", 2=>"two", 4=>"four"], 3=>"three", by=first) # Compare the keys of the pairs
+3
 ```
 """ searchsortedfirst
 
@@ -353,6 +363,8 @@ Return the index of the last value in `a` less than or equal to `x`, according t
 specified order. Return `firstindex(a) - 1` if `x` is less than all values in `a`. `a` is
 assumed to be sorted.
 
+See [`sort!`](@ref) for an explanation of the keyword arguments `by`, `lt` and `rev`.
+
 # Examples
 ```jldoctest
 julia> searchsortedlast([1, 2, 4, 5, 5, 7], 4) # single match
@@ -369,6 +381,9 @@ julia> searchsortedlast([1, 2, 4, 5, 5, 7], 9) # no match, insert at end
 
 julia> searchsortedlast([1, 2, 4, 5, 5, 7], 0) # no match, insert at start
 0
+
+julia> searchsortedlast([1=>"one", 2=>"two", 4=>"four"], 3=>"three", by=first) # compare the keys of the pairs
+2
 ```
 """ searchsortedlast