Documentation
¶
Overview ¶
Package timeline turns the intervals of an event or a report into a table: one row per period of time and payload, with the start and end worked out.
OpenADR writes intervals compactly. An event has a default period, an interval may override it or follow the previous one, a start may mean "now", a payload may pack several values into one interval, and the duration of the event may cut the intervals short or repeat them. Of and OfEvent apply those rules (User Guide, "Event and Interval Timing") so that a program does not have to:
rows, err := timeline.OfEvent(event, timeline.Options{SubIntervals: true})
for _, row := range rows.At(time.Now()) {
fmt.Println(row.Type, row.Values)
}
A Table can be written as CSV and read back, and Intervals makes intervals of the rows again, to build an event from a table.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrTooLarge = errors.New("timeline: too many rows")
ErrTooLarge is returned for a table of more than about a million rows. Set Options.Until to lay out a part of such an event.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// Now is the time a start of "now" stands for; the current time when
// zero.
Now time.Time
// SubIntervals splits a payload that holds several values into as many
// rows of equal length, one value each, as the specification has it
// for values that were packed into one interval. A payload that holds
// a point is left whole: its values are a curve, not a series.
SubIntervals bool
// Until bounds the rows of an event whose duration repeats its
// intervals. Without it such an event is laid out once if it repeats
// without end, and for its whole duration otherwise.
Until time.Time
}
Options decide how intervals are laid out.
type Row ¶
type Row struct {
// IntervalID is the ID of the interval the row comes from. A report
// uses it to say which interval of the event it is about.
IntervalID int32
// Sub numbers the rows that one payload with several values was split
// into, from 0; see Options.SubIntervals.
Sub int
// Start is when the period begins, and End when it is over. A zero End
// is a period without end.
Start, End time.Time
// RandomizeStart is the range within which a client is to shift Start,
// when not zero. The table shows the times as announced.
RandomizeStart openadr.Duration
// Type says what the values are, such as "PRICE".
Type string
Values []openadr.Value
}
Row is one payload over one period of time.
type Table ¶
type Table []Row
Table is a list of rows, in the order of their intervals.
func Of ¶
Of lays out intervals. period is the default of the intervals, as an event, or a resource of a report, carries it; it may be nil when every interval has a period of its own.
func OfEvent ¶
OfEvent lays out the intervals of an event, and applies the duration of the event: one shorter than the intervals leaves out what lies beyond it, and a longer one repeats them.
Example ¶
package main
import (
"fmt"
"time"
openadr "github.com/otfabric/go-openadr"
"github.com/otfabric/go-openadr/timeline"
)
func main() {
start := time.Date(2030, 1, 1, 0, 0, 0, 0, time.UTC)
event := openadr.Event{
IntervalPeriod: &openadr.IntervalPeriod{Start: &start, Duration: &openadr.Duration{Hours: 1}},
Intervals: []openadr.Interval{
{ID: 0, Payloads: []openadr.ValuesMap{{Type: "PRICE", Values: []openadr.Value{openadr.Number(0.17)}}}},
// Two prices packed into one interval: half an hour each.
{ID: 1, Payloads: []openadr.ValuesMap{{Type: "PRICE", Values: []openadr.Value{openadr.Number(0.21), openadr.Number(0.09)}}}},
},
}
rows, err := timeline.OfEvent(event, timeline.Options{SubIntervals: true})
if err != nil {
panic(err)
}
for _, row := range rows {
fmt.Println(row.Start.Format("15:04"), row.End.Format("15:04"), row.Type, row.Values[0])
}
}
Output: 00:00 01:00 PRICE 0.17 01:00 01:30 PRICE 0.21 01:30 02:00 PRICE 0.09
func ReadCSV ¶
ReadCSV reads a table that WriteCSV wrote, or one written by hand or by a spreadsheet. The header line is required and names the columns, in any order; start, type and values are required, and columns it does not know are ignored. A row without interval gets the number of its line, from 0. A cell of values that is not JSON is taken as a string.
func (Table) Intervals ¶
Intervals makes intervals of the rows, each with a period of its own, so that they need no default. Consecutive rows with the same IntervalID become one interval that spans them; within it, the rows of one Type become one payload, with their values in order. It is the reverse of Of with or without SubIntervals, for rows that are contiguous.
func (Table) Span ¶
Span returns the earliest start and the latest end of the rows. The end is zero when a row has none, and both are for an empty table.
func (Table) WriteCSV ¶
WriteCSV writes the table as CSV with a header line:
interval,sub,start,end,type,values,randomize_start 0,0,2030-01-01T00:00:00Z,2030-01-01T01:00:00Z,PRICE,0.17,
Times are RFC 3339 and keep their offset; end is empty for a period without end. values is written as JSON: one value as it is (0.17, true, "text", {"x":1,"y":2}), several as an array. randomize_start is an ISO 8601 duration, or empty.