DOCSEARCHbyAlgolia
Submit Docs

Carbon

repository·master·Indexed 26 days ago

https://github.com/dromara/carbon

A lightweight, semantic, and dependency-free Go package for date and time manipulation. Carbon provides an intuitive API for parsing, creating, and formatting time, including relative time formatting via DiffForHumans(), localization support, and time mocking for testing. It includes extensive calendar support for converting between Gregorian and Lunar, Julian, Persian, and Hebrew calendars, as well as boundary calculations for centuries, decades, years, quarters, months, weeks, days, hours, minutes, and seconds.

Tokens
19.4K
Snippets
25
Records
161
Agent score
88%

What's inside carbon

  1. Use the Hebrew Calendar module for date conversion and validation

    master

    The calendar/hebrew package provides tools for working with the Hebrew calendar. Key capabilities include:

    • Date Creation & Validation: Create and validate Hebrew calendar dates, including support for the 13th month (Adar Bet) in leap years.
    • Gregorian Conversion: Perform bidirectional conversion between Hebrew and Gregorian dates.
    • Timezone Support: Convert dates while accounting for different timezones.
    • JDN Conversion: Use Julian Day Numbers (JDN) as an intermediate standard for precise date calculations.
    • Leap Year Logic: Automatically handles leap year determination based on the 19-year Metonic cycle.

  2. Performance Overview of Carbon Library

    master

    Carbon is designed for high performance with a focus on execution efficiency, memory efficiency, and concurrency safety. Key performance characteristics include:

    • Zero Allocation Design: Approximately 65% of modules implement zero allocation patterns.
    • Core Task Speed: Most core operations execute in < 100ns.
    • Concurrency Safety: Systematically addresses race conditions and nil pointer dereferences.
    • Optimization Highlights:
      • SetLocale: Intelligent early return mechanism provides 60-90x speedup when setting the same locale repeatedly.
      • parseDuration: Optimized via sync.Map and caching, achieving 130-160x performance gains and 35-38x concurrency gains with zero allocations.
      • format2layout: Optimized via sync.Map, providing 23x concurrency performance improvement and zero allocations.
      • ParseByFormats: Algorithm optimization provides a 7.5% performance increase.

  3. Use the Persian Calendar package for date conversions and validation

    master

    The calendar/persian package provides tools for working with the Persian calendar. Key capabilities include:

    • Bidirectional Conversion: Convert between Persian calendar dates and Gregorian (standard) calendar dates.
    • Date Creation & Validation: Create Persian dates and verify their validity (supporting years 1-9999).
    • Leap Year Handling: Automatic calculation and verification of Persian leap years using JDN (Julian Day Number) difference logic.
    • Timezone Support: Perform conversions while respecting different timezones.
    • Formatting: Generate date strings in YYYY-MM-DD format and retrieve month/weekday names in English or Persian.

  4. Use the Lunar module for date conversion and validation

    master

    The Lunar module in Carbon provides full support for Chinese Lunar calendar operations within the 1900-2100 year range. Key capabilities include:

    • Bi-directional Conversion: Convert between Gregorian (standard) dates and Lunar dates.
    • Leap Month Handling: Full calculation and verification of leap months (e.g., "闰二月").
    • Validation: Verify the validity of years (1900-2100), months (1-12 plus leap months), and specific days within a month.
    • Timezone Support: Supports date conversion across different timezones.

  6. Use the `calendar/julian` package for Julian calendar calculations

    master
    The calendar/julian package provides tools for Julian Day (JD) and Modified Julian Day (MJD) calculations, bidirectional conversion between Julian and Gregorian calendars, and timezone-aware date conversions. It correctly handles the Gregorian reform boundary (October 15, 1582).

  7. Use the `calendar/julian` package for Julian Calendar operations

    master
    The calendar/julian package provides tools for Julian Calendar calculations, including Julian Day (JD) and Modified Julian Day (MJD) computations, and bidirectional conversion between the Julian and Gregorian calendars. It supports time zone conversions and configurable decimal precision.

  8. Analyze Carbon lock optimization and concurrency safety

    master

    Carbon employs several lock optimization strategies to ensure high performance in concurrent environments and prevent race conditions or null pointer dereferences:

    • Minimize lock holding time: Heavy operations like file I/O, JSON parsing, and map copying are executed outside of locks.
    • Read-write separation: Read operations utilize read locks, while write operations use write locks.
    • Early return optimization: Methods like SetLocale check if the requested locale is already active before acquiring write locks, significantly reducing overhead for repeated calls.
    • Deadlock prevention: The library avoids calling write operations while holding read locks.
    • Atomic operations: Uses defer to ensure proper lock release and maintains concurrency safety.

  9. Performance Overview of Carbon

    master

    Carbon is designed for high performance with a focus on execution efficiency, memory efficiency, and concurrency safety. Key performance characteristics include:

    • Execution Efficiency: Core operations typically perform in < 100ns.
    • Memory Efficiency: Approximately 65% of modules achieve zero-allocation design.
    • Concurrency: High stability under high concurrency with optimized lock strategies and fixes for race conditions and null pointer references.
    • Feature Richness: Supports multiple calendars and formats with good extensibility for custom formats and types.

  10. Use the Hebrew Calendar package for date conversions and formatting

    master

    The calendar/hebrew package provides tools for working with the Hebrew calendar. Key capabilities include:

    • Bidirectional Conversion: Convert between Hebrew calendar dates and Gregorian calendar dates.
    • Leap Month Support: Full handling of the Adar Bet (13th month) mechanism.
    • Timezone Support: Date conversions that respect different timezones.
    • Multi-language Formatting: Support for English and Hebrew locales for month and weekday names.
    • Validation: Verification of Hebrew years, months (1-13), and specific days within a month.
    • JDN Conversion: Precise conversion using Julian Day Number (JDN) as an intermediate standard.

  11. Understand Carbon performance characteristics

    master

    Carbon is designed for high performance, with a significant portion of its core modules achieving 'Zero Allocation' status.

    Performance Tiers

    • ⭐⭐⭐⭐⭐ (Excellent): Modules like carbon.go, comparer.go, creator.go, and difference.go typically exhibit < 100ns execution time and 0 B/op memory allocation.
    • ⭐⭐⭐⭐ (Good): Modules like parser.go and calendar.go involve more complex operations (string parsing, calendar conversions) and may have higher allocation rates (e.g., parser.go ranges from 459-4904 B/op).
    • ⭐⭐⭐ (Fair): Modules like constellation.go involve complex calculations and may take 200-500ns.