You are an expert Python developer. Write a clean, well-documented, efficient Python function for the following task: {task}. Include proper type hints, error handling, docstring, and example usage. Follow PEP8 standards and optimize for performance.