README
¶
RFC3339
A library that provides simplicity around parsing RFC3339 date-time
and full-date representations. The standard time.Time library is a bit
rough in that formats must be known ahead of time, and supplied when serializing
to strings. The types provided by this library extend the standard time.Time
type.
The date-time and full-date types implement the Scanner and
Valuer interfaces so that they can be stored as strings in a
database.
Install
$ go get github.com/jsumners/go-rfc3339
Example
package main
import (
"fmt"
"github.com/jsumners/go-rfc3339"
)
func main() {
dt, err := rfc3339.NewDateTimeFromString("2023-04-04T12:45:00-04:00")
if err != nil {
panic(err)
}
fmt.Printf("timestamp: %s", dt.ToString())
// Output:
// timestamp: 2023-04-04T12:45:00-04:00
}
Example (sql)
package main
import (
"database/sql"
"fmt"
"github.com/jsumners/go-rfc3339"
_ "modernc.org/sqlite"
)
func main() {
db, _ := sql.Open("sqlite", "./db.sqlite")
defer db.Close()
dt, _ := rfc3339.NewDateTimeFromString("2023-09-28T08:30:00-04:00")
db.Exec(
"insert into example (date_time) values (@date_time)",
sql.Named("date_time", dt),
)
rows, _ := db.Query("select date_time from values")
for rows.Next() {
var dt rfc3339.DateTime
rows.Scan(&dt)
fmt.Printf("dt = %+v\n", dt)
}
}
Documentation
¶
Overview ¶
Example (Datetime) ¶
This example shows how a rfc3339.DateTime can be used when deserializing JSON data.
package main
import (
"encoding/json"
"fmt"
"github.com/jsumners/go-rfc3339"
)
type MyJson struct {
Created rfc3339.DateTime `json:"created"`
}
// This example shows how a [rfc3339.DateTime] can be used when
// deserializing JSON data.
func main() {
input := `{"created":"2023-04-04T12:30:00-04:00"}`
var myJson MyJson
json.Unmarshal([]byte(input), &myJson)
fmt.Printf("%v\n", myJson)
}
Output: {2023-04-04 12:30:00 -0400 UTC-04:00}
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsDateTimeString ¶
IsDateTimeString verifies if an input string matches the format of an RFC 3339 `date-time` representation.
func IsFullDateString ¶
IsFullDateString verifies if an input string matches the format of an RFC 3339 `full-date` representation.
Types ¶
type DateTime ¶
DateTime represents an RFC 3339 `date-time`. It is a wrapper for time.Time.
func MustParseDateTimeString ¶ added in v1.1.0
MustParseDateTimeString wraps NewDateTimeFromString such that if an error happens it generates a panic.
func NewDateTimeFromString ¶
NewDateTimeFromString creates a new DateTime instance from an RFC 3339 `date-time` string representation. Note that the maximum precision of fractional seconds is limited to 9 places. This is due to time.Date's implementation of fractional seconds (basically, it supports a floating-point exponent of 10^9).
func NewFromTime ¶
NewFromTime wraps the `time` instance as an RFC 3339 DateTime.
func (DateTime) MarshalJSON ¶
func (*DateTime) Scan ¶
Scan implements the [sql.Scanner] interface to facilitate reading DateTime strings stored in a database.
func (DateTime) ToFullDate ¶ added in v1.2.0
ToFullDate provides a convenient way to convert a DateTime to a FullDate.
func (DateTime) ToString ¶
ToString serializes the DateTime instance to a full RFC 3339 date-time string representation.
func (*DateTime) UnmarshalJSON ¶
type FullDate ¶
FullDate represents an RFC 3339 `full-date`. It is a wrapper for time.Time. FullDate objects set the time parts to midnight (00:00:00) at the UTC (+00:00) offset.
func MustParseDateString ¶ added in v1.1.0
MustParseDateString wraps NewFullDateFromString such that if an error happens it generates a panic.
func NewFullDateFromString ¶
NewFullDateFromString creates a new FullDate instance from an RFC 3339 `full-date` string representation. Note that the time parts will be set to 00:00:00.000 at the UTC (+00:00) offset.
func (FullDate) MarshalJSON ¶
func (*FullDate) Scan ¶
Scan implements the [sql.Scanner] interface to facilitate reading FullDate strings stored in a database.
func (FullDate) ToDateTime ¶ added in v1.2.0
ToDateTime is a convenient way to convert a FullDate to a DateTime. Note: the DateTime will have its time portion set to 00:00:00 at UTC.
func (FullDate) ToString ¶
ToString serializes the FullDate instance to an RFC 3339 full-date string representation.
Source Files