Documentation
¶
Overview ¶
Package value holds what a cell computes to and how it is shown: the Value of a cell, its number Format, and the parsing of typed text into numbers, dates and times. It sits below the function library (internal/functions) and the engine (internal/sheet), which both work in these terms; the engine's API names them too, so callers see one package.
Index ¶
- Constants
- Variables
- func AsText(v Value) string
- func Canonicalize(s string, loc *locale.Locale) (string, bool)
- func Compare(l, r Value) int
- func CompareShown(l, r Value) int
- func Localize(s string, loc *locale.Locale) string
- func ParseNumber(s string) (float64, bool)
- func SameShown(a, b float64) bool
- func SizeCode(dec int) string
- type Format
- type FormatKind
- type Kind
- type Value
Constants ¶
const MaxDecimals = 15
MaxDecimals caps Increase decimal places.
Variables ¶
var ( ErrDiv0 = Value{Kind: Error, Str: "#DIV/0!"} ErrValue = Value{Kind: Error, Str: "#VALUE!"} ErrName = Value{Kind: Error, Str: "#NAME?"} ErrNA = Value{Kind: Error, Str: "#N/A"} ErrNum = Value{Kind: Error, Str: "#NUM!"} ErrRef = Value{Kind: Error, Str: "#REF!"} // also circular references )
Error values, using Google Sheets codes.
var Now = time.Now
Now is the clock used by TODAY() and NOW(), and for the year of dates typed without one; tests replace it.
Functions ¶
func Canonicalize ¶ added in v0.3.0
Canonicalize rewrites a number, date or time typed in loc as it would be typed in en-US, reporting false when s isn't one in loc.
func Compare ¶
Compare orders values like Sheets: numbers < text < booleans, text is case-insensitive, and a blank equals 0 or "".
func CompareShown ¶ added in v0.4.0
CompareShown is Compare as the comparison operators and criteria see numbers: at the 15 significant digits a cell shows, as Sheets and Excel do, so =0.1+0.2=0.3 is TRUE though the sum is 0.30000000000000004. Sorting and lookups use Compare, which is exact and so orders values consistently.
func Localize ¶ added in v0.3.0
Localize is the inverse of Canonicalize: a number, date or time entry as stored, written as typed in loc. Anything else is returned as is.
func ParseNumber ¶
ParseNumber recognizes numbers the way Google Sheets does on entry: optional sign, optional leading currency symbol, thousands separators, decimals, exponent, and a trailing percent sign ("12%" is 0.12).
func SizeCode ¶ added in v0.3.0
SizeCode is the custom number format closest to the Size format with dec decimals, written with conditions as Sheets and Excel take them: bytes below 1000, then kB and MB, e.g. [<1000]0" B";[<1000000]0.0," kB";0.0,," MB". Size itself goes on to GB, TB, PB and EB; files keep this code for other programs.
Types ¶
type Format ¶
type Format struct {
Kind FormatKind
Decimals int // for Number, Percent, Scientific, Accounting, Financial, Currency
// Pattern is the pattern of a FmtCustom, or overrides the default
// pattern of a date or time kind (a date typed as 2026-09-26 keeps
// that style, as in Sheets).
Pattern string
}
Format is a cell's number format. It is a plain value so cells can be copied freely.
func ParseDateTime ¶
ParseDateTime recognizes dates and times typed into a cell the way Sheets does in the en-US locale: 9/26/2026, 9/26/26, 9/26 (this year), 2026-09-26, Sep 26, 2026, 26 Sep 2026, 14:30, 2:30 PM, 2pm, 25:30 (a duration) and a date followed by a time. It returns the serial and the format Sheets would apply.
func ParseValue ¶
ParseValue recognizes everything Sheets turns into a number on entry: numbers, currency, percentages, dates and times. It also returns the format Sheets applies, e.g. Currency for "$1,200" or Date for "9/26/2026"; plain numbers get Automatic.
func ParseValueIn ¶ added in v0.3.0
ParseValueIn is ParseValue for an entry typed in loc.
func Preset ¶
func Preset(k FormatKind) Format
Preset returns kind with Sheets' default decimals: two for the number kinds, and one for sizes, as nushell shows them.
func (Format) Code ¶
Code returns the Sheets-style format pattern f renders with, or "" for Automatic and Plain text.
func (Format) CodeIn ¶ added in v0.3.0
CodeIn is Code as shown in loc: the Currency format with loc's symbol and the Date, Time and Date time formats in loc's order. Patterns of their own are the same in every locale.
func (Format) WithDecimals ¶
WithDecimals returns f showing delta more (or fewer) decimal places, as Sheets' Increase and Decrease decimal places do. v is the value shown, used when f is Automatic to start from the decimals currently visible. Formats without decimals (dates, plain text) are returned unchanged.
type FormatKind ¶
type FormatKind uint8
FormatKind is a number format from Sheets' Format > Number menu.
const ( FmtAuto FormatKind = iota // General; formulas may infer a format FmtText // Plain text: entries stay as typed FmtNumber // 1,000.12 FmtPercent // 10.12% FmtScientific // 1.01E+03 FmtAccounting // $ (1,000.12) FmtFinancial // (1,000.12) FmtCurrency // $1,000.12 FmtDate // 9/26/2026 FmtTime // 3:59:00 PM FmtDateTime // 9/26/2026 15:59:00 FmtDuration // 24:01:00 FmtCustom // Pattern, e.g. from Increase decimal places on Automatic FmtSize // 1.6 kB: a count of bytes, as nushell shows file sizes )
func ParseFormatKind ¶
func ParseFormatKind(s string) (FormatKind, bool)
ParseFormatKind is the inverse of FormatKind.String.
func (FormatKind) HasDecimals ¶
func (k FormatKind) HasDecimals() bool
HasDecimals reports whether the kind takes a number of decimal places.
func (FormatKind) IsTime ¶
func (k FormatKind) IsTime() bool
IsTime reports whether the kind shows a date, time or duration.
func (FormatKind) String ¶
func (k FormatKind) String() string
String returns the kind's name as stored in files.
type Value ¶
type Value struct {
Kind Kind
Num float64 // numbers, and booleans as 1 or 0
Str string // text, or the error code such as #DIV/0!
}
Value is the computed contents of a cell.
func ErrOf ¶
ErrOf returns a pointer to a copy of v, for the *Value error results of argument helpers. Taking &v of a parameter directly would move it to the heap on every call, erroneous or not: one allocation per cell read by SUM over a range.
Source Files