Add examples to Option::map_or documentation

[patrickoliveira15]

This PR enhances the documentation of the Option::map_or method by adding more comprehensive and practical examples. These updates aim to help developers better understand the method's behavior and usage in various scenarios, especially when dealing with Some and None cases.

Changes Made:

1. Added Examples for Clarity:

   • Demonstrated how map_or applies a function to a value when Some is present.
   • Showed how the default value is returned when None is encountered.

2. Introduced a Real-World Use Case:

   • Added an example illustrating how map_or can be used to handle fallback logic, such as generating personalized greeting messages.

3. Improved Readability:

   • Included comments to explain each example, ensuring developers understand the rationale behind each test case.

Updated Examples:

// Using a default value for an empty option.
let empty: Option<i32> = None;
assert_eq!(empty.map_or(0, |v| v * 2), 0); // Default value is used.

// Applying a function to a `Some` value.
let value = Some(21);
assert_eq!(value.map_or(0, |v| v * 2), 42); // Function is applied to `21`.

// Practical example with `Option<&str>`:
let username: Option<&str> = Some("Alice");
let greeting = username.map_or("Hello, guest!".to_string(), |name| format!("Hello, {}!", name));
assert_eq!(greeting, "Hello, Alice!");

let no_username: Option<&str> = None;
let fallback_greeting = no_username.map_or("Hello, guest!".to_string(), |name| format!("Hello, {}!", name));
assert_eq!(fallback_greeting, "Hello, guest!");

Benefits:

• Improved Usability: The examples provide clear, actionable guidance on how to use map_or effectively.
• Increased Accessibility: Developers at all levels can quickly grasp the method's functionality with the added real-world context.
• Aligned with Rust's Philosophy: Enhances documentation to prioritize clarity and developer experience.

If there are additional scenarios or edge cases worth including, I'm happy to expand this PR!

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Amanieu (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[cyrgani]

I do not believe that any of these cases add anything of value compared to the two existing examples above. They are just more verbose, but showcase no new features or behavior.
If there is a different rationale for this, please try to explain it without lots of vague LLM speech.
Also, the //s are missing for the comment lines in the doctest.

[rustbot]

There are merge commits (commits with multiple parents) in your changes. We have a no merge policy so these commits will need to be removed for this pull request to be merged.

You can start a rebase with the following commands:

$ # rebase
$ git pull --rebase https://github.com/rust-lang/rust.git master
$ git push --force-with-lease

The following commits are merge commits:

• 9a8606f

[rust-log-analyzer]

The job mingw-check-tidy failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
COPY host-x86_64/mingw-check/validate-error-codes.sh /scripts/

# NOTE: intentionally uses python2 for x.py so we can test it still works.
# validate-toolstate only runs in our CI, so it's ok for it to only support python3.
ENV SCRIPT TIDY_PRINT_DIFF=1 python2.7 ../x.py test \
           --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --allow-unsafe --generate-hashes reuse-requirements.in
---
#13 2.804 Building wheels for collected packages: reuse
#13 2.805   Building wheel for reuse (pyproject.toml): started
#13 3.011   Building wheel for reuse (pyproject.toml): finished with status 'done'
#13 3.012   Created wheel for reuse: filename=reuse-4.0.3-cp310-cp310-manylinux_2_35_x86_64.whl size=132719 sha256=be6760d5849de4a58bbe52b85ca57a55f2b32b518b17029a5ad2e530db0d4303
#13 3.012   Stored in directory: /tmp/pip-ephem-wheel-cache-4rcq2h3p/wheels/3d/8d/0a/e0fc6aba4494b28a967ab5eaf951c121d9c677958714e34532
#13 3.015 Installing collected packages: boolean-py, binaryornot, tomlkit, reuse, python-debian, markupsafe, license-expression, jinja2, chardet, attrs
#13 3.405 Successfully installed attrs-23.2.0 binaryornot-0.4.4 boolean-py-4.0 chardet-5.2.0 jinja2-3.1.4 license-expression-30.3.0 markupsafe-2.1.5 python-debian-0.1.49 reuse-4.0.3 tomlkit-0.13.0
#13 3.405 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#13 3.929 Collecting virtualenv
#13 3.929 Collecting virtualenv
#13 3.983   Downloading virtualenv-20.29.0-py3-none-any.whl (4.3 MB)
#13 4.229      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.3/4.3 MB 17.5 MB/s eta 0:00:00
#13 4.287 Collecting filelock<4,>=3.12.2
#13 4.299   Downloading filelock-3.16.1-py3-none-any.whl (16 kB)
#13 4.332 Collecting platformdirs<5,>=3.9.1
#13 4.342   Downloading platformdirs-4.3.6-py3-none-any.whl (18 kB)
#13 4.362 Collecting distlib<1,>=0.3.7
#13 4.386      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 469.0/469.0 KB 36.0 MB/s eta 0:00:00
#13 4.386      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 469.0/469.0 KB 36.0 MB/s eta 0:00:00
#13 4.466 Installing collected packages: distlib, platformdirs, filelock, virtualenv
#13 4.647 Successfully installed distlib-0.3.9 filelock-3.16.1 platformdirs-4.3.6 virtualenv-20.29.0
#13 DONE 4.8s

#14 [7/8] COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
#14 DONE 0.0s
---
DirectMap4k:      137152 kB
DirectMap2M:     7202816 kB
DirectMap1G:    11534336 kB
##[endgroup]
Executing TIDY_PRINT_DIFF=1 python2.7 ../x.py test            --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
+ TIDY_PRINT_DIFF=1 python2.7 ../x.py test --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
    Finished `dev` profile [unoptimized] target(s) in 0.05s
##[endgroup]
WARN: currently no CI rustc builds have rustc debug assertions enabled. Please either set `rust.debug-assertions` to `false` if you want to use download CI rustc or set `rust.download-rustc` to `false`.
downloading https://static.rust-lang.org/dist/2025-01-08/rustfmt-nightly-x86_64-unknown-linux-gnu.tar.xz