README
¶
Date
Overview
The Date component provides utilities for working with dates and times in a standardized format. It simplifies common date operations like parsing, formatting, and handling optional (nullable) dates.
Features
- Standardized Date Format: Uses RFC3339 as the standard date format throughout the application
- Date Parsing: Parse date strings into time.Time objects with proper error handling
- Date Formatting: Format time.Time objects as strings in the standard format
- Optional Date Support: Handle nullable dates with pointer-based functions
- Validation Error Integration: Return structured validation errors for invalid date formats
Installation
go get github.com/abitofhelp/servicelib/date
Quick Start
See the Basic Usage example for a complete, runnable example of how to use the date component.
API Documentation
Core Constants
StandardDateFormat
The standard date format used throughout the application.
const StandardDateFormat = time.RFC3339
Key Methods
ParseDate
Parses a date string in the standard format.
func ParseDate(dateStr string) (time.Time, error)
ParseOptionalDate
Parses an optional date string in the standard format.
func ParseOptionalDate(dateStr *string) (*time.Time, error)
FormatDate
Formats a time.Time as a string in the standard format.
func FormatDate(date time.Time) string
FormatOptionalDate
Formats an optional time.Time as a string in the standard format.
func FormatOptionalDate(date *time.Time) *string
Examples
For complete, runnable examples, see the following directories in the EXAMPLES directory:
- Basic Usage - Shows basic usage of the date component
- Error Handling - Shows how to handle date parsing errors
- Time Zones - Shows how to work with time zones
- Optional Dates - Shows how to work with optional (nullable) dates
Best Practices
- Use Standard Format: Always use the StandardDateFormat constant for consistency
- Handle Parsing Errors: Always check for errors when parsing date strings
- Use Optional Functions: Use ParseOptionalDate and FormatOptionalDate for nullable dates
- Time Zone Awareness: Be aware of time zones when parsing and formatting dates
- Validate User Input: Always validate user-provided date strings before parsing
Troubleshooting
Common Issues
Invalid Date Format
If you're seeing "invalid date format" errors, ensure the date string follows the RFC3339 format (e.g., "2023-01-02T15:04:05Z"). Common issues include:
- Missing time component
- Missing timezone indicator
- Incorrect separators between date parts
Time Zone Confusion
If dates are being parsed correctly but show unexpected times, check the time zone:
- RFC3339 dates with "Z" suffix are in UTC
- Dates with explicit offsets (e.g., "+01:00") are in that specific time zone
- Consider converting to a specific time zone if needed for display or comparison
Related Components
- Validation - Validation utilities that work with date validation
- Errors - Error handling for date parsing errors
Contributing
Contributions to this component are welcome! Please see the Contributing Guide for more information.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Overview ¶
Package date provides utilities for working with dates and times.
Package date provides utilities for working with dates and times in a consistent manner.
This package standardizes date and time handling across the application by providing a set of functions for parsing, formatting, and manipulating dates. It uses a standard date format (RFC3339) to ensure consistency in date representations.
The package addresses common challenges in date handling:
- Consistent date formatting across the application
- Handling of optional (nullable) dates
- Proper error handling for date parsing failures
Key components:
- StandardDateFormat: The standard date format constant (RFC3339)
- Parse functions: For converting strings to time.Time values
- Format functions: For converting time.Time values to strings
- Support for both required and optional (pointer-based) dates
Example usage:
// Parsing a date string
dateStr := "2023-04-15T14:30:00Z"
parsedDate, err := date.ParseDate(dateStr)
if err != nil {
log.Fatalf("Failed to parse date: %v", err)
}
// Working with the parsed date
if parsedDate.After(time.Now()) {
fmt.Println("The date is in the future")
}
// Formatting a date
formattedDate := date.FormatDate(parsedDate)
fmt.Println("Formatted date:", formattedDate)
// Working with optional dates
var optionalDateStr *string
// optionalDateStr is nil
optionalDate, _ := date.ParseOptionalDate(optionalDateStr)
// optionalDate will be nil
// Setting a value
dateValue := "2023-05-20T10:15:00Z"
optionalDateStr = &dateValue
optionalDate, _ = date.ParseOptionalDate(optionalDateStr)
// optionalDate will contain the parsed date
// Formatting an optional date
formattedOptional := date.FormatOptionalDate(optionalDate)
// formattedOptional will be a pointer to the formatted string
Index ¶
Constants ¶
const ( // StandardDateFormat is the standard date format used throughout the application. // This format follows the RFC3339 standard (2006-01-02T15:04:05Z07:00), // which is both human-readable and machine-parsable, and includes // date, time, and timezone information. StandardDateFormat = time.RFC3339 )
Variables ¶
This section is empty.
Functions ¶
func FormatDate ¶
FormatDate formats a time.Time as a string in the standard format (RFC3339). It converts a time.Time object into a standardized string representation that can be used for display, storage, or transmission.
This function ensures consistent date formatting throughout the application.
Parameters:
- date: The time.Time value to format
Returns:
- string: The formatted date string (e.g., "2023-04-15T14:30:00Z")
func FormatOptionalDate ¶
FormatOptionalDate formats an optional time.Time as a string in the standard format (RFC3339). This function is designed to handle nullable time values (represented as pointers). If the input pointer is nil, the function returns nil without attempting to format. Otherwise, it behaves similarly to FormatDate, converting the time.Time to a string.
This is particularly useful when working with optional date fields in APIs or databases.
Parameters:
- date: Pointer to the time.Time value to format, can be nil
Returns:
- *string: Pointer to the formatted date string (e.g., "2023-04-15T14:30:00Z") if input is not nil, nil if input is nil
func ParseDate ¶
ParseDate parses a date string in the standard format (RFC3339). It converts a string representation of a date and time into a time.Time object. If the string cannot be parsed according to the StandardDateFormat, it returns a validation error with details about the failure.
Parameters:
- dateStr: The date string to parse (e.g., "2023-04-15T14:30:00Z")
Returns:
- time.Time: The parsed time if successful
- error: A validation error if parsing fails, nil otherwise
func ParseOptionalDate ¶
ParseOptionalDate parses an optional date string in the standard format (RFC3339). This function is designed to handle nullable date strings (represented as pointers). If the input pointer is nil, the function returns nil without attempting to parse. Otherwise, it behaves similarly to ParseDate, converting the string to a time.Time.
This is particularly useful when working with optional date fields in APIs or databases.
Parameters:
- dateStr: Pointer to the date string to parse (e.g., "2023-04-15T14:30:00Z"), can be nil
Returns:
- *time.Time: Pointer to the parsed time if successful, nil if input is nil
- error: A validation error if parsing fails, nil otherwise
Types ¶
This section is empty.
Source Files