theIdxTag

README

The idx Tag

What About Memory?

So we can declare the shape of user input using a struct. But what if I'm a sucker for memory performance? If we must declare the fields of an input struct in the order by which we want them displayed to users, we may face a tradeoff in the form of a suboptimal memory layout on that struct.

See, for example, our applicationForm struct from the example(s). Imagine if we wanted to display another bool-type option, ConsentToSMS, after the PhoneNo field, but before the Country field. Because struct fields in Go sit in memory within a contiguous block, we end up with needless padding in two places, generated by Go for the sake of making each field easily addressable by the CPU:

// assume we're on a 64-bit system for this example
type applicationForm struct {
  // ...
  PhoneNo          int
  ConsentToSMS     bool   // 1 byte
  // [ PADDING ]          // 7 bytes
  Country          string
  // ...
  CanTravel        bool   // 1 byte
  // [ PADDING ]          // 7 bytes
  CoverLetter string
}

Go is adding 7 bytes of padding after each boolean-type struct field by design, but we know that were we to pair those boolean fields together (preferably at the end of the struct), our memory layout would be far more optimal: Go would be adding 6 bytes of padding, rather than 14! Yet, because of our selfish desire for a more sensible user form that asks for a user's consent to receive SMS text messages after inquiring about their phone number, we end up wasting a total of 8 precious bytes!

Is there anyone who could help us?

Enter the idx tag! This tag allows us to declare our struct fields in whatever more memory-performant way we desire, while telling structly's bubbletea model what order we actually want to display them in.

// applicationForm holds fields typical of a job application.
type applicationForm struct {
 FirstName        string `idx:"0"`
 LastName         string `idx:"1"`
 Email            string `idx:"2"`
 Country          string `idx:"5"`
 Location         string `idx:"6"`
 CoverLetter      string `idx:"8"`
 PhoneNo          int    `idx:"3"`
 ConsentToSMS     bool   `idx:"4"`
 CanTravel        bool   `idx:"7"`
}

Sure, the order of display may become a bit less readable at a glance by us developers within the source code, but we'll have to accept some tradeoff in the end, right? It's just nice to be able to choose which tradeoff we're willing to accept.

The rules to using the idx tag are strict, but simple:

• All or Nothing: if you use it on one field, use it on all fields.
  • The exception here being on fields with the incompatible bl tag.
• Start at 0: the values must start at 0
• Keep sequence: the values must not break sequence.
  • No values may be skipped.
  • No two values may be the same.

To observe the idx tag in action, run the example at ./example/withIDX/main.go! You'll find that it has the same behavior as seen in the default example, despite the reordered fields under the applicationForm struct.

This is the power of the idx tag!

You can also see a demonstration of just the behavior itself by running the subtest under idx_test.go dedicated to that using the following command in your terminal:

go test -run TestIDXMemoryLayout -v

What's Next?

Now that you've been introduced to the idx tag, you ought to know about its interoperability with the bl tag, which is used for blacklisting fields action the type level.

Read about Field Exceptions