GetCandis, GetParamNames, GetParamValue, GetDimNames, GetDimData, GetVFieldNames, GetFieldDims, GetFieldData, GetNextVSlice, NullCandis, AddComment, AddParam, AddDim, AddVField, PutCandis, UpdateVField, PutNextVSlice, CloseCandis, Unflatten2, Unflatten3, Unflatten4, Flatten2, Flatten3, Flatten4 : Read and write Candis files from Go language
This set of routines constitutes the Go language interface to Candis files. The interface is fully general, allowing in particular Candis files with multiple variable slices to be written and read.
For reading files:
c := gocandis.GetCandis(infile string)
This function opens the file "infile", reads the header, the static slice and the first variable slice. This information is stored in a Candis structure which the function returns. If the file name is "-", the standard input is read. The file is left open for subsequent reads of possible additional variable slices.
mycomments := c.GetComments()
This method returns a list (slice of strings) of comments.
myparams := c.GetParamNames()
This method returns a list (slice of strings) of parameter names.
mypvalue := c.GetParamValue(pname string)
This method returns the value of a parameter as a string. If the parameter does not exist, the program fails.
mydims := c.GetDimNames()
This method returns a list (slice of strings) of dimension names.
mydata := c.GetDimData(dname string)
This method returns a pointer to the data associated with a dimension in the form of a slice of float64 elements.
myfields := c.GetVFieldNames()
This method returns a list (slice of strings) of variable field names.
mydims := c.GetFieldDims(fname string)
This method returns a list of dimensions associated with the named field in the form of a slice of strings. The field is sought first in the variable slice and then (as a legacy measure) in the static slice.
mydata := c.GetFieldData(fname string)
This method returns a pointer to the data associated with a field in the form of a flat (one-dimensional) slice of float64 elements. See the section on indexing below for dealing with multi-dimensional fields. The field is sought first in the variable slice and then (as a legacy measure) in the static slice.
ssize := c.GetNextVSlice()
This method reads the next variable slice, replacing the variable slice data in the Candis structure with the new data. The number of elements in the variable slice is returned. If this is zero, than no succeeding slice was found.
For creating Candis structures (must not be associated with an open file):
c := gocandis.NullCandis()
This function returns an empty Candis structure to which elements can be added subsequently.
c.AddComment(comment string)
This method adds a comment to a Candis structure. The comment string need not be terminated by a newline.
c.AddParam(pname string, pvalue string)
This method adds a parameter and its value to a Candis structure.
c.AddDim(dname string, data []float64)
This method adds a dimension to a Candis structure. The dimension data values are in the form of a float64 slice. The length of this slice determines the number of dimension elements. Dimensions are represented as fields in the static slice. Data values are converted to float32 and represented in a byte stream in big-endian order when sent to the output. Float64 is retained in the Candis struct since Go math functions only work on float64.
c.AddVField(name string, dlist []string, data []float64)
This method adds a variable field to a Candis structure. The dimensions over which the field is defined are represented by a slice containing dimension names. The length of this slice gives the number of dimensions used by this field, which must be less than or equal to 4. The dimensions must be in the same order as dimensions are defined using AddDim. The data are represented by a flat (one dimensional) slice of float64 values. See the section below on indexing for how to deal with multi-dimensional variable fields. Data values are converted to float32 and represented in a byte stream in big-endian order when sent to the output. Float64 is retained in the Candis struct since Go math functions only work on float64.
For writing Candis files:
c.PutCandis(outfile string)
This method writes a Candis file based on the information in a Candis structure. The file is left open for the writing of subsequent variable slices. If the file name is "-", the Candis file is written to the standard output.
c.UpdateVField(fname string, data []float64)
This method updates the data in a variable field of a Candis structure without touching the header. Use this in conjunction with PutNextVslice to create Candis files with multiple variable fields.
c.PutNextVSlice()
This method writes an additional variable slice to a Candis file from information in the Candis structure. The variable slice has presumably been updated by calls to UpdateVField.
Cleanup:
c.CloseCandis()
This method closes a Candis file whether opened for read or write. The file pointer is also zeroed. Headers can be modified after a close operation.
Multi-dimensional fields are stored in flattened form as one-dimensional slices. As in C and Go, and unlike Fortran, the last dimension iterates most rapidly.
To index the flattened version x2flat of a two-dimensional variable x2 with dimension sizes [n1 n2], write:
x2flat[i1*n2 + i2]
For a three-dimensional variable x3 with [n1 n2 n3], write:
x3flat[(i1*n2 + i2)*n3 + i3]
For a four-dimensional variable x4 with [n1 n2 n3 n4], write:
x4flat[((i1*n2 + i2)*n3 + i3)*n4 + i4]
where the indices vary over the ranges as follows: i1 = [0, n1 - 1], i2 = [0, n2 - 1], i3 = [0, n3 - 1], i4 = [0, n4 - 1].
The functions below allow multi-dimensional fields to be referenced in an unflattened manner.
unflat2 := gocandis.Unflatten2(n1, n2 int, flat []float64)
This function creates the two-dimensional float64 slice "unflat2" from the flattened slice "flat". The integer slice indices i1 and i2 take on values in the ranges [0,n1 - 1] and [0,n2 - 1] respectively. Accessing the element at (i1,i2) is done with the syntax "unflat2[i1][i2]". Unflattening copies no data -- "flat2[i1*n2 + i2]" and "unflat2[i1][i2]" refer to the same element.
unflat3 := gocandis.Unflatten3(n1, n2, n3 int, flat []float64)
As Unflatten2, except for a three-dimensional field.
unflat4 := gocandis.Unflatten4(n1, n2, n3, n4 int, flat []float64)
As Unflatten2, except for a four-dimensional field.
flat := gocandis.Flatten2(unflat2 [][]float64)
Flatten the unflattened two-dimensional float64 slice. This operates via a copy, so that the flattened slice is independent of the unflattened slice.
flat := gocandis.Flatten3(unflat3 [][][]float64)
As Flatten2, except for the three-dimensional case.
flat := gocandis.Flatten4(unflat4 [][][][]float64)
As Flatten2, except for the four-dimensional case.
Gocandis does not create non-index static fields, though it can read them. (This is not actually a bug, but some people might view it as such.)