feature idea: Export format()/concat() from fitcsv or add proto.Field.String(

[GgFred]

Hi,

I'm working on a project that reads FIT files and I need to display proto.Field values as formatted strings (applying scale/offset, handling arrays, etc.).

For now, I ended up writing my own version:

func getString(field proto.Field) string {
    if field.Array {
return fmt.Sprintf("%v", field.Value)
    }
switch field.Type {
case profile.Enum:
return "" // skip
case profile.Uint8:
return strconv.FormatFloat(float64(field.Value.Uint8())/field.Scale, 'f', -2, 64)
case profile.Sint8:
return strconv.FormatFloat(float64(field.Value.Int8())/field.Scale, 'f', -2, 64)
case profile.Uint16:
return strconv.FormatFloat(float64(field.Value.Uint16())/field.Scale, 'f', -2, 64)
case profile.Sint16:
return strconv.FormatFloat(float64(field.Value.Int16())/field.Scale, 'f', -2, 64)
case profile.Uint32:
return strconv.FormatFloat(float64(field.Value.Uint32())/field.Scale, 'f', -2, 64)
case profile.Sint32:
return strconv.FormatFloat(float64(field.Value.Int32())/field.Scale, 'f', -2, 64)
case profile.String:
return field.Value.String()
case profile.Float32:
return strconv.FormatFloat(float64(field.Value.Float32())/field.Scale, 'f', -2, 64)
case profile.Float64:
return strconv.FormatFloat(field.Value.Float64()/field.Scale, 'f', -2, 64)
case profile.Uint8z:
return strconv.FormatFloat(float64(field.Value.Uint8z())/field.Scale, 'f', -2, 64)
case profile.Uint16z:
return strconv.FormatFloat(float64(field.Value.Uint16z())/field.Scale, 'f', -2, 64)
case profile.Uint32z:
return strconv.FormatFloat(float64(field.Value.Uint32z())/field.Scale, 'f', -2, 64)
case profile.Byte:
return strconv.FormatFloat(float64(field.Value.Uint8())/field.Scale, 'f', -2, 64)
case profile.Sint64:
return strconv.FormatFloat(float64(field.Value.Int64())/field.Scale, 'f', -2, 64)
case profile.Uint64:
return strconv.FormatFloat(float64(field.Value.Uint64())/field.Scale, 'f', -2, 64)
case profile.Uint64z:
return strconv.FormatFloat(float64(field.Value.Uint64z())/field.Scale, 'f', -2, 64)
case profile.Bool:
return fmt.Sprintf("%v", field.Value.Bool())
case profile.DateTime:
return formatTimestamp(field.Value.Uint32())
case profile.LocalDateTime:
return formatTimestamp(field.Value.Uint32())
case profile.TimeIntoDay:
return fmt.Sprintf("%v", field.Value)
case profile.LocaltimeIntoDay:
return fmt.Sprintf("%v", field.Value)
default:
return fmt.Sprintf("%v", field.Value)
    }
}

But this is essentially duplicating logic that already exists in the codebase. I'd love to avoid maintaining a separate copy.
Maybe the format() and concat() functions in cmd/fitconv/fitcsv/formatter.go are better, but they are unexported.

Would you consider either:

1. Exporting format() and concat() (or a subset) so they can be reused by library consumers?
2. Adding a String() method on proto.Field (or a helper in a public package) that handles scale, offset, and type-aware formatting?

But this is essentially duplicating logic that already exists in the codebase. I'd love to avoid maintaining a separate copy.

What do you think? Happy to contribute a PR if you're open to it.

Thanks for the great library!

[muktihari]

Hi @GgFred, thanks for reaching out.

I believe formatting string the way you wanted is presentation logic, different programs have different intents for how the data should be presented. For example, when printing scaled value, different program might expect to print 4 decimal points instead of 2, some programs might expect to print with "g" flag instead of "f", and other expect raw value, it really depends on the intention of the users.

1. Exporting format() and concat() (or a subset) so they can be reused by library consumers?

The fitconv and all programs under cmd folder are standalone programs and are not part of this library to be used for import. They are more like proof-of-concept or example of programs build using this library, they are useful on their own way. And they are not guaranteed to be stable or even stay in this repository as stated here:

fit/cmd/doc.go

Lines 5 to 8 in 4f0dd1f

	// Package cmd provides CLI programs to work with FIT files.
	// Any code under this package is NOT GUARANTEED to be stable and backward-compatible.
	// If the programs become too complex, they should be separated from this SDK repository.
	package cmd

2. Adding a String() method on proto.Field (or a helper in a public package) that handles scale, offset, and type-aware formatting?

String() method printing only the Value might be ambiguous IMO, users might expect to print all the struct's fields, no?
And for helper, unless it's "generic" enough to be put on this library I will consider it, however, this feature request is more like specific use-case for specific application, even the way fitconv format is different from the code you provided.

While I open for a feature request, I want to keep this library simple for maintenance as well. My suggestion will be to copy the unexported code as you see fit into your code base and maintain it separately.

Let me know if you have more questions. Thanks!

[GgFred]

Thanks for the detailed response!

I understand the reasoning about presentation logic. However, the part I'd find most valuable to have exported is specifically the scale/offset handling. Having it built into the library would make it automatic and prevent users from accidentally forgetting to apply it — which is an easy mistake to make when working with FIT fields.

That said, I'll follow your suggestion and maintain my own copy for now. Thanks again!

[muktihari]

I get that can be tricky, after spending quite a while writing programs using this library and making my share of mistakes, I’ve come to the conclusion that when working directly with FIT fields, I’d expect users to have at least a basic understanding of the protocol and knowing that FIT fields produced by the decoder will always hold raw/unscaled value.

That being said, I’ve created a few helpers to make things a bit easier.

My another suggestion is to try using this building block (?)

import (
	"fmt"
	"strconv"
	"github.com/muktihari/fit/kit/datetime"
	"github.com/muktihari/fit/kit/scaleoffset"
)

func formatValue(field proto.Field) string {
	val := scaleoffset.ApplyAny(field.Value, field.Scale, field.Offset)
	switch x := val.(type) {
	case float64:
		return strconv.FormatFloat(x, 'f', 2, 64) // 0.12
	case []float64:
		var buf = []byte{'['}
		for i, v := range x {
			buf = strconv.AppendFloat(buf, v, 'f', 2, 64)
			if i < len(x)-1 {
				buf = append(buf, ' ')
			}
		}
		buf = append(buf, ']')
		return string(buf) // [0.12 0.34]
	case uint32:
		if field.Type == profile.DateTime || field.Type == profile.LocalDateTime {
			return datetime.ToTime(x).Format(time.RFC3339)
		}
		return fmt.Sprintf("%v", x)
	default:
		return fmt.Sprintf("%v", x)
	}
}

I’ve considered having ValueScaled() method for proto.Field but then I don’t know what value it should be returned, is it anyor Value{} and for what purposes it will be used. Unlike mesgdef structs which its field type is known at compile time, proto.Field is a container for dynamic-type, so I drop the idea and keep it under scaleoffset package as a helper.

[GgFred]

Thanks for the detailed explanation, this clarifies the design choices quite well.

The helper approach makes sense, and the formatValue example is a good starting point. One possible extension could be to make it slightly more flexible, e.g.:
formatValue(field proto.Field, dateLayout string, floatPrec int) string

That would allow callers to control formatting concerns (precision, time layout) without re-implementing the logic on their side.

Regarding the expectation around protocol knowledge, I agree in principle. That said, in practice, some users may interact with FIT data in a more opportunistic way (e.g. integrating into an existing pipeline or addressing a time-constrained requirement) without having a full understanding of the protocol semantics upfront. In those cases, having slightly higher-level helpers can help bridge the gap.

Appreciate the insight—very helpful overall.