~mna/zzcsi

6cbe3589be6a356a6298cac65a81f6a5c091c199 — Martin Angers 1 year, 2 months ago 4ba91c1
benchmarks and doc
2 files changed, 55 insertions(+), 4 deletions(-)

M README.md
M csi_test.go
M README.md => README.md +28 -4
@@ 1,12 1,35 @@
# zztermcsi [![builds.sr.ht status](https://builds.sr.ht/~mna/zztermcsi.svg)](https://builds.sr.ht/~mna/zztermcsi?) [![GoDoc](https://godoc.org/git.sr.ht/~mna/zztermcsi?status.svg)](http://godoc.org/git.sr.ht/~mna/zztermcsi) [![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/git.sr.ht/~mna/zztermcsi)

Package zztermcsi [TODO ...]. See the [package documentation][godoc] for details,
API reference and usage example (alternatively, on [pkg.go.dev][pgd]).

* Canonical repository: https://git.sr.ht/~mna/zztermcsi
* Issues: https://todo.sr.ht/~mna/zztermcsi
* Builds: https://builds.sr.ht/~mna/zztermcsi

Package zztermcsi implements the Control Sequence Introducer (CSI) functions
supported by Xterm-compatible terminals. The most commonly used functions are
to erase a line or the screen, manipulate the cursor or set the display
attributes such as foreground and background colors, bold or italics, but many
more functions are available. See the [xterm documentation][xterm] for more
information on CSI sequences.

See the [package documentation][godoc] for details, API reference and usage
example (alternatively, on [pkg.go.dev][pgd]).

This is a package in the [zzterm][zzt] family of Go packages, which aim to
help build terminal-based programs with a focus on speed and memory efficiency.

## Benchmarks

When using a buffer of sufficient capacity, `CSI.AppendFunc` can append the
CSI escape sequence without allocation.

```
benchmark                       iter      time/iter   bytes alloc        allocs
---------                       ----      ---------   -----------        ------
BenchmarkCSI/Func-4          9259478   118.00 ns/op       24 B/op   2 allocs/op
BenchmarkCSI/FuncString-4    9003938   133.00 ns/op       32 B/op   3 allocs/op
BenchmarkCSI/AppendFunc-4   20808049    58.40 ns/op        0 B/op   0 allocs/op
```

## License

The [BSD 3-Clause license][bsd].


@@ 14,4 37,5 @@ The [BSD 3-Clause license][bsd].
[bsd]: http://opensource.org/licenses/BSD-3-Clause
[godoc]: http://godoc.org/git.sr.ht/~mna/zztermcsi
[pgd]: https://pkg.go.dev/git.sr.ht/~mna/zztermcsi

[xterm]: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-ordered-by-the-final-character_s_
[zzt]: https://git.sr.ht/~mna/zzterm

M csi_test.go => csi_test.go +27 -0
@@ 88,3 88,30 @@ func TestIsCSI(t *testing.T) {
		})
	}
}

var (
	BenchmarkResultString string
	BenchmarkResultBytes  []byte
)

func BenchmarkCSI(b *testing.B) {
	b.Run("Func", func(b *testing.B) {
		for i := 0; i < b.N; i++ {
			BenchmarkResultBytes = ChLnCol.Func(12, 80)
		}
	})

	b.Run("FuncString", func(b *testing.B) {
		for i := 0; i < b.N; i++ {
			BenchmarkResultString = ChLnCol.FuncString(12, 80)
		}
	})

	b.Run("AppendFunc", func(b *testing.B) {
		buf := make([]byte, 0, 8)
		b.ResetTimer()
		for i := 0; i < b.N; i++ {
			BenchmarkResultBytes = ChLnCol.AppendFunc(buf, 12, 80)
		}
	})
}