Cell Values

The Value Type

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

ValueType	Go Type	Description
TypeEmpty	nil	Cell has no data
TypeNumber	float64	All numeric values
TypeString	string	Text content
TypeBool	bool	true or false
TypeError	string	Error like #DIV/0!

The fields are intentionally simple:

type Value struct {
    Type   ValueType
    Number float64
    String string
    Bool   bool
}

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 a .xlsx date serial number
sheet.SetValue("D1", time.Date(2025, 6, 15, 0, 0, 0, 0, time.UTC))

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

// Reuse an existing Value
sheet.SetValue("F1", werkbook.Value{Type: werkbook.TypeString, String: "ok"})

Accepted inputs are:

• nil
• string
• bool
• every signed and unsigned integer type
• float32 and float64
• time.Time
• werkbook.Value

float32 and float64 values must be finite. NaN and Inf return ErrUnsupportedType.

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)
}

Value.Raw() returns float64, string, bool, or nil. For TypeError, inspect Value.String.

Dates

Spreadsheet files store 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 (.xlsx serial)
v, _ := sheet.GetValue("A1")
fmt.Println(v.Type)   // TypeNumber
fmt.Println(v.Number) // 45672 (.xlsx serial for 2025-01-15)

To display dates correctly in spreadsheet apps, 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".

If you need a workbook to use the Mac 1904 date system, create it with werkbook.WithDate1904(true) or call wb.SetDate1904(true) before writing.

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

Reading an unset cell is not an error. You get TypeEmpty.