Cell Values

The Value Type

Every cell in werkbook holds a Value — a tagged union with five possible types:

Setting Values

SetValue accepts Go native types and converts them automatically:

// Strings
sheet.SetValue("A1", "Hello, world")

// Numbers — all numeric types become float64
sheet.SetValue("B1", 42)        // int
sheet.SetValue("B2", 3.14)      // float64
sheet.SetValue("B3", int64(99)) // int64
sheet.SetValue("B4", uint(7))   // uint

// Booleans
sheet.SetValue("C1", true)

// Dates — time.Time is stored as an Excel serial number
sheet.SetValue("D1", time.Date(2025, 6, 15, 0, 0, 0, 0, time.UTC))

// Clear a cell
sheet.SetValue("E1", nil)

Reading Values

Use GetValue to retrieve a cell’s value, then inspect the type:

v, err := sheet.GetValue("A1")
if err != nil {
    log.Fatal(err)
}

// Quick access to the underlying value
raw := v.Raw() // returns float64, string, bool, or nil

// Type-specific access
if v.Type == werkbook.TypeNumber {
    fmt.Printf("%.2f\n", v.Number)
}
if v.Type == werkbook.TypeString {
    fmt.Println(v.String)
}

Dates

Excel stores dates as serial numbers — the number of days since January 1, 1900. werkbook handles this conversion automatically:

// Writing a date
sheet.SetValue("A1", time.Date(2025, 1, 15, 0, 0, 0, 0, time.UTC))

// The stored value is a number (Excel serial)
v, _ := sheet.GetValue("A1")
fmt.Println(v.Type)   // TypeNumber
fmt.Println(v.Number) // 45672 (Excel serial for 2025-01-15)

To display dates correctly in Excel, apply a number format:

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

Common date formats: "yyyy-mm-dd", "mm/dd/yyyy", "d-mmm-yy", "mmmm d, yyyy".

Error Values

Formula errors are represented as TypeError with the error string:

v, _ := sheet.GetValue("A1")
if v.Type == werkbook.TypeError {
    fmt.Println(v.String) // "#DIV/0!", "#N/A", "#VALUE!", etc.
}

Supported error values: #DIV/0!, #N/A, #NAME?, #NULL!, #NUM!, #REF!, #VALUE!, #SPILL!, #CALC!.

Empty Cells

werkbook uses sparse storage — empty cells don’t consume memory:

v, _ := sheet.GetValue("Z99")
fmt.Println(v.IsEmpty()) // true
fmt.Println(v.Raw())     // nil