ms_learn_csharp/026_Challenge_variabe_data/026_csharp.md

# Challenge project

## Work with variable data in C#

Demonstrate your ability to develop a console app that implements data
formatting and using arrays to deliver a multiple term search feature.

### Learning objectives

Apply iteration statements using data input.

- Process data.

- Format data output.

- Choose the correct data types and safely converting data types.

- Create and manipulate string arrays, and sort array data.

- Modify and build complex strings from multiple data sources, and format data
for display.

## Introduction

Suppose you're one of the developers working on the Contoso Pets adoption
application to help find new homes for pets. Your starting version of the
application gathers a single search term used to search the descriptions of
dogs. A single term search is helpful, but the feedback given from the team is
the application needs more search functionality. The team wants you to extend
the search functionality to allow for multiple term searches. Additionally, the
team wants to pilot an update to the "search status" animation that shows
search progress.

In this challenge coding project, your C# data knowledge and skills are applied
for:

- Creating string arrays by splitting strings
- Manipulating array data, iterating through elements in an array, and sorting array data
- Modifying and building strings from multiple data sources

In short, you'll:

- Develop multi-term search functionality for the "dogs" search
- Update the "search status" animation, information and countdown

By the end of this module, you complete an updated version of the Contoso Pets
application that searches all dogs available for adoption using multiple search
terms and an improved search status simulation.

---

### Project specification overview

Update the existing Contoso Pets starter application to include multiple term
search and improved "search status" animation features:

#### Add dog attribute multi-term search

Gather user input for the pet characteristic multiple term search

- Users need to provide search terms separated by commas
- Store the search terms in an array and sort the terms alphabetically

Within the animals array loop that identifies "dogs":

- Iterate through the search terms to search each dog's description
- Search the combined description for a term match
- Output each dog's description where there's one or more terms matched

After exiting the "search Animals" array loop that identifies dogs:

If no dogs were a match for any of the users provided search terms, output a no
dogs matched message.

#### Add "search status" improvements

Update the animation

- Adjust the searchingIcons array to resemble a spinning dial
- Adjust the animation loop so the animation shows a numeric countdown from two to zero (2.., 1.., 0..)

#### Starter code

The starter code project for this challenge project module includes a Program
.cs file that provides the following code features:

The code declares variables used to collect and process pet data and menu item
selections

The code declares the ourAnimals array

The code uses a for loop around an if-elseif-else construct to populate the
ourAnimals array with a sample dataset

The code displays the following main menu options for user selection:

  ```txt
  1. List all of our current pet information
  2. Display all dogs with a specified characteristic

  Enter menu item selection or type "Exit" to exit the program
  ```

The application menu code reads the user's menu item selection and displays a
message echoing their selection

Case 1: "List all of our current pet information" displays the sample data for
all animals (two dogs and two cats)

Case 2: "2. Display all dogs with a specified characteristic" is the primary
area where new functionality code is added

  - Under Case 2, the starter code identifies dogs and searches for a single
  user input term
  - Before you search each dog, the console shows a simple "animation" that
  simulates a status for searching occurring

Your goal is to update the existing code to develop key features requested by
your team:

- Add dog multiple attribute search
- Update search animation

Use your development environment, and test your application at each stage of
your development process.

#### Setup

