Dates and Number Formats

Dates Are Stored as Numbers

Excel stores dates as serial numbers. In werkbook, a date cell still comes back as TypeNumber:

sheet.SetValue("A1", time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC))

v, _ := sheet.GetValue("A1")
fmt.Println(v.Type)   // TypeNumber
fmt.Println(v.Number) // Excel serial

To make spreadsheet apps display that number as a date, apply a number format:

sheet.SetStyle("A1", &werkbook.Style{
    NumFmt: "yyyy-mm-dd",
})

Choose the Workbook Date System

New workbooks use the 1900 date system unless you opt into the 1904 system:

wb := werkbook.New(werkbook.WithDate1904(true))
fmt.Println(wb.Date1904()) // true

You can also switch an existing in-memory workbook:

wb.SetDate1904(true)

This affects how time.Time values are serialized and how date-aware formula formatting behaves.

Detect Date-Like Cells When Reading

The value alone is not enough to know whether a number should be treated as a date. Check the cell style too:

v, _ := sheet.GetValue("B2")
style, _ := sheet.GetStyle("B2")

if v.Type == werkbook.TypeNumber && style != nil &&
    werkbook.IsDateFormat(style.NumFmt, style.NumFmtID) {
    fmt.Println("looks like a date")
}

Convert Serial Numbers to time.Time

The root package exposes a helper for the 1900 date system:

t := werkbook.ExcelSerialToTime(45718)
fmt.Println(t.Format("2006-01-02"))

Important: ExcelSerialToTime interprets serials in the 1900 date system. If wb.Date1904() is true, keep the raw serial or apply your own 1904 conversion in application code.

Custom Formats and Built-In Format IDs

You can use either a custom format string or an Excel built-in format ID:

sheet.SetStyle("C2", &werkbook.Style{NumFmt: "$#,##0.00"})
sheet.SetStyle("C3", &werkbook.Style{NumFmt: "0.00%"})
sheet.SetStyle("C4", &werkbook.Style{NumFmtID: 14}) // common short date format

When both are present, NumFmt takes precedence over NumFmtID.

Formula Formatting

Functions such as TEXT use the workbook date system during evaluation:

sheet.SetFormula("B1", `TEXT(A1, "yyyy-mm-dd")`)

That means the same numeric serial can render differently in 1900 and 1904 workbooks.