From 72d9f6d47c7d9f7d69c4a7e73130352da41f7a0b Mon Sep 17 00:00:00 2001
From: Siddhant <siddhantjssalunke@gmail.com>
Date: Fri, 31 Oct 2025 21:23:05 +0530
Subject: [PATCH] Added Digital Time Utility project (Clock, Alarm, Stopwatch)

---
 digital_clock_alarm_stopwatch/README.md       | 37 ++++++++
 .../clock_alarm_stopwatch.py                  | 89 +++++++++++++++++++
 2 files changed, 126 insertions(+)
 create mode 100644 digital_clock_alarm_stopwatch/README.md
 create mode 100644 digital_clock_alarm_stopwatch/clock_alarm_stopwatch.py

diff --git a/digital_clock_alarm_stopwatch/README.md b/digital_clock_alarm_stopwatch/README.md
new file mode 100644
index 0000000..f964aab
--- /dev/null
+++ b/digital_clock_alarm_stopwatch/README.md
@@ -0,0 +1,37 @@
+# Digital Clock, Alarm & Stopwatch ⏰
+
+### 📌 Overview
+This is a simple **terminal-based Python project** that combines:
+1. 🕒 **Clock** — Displays the current system time.
+2. ⏰ **Alarm** — Lets you set a custom alarm time.
+3. ⏳ **Stopwatch** — Counts elapsed time in HH:MM:SS format.
+
+All features are implemented in a single file under **100 lines**, following open-source contribution guidelines.
+
+---
+
+### ⚙️ Features
+- Works completely in the **terminal** (no GUI or external modules).
+- Cross-platform: runs on **Windows, macOS, and Linux**.
+- Clean menu with user-friendly navigation.
+- Uses **match-case** (Python 3.10+).
+
+---
+
+### ▶️ How to Run
+1. Open the terminal and navigate to the folder containing the file.
+2. Run the following command:
+   ```bash
+   python clock_alarm_stopwatch.py
+
+🧠 Code Logic Summary
+
+clear() → clears the console output for a fresh display.
+
+show_clock() → shows real-time system clock.
+
+set_alarm() → triggers a simple text-based alarm at the set time.
+
+stopwatch() → counts time until manually stopped.
+
+main() → provides a menu and controls program flow.
\ No newline at end of file
diff --git a/digital_clock_alarm_stopwatch/clock_alarm_stopwatch.py b/digital_clock_alarm_stopwatch/clock_alarm_stopwatch.py
new file mode 100644
index 0000000..5f46ef7
--- /dev/null
+++ b/digital_clock_alarm_stopwatch/clock_alarm_stopwatch.py
@@ -0,0 +1,89 @@
+import time, os  # Import required modules
+
+# Function to clear the console screen (works on Windows, Mac, Linux)
+def clear():
+    os.system('cls' if os.name == 'nt' else 'clear')
+
+# Function to display a live digital clock
+def show_clock():
+    while True:
+        clear()
+        t = time.strftime("%H:%M:%S")  # Get current time
+        print("========== CLOCK ==========")
+        print("Current Time:", t)
+        print("===========================")
+        b = input("Press 'b' to go back: ")  # Wait for user input
+        if b.lower() == 'b':  # Return to main menu
+            break
+
+# Function to set and run an alarm
+def set_alarm():
+    # Get alarm time from user
+    h = int(input("Hour (0-23): "))
+    m = int(input("Minute (0-59): "))
+    s = int(input("Second (0-59): "))
+    print(f"Alarm set for {h:02d}:{m:02d}:{s:02d}")
+    
+    # Continuously check time until alarm time matches
+    while True:
+        t = time.localtime()
+        if (t.tm_hour, t.tm_min, t.tm_sec) == (h, m, s):
+            print("\n⏰ ALARM! WAKE UP! ⏰")
+            for _ in range(3):  # Beep message 3 times
+                print("BEEP! BEEP! BEEP!")
+                time.sleep(1)
+            break
+        # Option to cancel alarm manually
+        if input("Press 'b' + Enter to cancel or Enter to wait: ") == 'b': 
+            print("Alarm cancelled.")
+            break
+        time.sleep(1)
+    input("Press Enter to return...")
+
+# Function to start a stopwatch
+def stopwatch():
+    sec = 0
+    start = input("Press Enter to start or 'b' to go back: ")
+    if start.lower() == 'b': 
+        return
+    while True:
+        clear()
+        # Display elapsed time in HH:MM:SS format
+        print("====== STOPWATCH ======")
+        print(f"Time: {sec//3600:02d}:{(sec//60)%60:02d}:{sec%60:02d}")
+        print("=======================")
+        print("Press 'b' + Enter to stop.")
+        time.sleep(1)
+        sec += 1
+        # Check for stop key depending on OS
+        if os.name == 'nt':
+            import msvcrt
+            if msvcrt.kbhit() and msvcrt.getch().decode().lower() == 'b':
+                break
+        else:
+            if input() == 'b':
+                break
+    input("Stopped. Press Enter to return...")
+
+# Main menu function
+def main():
+    while True:
+        clear()
+        print("==== DIGITAL TIME UTILITY ====")
+        print("1. Clock\n2. Alarm\n3. Stopwatch\n4. Exit")
+        choice = input("Enter your choice: ")
+        # Match-case statement for menu selection
+        match choice:
+            case '1': show_clock()
+            case '2': set_alarm()
+            case '3': stopwatch()
+            case '4':
+                print("Goodbye!")
+                break
+            case _:
+                print("Invalid choice, please try again.")
+                time.sleep(1)
+
+# Program execution starts here
+if __name__ == "__main__":
+    main()