feat(algorithms, intervals): most booked meeting rooms

[BrianLusina]

Describe your change:

Uses two min heaps to find the most booked meeting rooms

• Add an algorithm?
• Fix a bug or typo in an existing algorithm?
• Documentation change?

Checklist:

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized.
• I know that pull requests will not be merged if they fail the automated tests.
• This PR only changes one algorithm file. To ease review, please open separate PRs for separate algorithms.
• All new Python files are placed inside an existing directory.
• All filenames are in all lowercase characters with no spaces or dashes.
• All functions and variable names follow Python naming conventions.
• All function parameters and return values are annotated with Python type hints.
• All functions have doctests that pass the automated testing.
• All new algorithms have a URL in its comments that points to Wikipedia or other similar explanation.
• If this pull request resolves one or more open issues then the commit message contains Fixes: #{$ISSUE_NO}.

Summary by CodeRabbit

• New Features

  • Added a meeting-room booking optimizer to identify the most frequently reserved room
  • Added circular linked list utilities and new math/string utilities (Sum of Multiples, Integer to English)

• Documentation

  • Added a comprehensive "Meeting Rooms III" guide and updated hierarchical docs to reflect new sections and reorganized entries

• Tests

  • Added unit tests for the meeting-room logic and circular linked list utilities

• Chores

  • Removed an obsolete pymath test entry (reorganized)

[coderabbitai]

Warning

Rate limit exceeded

@BrianLusina has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 17 minutes and 44 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Adds a new Meeting Rooms III solution: a heap-based most_booked() implementation, unit tests, expanded README with problem statement and solution, and DIRECTORY.md updates to register the new entries.

Changes

Cohort / File(s)	Summary
Meeting Rooms III Implementation algorithms/intervals/meeting_rooms/__init__.py	Added most_booked(meetings: List[List[int]], rooms: int) -> int implementing room assignment with two min-heaps (available and in-use) and per-room counters; added/adjusted typing imports.
Meeting Rooms III Tests algorithms/intervals/meeting_rooms/test_most_booked_meeting_rooms.py	New unittest module with parameterized test cases for most_booked().
Meeting Rooms Documentation algorithms/intervals/meeting_rooms/README.md	Inserted comprehensive "Meeting Rooms III" section: problem statement, constraints, examples, hints, two-heap solution walkthrough, complexity analysis, and illustrations.
Directory Index Updates DIRECTORY.md	Added and reorganized entries to include new Meeting Rooms III docs, tests, and related entries across categories.

Sequence Diagram

sequenceDiagram
    participant Client
    participant MostBooked as most_booked()
    participant Available as AvailableRoomsHeap
    participant InUse as InUseRoomsHeap
    participant Counter as BookingCounter

    Client->>MostBooked: call(meetings, rooms)
    MostBooked->>Available: init room ids
    MostBooked->>Counter: init counters

    loop for each meeting (by start time)
        MostBooked->>InUse: pop rooms with end_time <= meeting.start
        InUse->>Available: push freed rooms
        MostBooked->>Available: if empty? check earliest in InUse
        alt room available
            MostBooked->>Available: pop room_id
        else all occupied
            MostBooked->>InUse: pop earliest finishing (end, room_id)
            InUse->>MostBooked: earliest_end
            MostBooked->>Available: use freed room_id (delayed end = earliest_end + duration)
        end
        MostBooked->>Counter: increment(room_id)
        MostBooked->>InUse: push (meeting_end, room_id)
    end

    MostBooked->>Counter: determine max_booked_room
    MostBooked->>Client: return(room_id)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(algorithms, intervals): most booked meeting rooms #171: Adds the same most_booked(meetings, rooms) implementation and accompanying README/tests for Meeting Rooms III.

Suggested labels

Sorting

Poem

🐰 I hop through heaps both near and far,
Assigning rooms beneath each star,
Counters ticking, meetings land,
Most-booked room held in my hand—
A rabbit's cheer for code well-planned!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a most booked meeting rooms algorithm to the intervals category.
Description check	✅ Passed	The description follows the required template with brief change summary and completed checklist items. However, one optional checklist item about issue references is unchecked.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/algorithms-intervals

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Fix all issues with AI agents

In `@algorithms/intervals/meeting_rooms/__init__.py`:
- Line 112: Fix the typographical error in the inline comment inside
algorithms/intervals/meeting_rooms/__init__.py: change "numer" to "number" in
the comment that reads "Once all meetings are processed, return the room with
the highest numer of meetings from the counter array" (so the comment correctly
reads "highest number of meetings"); this is a documentation-only change and
does not affect any function logic such as the room-counting implementation.
- Line 89: Typo in the comment inside
algorithms/intervals/meeting_rooms/__init__.py: change "fre" to "free" in the
explanatory comment that begins "If a room is free, assign it to the current
meeting..." so the sentence reads correctly; update the comment near the meeting
room assignment logic (the comment adjacent to the code handling room
allocation/delay) to fix the spelling.
- Around line 77-78: Fix the typo and simplify the list creation: replace the
comprehension that defines available (currently "available = [i for i in
range(rooms)]") with "available = list(range(rooms))" and update the inline
comment that reads "# Min hip for rooms currently in use" to "# Min heap for
rooms currently in use" so the variable name 'available' and the min-heap
comment are correct and clear.

In `@algorithms/intervals/meeting_rooms/README.md`:
- Around line 147-150: The README image list has a duplicate: both "Example 2"
and "Example 3" reference meeting_rooms_3_example_3.png; update the second entry
so "Example 2" points to meeting_rooms_3_example_2.png instead of
meeting_rooms_3_example_3.png (edit the image reference string in the block that
contains the four ![Example X](...) lines).

🧹 Nitpick comments (1)

algorithms/intervals/meeting_rooms/__init__.py (1)

73-113: Missing docstring — inconsistent with other functions in the file.

find_minimum_meeting_rooms and find_minimum_meeting_rooms_priority_queue both have docstrings documenting complexity, parameters, and return values. most_booked should follow the same pattern for consistency.