Rollup merge of #130416 - BatmanAoD:130122-sort-by-docs, r=Mark-Simul… · qinheping/verify-rust-std@a31f882 (original) (raw)

`@@ -180,10 +180,9 @@ impl [T] {

180

`/// This sort is stable (i.e., does not reorder equal elements) and O(n * log(n))

181

`/// worst-case.

182

`///

183

`` -

/// If the implementation of [Ord] for T does not implement a [total order] the resulting

184

/// order of elements in the slice is unspecified. All original elements will remain in the

185

/// slice and any possible modifications via interior mutability are observed in the input. Same

186

`` -

/// is true if the implementation of [Ord] for T panics.

183

`` +

/// If the implementation of [Ord] for T does not implement a [total order], the function

184

/// may panic; even if the function exits normally, the resulting order of elements in the slice

185

/// is unspecified. See also the note on panicking below.

187

186

`///

188

187

`/// When applicable, unstable sorting is preferred because it is generally faster than stable

189

188

`/// sorting and it doesn't allocate auxiliary memory. See

`@@ -212,7 +211,15 @@ impl [T] {

212

211

`///

213

212

`/// # Panics

214

213

`///

215

`` -

/// May panic if the implementation of [Ord] for T does not implement a [total order].

214

`` +

/// May panic if the implementation of [Ord] for T does not implement a [total order], or if

215

`` +

/// the [Ord] implementation itself panics.

216

///

217

/// All safe functions on slices preserve the invariant that even if the function panics, all

218

/// original elements will remain in the slice and any possible modifications via interior

219

/// mutability are observed in the input. This ensures that recovery code (for instance inside

220

`` +

/// of a Drop or following a catch_unwind) will still have access to all the original

221

`` +

/// elements. For instance, if the slice belongs to a Vec, the Vec::drop method will be able

222

/// to dispose of all contained elements.

216

223

`///

217

224

`/// # Examples

218

225

`///

`@@ -241,10 +248,9 @@ impl [T] {

241

248

`/// This sort is stable (i.e., does not reorder equal elements) and O(n * log(n))

242

249

`/// worst-case.

243

250

`///

244

`` -

/// If the comparison function compare does not implement a [total order] the resulting order

245

/// of elements in the slice is unspecified. All original elements will remain in the slice and

246

/// any possible modifications via interior mutability are observed in the input. Same is true

247

`` -

/// if compare panics.

251

`` +

/// If the comparison function compare does not implement a [total order], the function may

252

/// panic; even if the function exits normally, the resulting order of elements in the slice is

253

/// unspecified. See also the note on panicking below.

248

254

`///

249

255

`` /// For example |a, b| (a - b).cmp(a) is a comparison function that is neither transitive nor

250

256

`` /// reflexive nor total, a < b < c < a with a = 1, b = 2, c = 3. For more information and

`@@ -263,7 +269,14 @@ impl [T] {

263

269

`///

264

270

`/// # Panics

265

271

`///

266

`` -

/// May panic if compare does not implement a [total order].

272

`` +

/// May panic if compare does not implement a [total order], or if compare itself panics.

273

///

274

/// All safe functions on slices preserve the invariant that even if the function panics, all

275

/// original elements will remain in the slice and any possible modifications via interior

276

/// mutability are observed in the input. This ensures that recovery code (for instance inside

277

`` +

/// of a Drop or following a catch_unwind) will still have access to all the original

278

`` +

/// elements. For instance, if the slice belongs to a Vec, the Vec::drop method will be able

279

/// to dispose of all contained elements.

267

280

`///

268

281

`/// # Examples

269

282

`///

`@@ -295,10 +308,9 @@ impl [T] {

295

308

`/// This sort is stable (i.e., does not reorder equal elements) and O(m * n * log(n))

296

309

`/// worst-case, where the key function is O(m).

297

310

`///

298

`` -

/// If the implementation of [Ord] for K does not implement a [total order] the resulting

299

/// order of elements in the slice is unspecified. All original elements will remain in the

300

/// slice and any possible modifications via interior mutability are observed in the input. Same

301

`` -

/// is true if the implementation of [Ord] for K panics.

311

`` +

/// If the implementation of [Ord] for K does not implement a [total order], the function

312

/// may panic; even if the function exits normally, the resulting order of elements in the slice

313

/// is unspecified. See also the note on panicking below.

302

314

`///

303

315

`/// # Current implementation

304

316

`///

`@@ -313,7 +325,15 @@ impl [T] {

313

325

`///

314

326

`/// # Panics

315

327

`///

316

`` -

/// May panic if the implementation of [Ord] for K does not implement a [total order].

328

`` +

/// May panic if the implementation of [Ord] for K does not implement a [total order], or if

329

`` +

/// the [Ord] implementation or the key-function f panics.

330

///

331

/// All safe functions on slices preserve the invariant that even if the function panics, all

332

/// original elements will remain in the slice and any possible modifications via interior

333

/// mutability are observed in the input. This ensures that recovery code (for instance inside

334

`` +

/// of a Drop or following a catch_unwind) will still have access to all the original

335

`` +

/// elements. For instance, if the slice belongs to a Vec, the Vec::drop method will be able

336

/// to dispose of all contained elements.

317

337

`///

318

338

`/// # Examples

319

339

`///

`@@ -347,10 +367,9 @@ impl [T] {

347

367

`/// storage to remember the results of key evaluation. The order of calls to the key function is

348

368

`/// unspecified and may change in future versions of the standard library.

349

369

`///

350

`` -

/// If the implementation of [Ord] for K does not implement a [total order] the resulting

351

/// order of elements in the slice is unspecified. All original elements will remain in the

352

/// slice and any possible modifications via interior mutability are observed in the input. Same

353

`` -

/// is true if the implementation of [Ord] for K panics.

370

`` +

/// If the implementation of [Ord] for K does not implement a [total order], the function

371

/// may panic; even if the function exits normally, the resulting order of elements in the slice

372

/// is unspecified. See also the note on panicking below.

354

373

`///

355

374

`/// For simple key functions (e.g., functions that are property accesses or basic operations),

356

375

`` /// sort_by_key is likely to be faster.

`@@ -369,7 +388,15 @@ impl [T] {

369

388

`///

370

389

`/// # Panics

371

390

`///

372

`` -

/// May panic if the implementation of [Ord] for K does not implement a [total order].

391

`` +

/// May panic if the implementation of [Ord] for K does not implement a [total order], or if

392

`` +

/// the [Ord] implementation panics.

393

///

394

/// All safe functions on slices preserve the invariant that even if the function panics, all

395

/// original elements will remain in the slice and any possible modifications via interior

396

/// mutability are observed in the input. This ensures that recovery code (for instance inside

397

`` +

/// of a Drop or following a catch_unwind) will still have access to all the original

398

`` +

/// elements. For instance, if the slice belongs to a Vec, the Vec::drop method will be able

399

/// to dispose of all contained elements.

373

400

`///

374

401

`/// # Examples

375

402

`///