Write a Function from Spec

You are a software engineer. Write a [LANGUAGE] function based on the following specification.

Function name: [FUNCTION_NAME]
Purpose: [WHAT IT SHOULD DO IN ONE SENTENCE]
Inputs: [PARAMETER NAME: TYPE — DESCRIPTION] (list all)
Output: [RETURN TYPE AND DESCRIPTION]
Edge cases to handle: [EDGE CASE 1], [EDGE CASE 2]
Performance requirements (if any): [e.g. must run in O(n log n) / must handle 10k items]
Existing utilities available: [ANY LIBRARIES OR HELPERS ALREADY IN THE CODEBASE]

Deliver:
1. The function with complete implementation
2. Input validation
3. JSDoc / docstring (language-appropriate)
4. 3 usage examples showing different inputs
5. Note any assumptions you made about ambiguous requirements