Download a
[zip](https://github.com/MicrosoftLearning/Challenge-project-Work-with-variable-data-in-CSharp/archive/refs/heads/main.zip)
file containing the code folders for the challenge project.

Build and run the file entering `dotnet run` in the terminal window.

The menu should display with two options. Enter `1` as shown in the following
terminal example:

  ```txt
  Welcome to the Contoso PetFriends app. Your main menu options are:
    1. List all of our current pet information
    2. Display all dogs with a specified characteristic
  
  Enter your selection number (or type Exit to exit the program)
  1
  ```

The sample data on the current pets should display followed by the message
`Press the Enter key to continue`

After pressing Enter, the menu should display again. Choose Option `2`, shown
in the following example:

  ```txt
  Welcome to the Contoso PetFriends app. Your main menu options are:
   1. List all of our current pet information
   2. Display all dogs with a specified characteristic
  
  Enter your selection number (or type Exit to exit the program)
  2
  
  Enter one desired dog characteristic to search for
  ```

Enter "large" for the search term and press "Enter."

Notice the "searching" message as shown:

```txt
searching our dog Nickname: gus for large ...     
```

Notice, the message runs before each search of a pet, and the periods
(`., .., ...`) at the end change in an animation. Run the search again if you
missed it.

Once the search ends, press enter to return to the menu. Then type "exit" and
press "Enter" to close the application.

Take a few minutes to become familiar with the Project.cs started code.

Focus on the areas that require updates, search and the animation.

Notice that there are some comments left in the code that indicate where to
place an update.

You're now ready to begin the Guided project exercises. Good luck!

---

### Add multiple term search support

The Contoso Pets app helps find new homes for abandoned pets. The team wants
the search feature improved to let users enter multiple terms when searching
for dogs to adopt.

### Search specification

In this first challenge exercise, you need to update the single term search
feature to allow users to enter multiple search terms separated by commas.

#### Gather multiple search terms from the user

- Allow the user to enter multiple search terms when searching for dogs
- The user needs instructions to "enter the search terms separated by commas"
- Separate out individual search terms from the user entry string and store as
values in an array
- Sort the terms in the array in alphanumeric sort order

#### Identify dogs with descriptions with matches for one, or more, user search term

- As you identify a dog in the `animalsArray`, search for matches for each term
the user has entered
- For a term match, output a message with the dogs name and the term that is
matched
  - example: `Our dog Jake is a match for your search for sheppard!`
- When all term searches complete for the current dog description:
  - For one or more matches, output the nickname and description for the
  current dog
  - For one or more matches, track that there has been a match so you know not
  to display an "no matches found for any available dogs" message (refer to the
  next item)
- After **all** dog searches complete with no matches, display a message "No
matches found for any available dogs"

#### Enforce the following validation rules

- values can't be null
- values can't have zero characters
- any further restriction is up to the developer

#### Code comments

- Numbered code comments in the starter code offer suggestions
- The comments are in a sequential order and only the comments starting with #1, #2, and #3 apply to this exercise of the challenge

#### Sample output

Review the following animated image

Notice the temporary display of "`searching...`" followed by the current term 
(example: "`searching...retriever`")

Notice the order the terms appear in search is now in alphanumeric

Notice the messages for matches persist (example:
"`Our dog lola is a chase match!`")

Review the sample output in the following section, "How to check your work", to further clarify how to implement features

### How to check your work

To validate that your code satisfies the specified requirements.

Build and run your app.

> Note  
> You can exit the verification test before completing all of the verification
steps if see a result that does not satisfy the specification requirements. To
force an exit from the running program, in the Terminal panel, press Ctrl-C.
After exiting the running app, complete the edits that you believe will address
the issue you are working on, save your updates to the Program.cs file, and
then re-build and run your code.

The terminal command prompt should display as the starting point for the
program

At the command prompt, enter 2 menu:

  ```txt
  Welcome to the Contoso PetFriends app. Your main menu options are:
   1. List all of our current pet information
   2. Display all dogs with a specified characteristic
  
  Enter your selection number (or type Exit to exit the program)
  2
  
  Enter dog characteristics to search for separated by commas
  ```

At the command prompt, enter large, cream, golden to test when more than one
search term matches the dog descriptions. Verify that the Terminal panel
updates with a message similar to the code output sample:

  ```txt
  Enter dog characteristics to search for separated by commas
  large, cream, golden
  
  Our dog Nickname: lola matches your search for cream
  Our dog Nickname: lola matches your search for golden
  Nickname: lola (ID #: d1)
  Physical description: medium sized cream colored female golden retriever weighing about 45 pounds. housebroken.
  Personality: loves to have her belly rubbed and likes to chase her tail. gives lots of kisses.
  
  Our dog Nickname: gus matches your search for golden
  Our dog Nickname: gus matches your search for large
  Nickname: gus (ID #: d2)
  Physical description: large reddish-brown male golden retriever weighing about 85 pounds. housebroken.
  Personality: loves to have his ears rubbed when he greets you at the door, or at any time! loves to lean-in and give doggy hugs.
  
  Press the Enter key to continue
  ```

At the command prompt, press the enter key to continue to the main menu

At the command prompt, enter 2 menu:

  ```txt
  Welcome to the Contoso PetFriends app. Your main menu options are:
   1. List all of our current pet information
   2. Display all dogs with a specified characteristic
  
  Enter your selection number (or type Exit to exit the program)
  2
  
  Enter dog characteristics to search for separated by commas
  ```

At the command prompt, enter big, grey, stripes to test when none of the search
terms match dog descriptions. Verify that the Terminal panel updates with a
message similar to the code output samples:

  ```txt
  Enter dog characteristics to search for separated by commas
  big, grey, stripes
  
  None of our dogs are a match for: big, grey, stripes
  
  
  Press the Enter key to continue
  ```

If you specified further restrictions for valid entries, run the appropriate
test cases to verify your work.

> Note  
> If your code meets the requirements you should be able to complete each step
in order and see the expected results in a single test pass. If you added
additional restrictions, you may need to exit the application and then run a
separate test pass to complete your verification.

Congratulations if you succeeded in this challenge exercise!

---

## Exercise

### Add improved search animation

The Contoso Pets app helps find new homes for abandoned pets. Part of the
request for search feature improvement is to update the animated simulation
indicating search progress.

#### Search animation specification

In this second challenge exercise, you need to update the search animation to
resemble spinning and add a count down (2, 1, 0).

#### Change the current "searching" animation icons

Update the current animation "icons"
`string[] searchingIcons = {". ", ".. ", "..."};`

Use new icons that simulate spinning

You can design the "searching" animation to display "spinning" to work
differently than displayed in the animated image

The "searching..." animation, should continue to be overwritten, after each
animation completes so it stays on the same line, and so that it doesn't
display after the animation stops.

#### Add a countdown to the "searching" animation

Review the previous animated image - note the countdown in the output
"`searching...retriever / 2`"
The previous number "`2`" displays as "`1`", and finally as "`0`", counting down
Update the loop that contains the "searching" animation so that the loop can
display a countdown

##### Code comments

- Numbered code comments in the starter code offer suggestions
- The comments are in a sequential order and only the comments starting with #4, and #5 apply to this exercise of the challenge

#### How to check your work

To validate that your code satisfies the specified requirements, complete the
instruction steps:

Build and run your app.

> Note  
> You can exit the verification test before completing all of the verification
steps if see a result that does not satisfy the specification requirements. To
force an exit from the running program, in the Terminal panel, press Ctrl-C.
After exiting the running app, complete the edits that you believe will address
the issue you are working on, save your updates to the Program.cs file, and
then re-build and run your code.

The terminal command prompt should display as the starting point for the
program

At the command prompt, enter 2 menu:

  ```txt
  Welcome to the Contoso PetFriends app. Your main menu options are:
   1. List all of our current pet information
   2. Display all dogs with a specified characteristic
  
  Enter your selection number (or type Exit to exit the program)
  2
  
  Enter dog characteristics to search for separated by commas
  ```

At the command prompt, enter **golden, big** and press enter to test the search
status messages with animation and countdown

Verify that the console panel updates with temporary "searching" status
messages similar to the code output samples:

  ```txt
  Enter dog characteristics to search for separated by commas
  golden, big

  searching our dog Nickname: lola for big / 2
  ```

  ```txt
  searching our dog Nickname: lola for big -- 1
  ```

  ```txt
  searching our dog Nickname: lola for golden \ 1
  ```

  ```txt
  searching our dog Nickname: lola for golden * 0
  ```

All the user entered search terms should display with the "`searching`" spin
animation and countdown for each dog where the "searching our dog..." line in
the output overwrites the previous line to create an animation

Refer to the previous animated image of the running program for more examples
of the "searching" status animation with countdown

Validate after the searching has stopped, the "`searching`" animation and
countdown no longer displays

> Note  
> If your code meets the requirements you should be able to complete each step
in order and see the expected results in a single test pass.

Congratulations if you succeeded in this exercise challenge!

- [Challenge](./Challenge-Variable_data/Own/Program.cs)

---

### Summary

Your challenge was to update an application to support multiple term search and
to improve the "search status" information animation.

In this module, you developed code that combines:

- Iterate using data input.
- Process data.
- Format data output.
- Choose the correct data types and safely convert data types.
- Create and manipulate string arrays, and sort array data.
- Modify and build complex strings from multiple data sources, and format data
for display.

You delivered functionality to your Contoso pet app team, including:

- Gather the pet characteristics for multiple search term inputs.
- Store search input terms in a sorted array.
- Display the dogs that have a term match.
- Provide an improved search status animation with a countdown.