stringpool

README

stringpool

Tricky and fun utilities for Go programs.

---

---

Getting Started

Prerequisites

• Go
• Git
• GitHub CLI

Developed with go1.17.6 darwin/arm64. Go is extremely backwards compatible and semver stable. Nearly any v1.x should work fine.

---

Installation

To use this repo as a template for your own project:

gh repo create -y --public --template "https://github.com/skeptycal/stringpool"

Clone this repo to test and contribute:

# add repo to $GOPATH (xxxxxx is your computer login username)
go get github.com/xxxxxx/stringpool

cd ${GOPATH}/src/github.com/xxxxxx/stringpool

# test results and coverage info
./go.test.sh

# install as a utility package
go install

Use the Issues and PR templates on the GitHub repo page to contribute.

---

Basic Usage

This is a copy of the example script available in the cmd/example/stringpool folder:

package main

import "github.com/skeptycal/stringpool"

func main() {
    stringpool.Example()
}

To try it out:

# change to the sample folder
cd cmd/example/stringpool

# run the main.go program
go run ./main.go

# to compile as an executable
go build

---

Code of Conduct and Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us. Please read the Code of Conduct for details before submitting anything.

---

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

---

Contributors and Inspiration

• Michael Treanor (GitHub / Twitter) - Initial work, updates, maintainer
• Francesc Campoy - Inspiration and great YouTube videos!

See also the list of contributors who participated in this project.

---

License

Licensed under the MIT https://opensource.org/licenses/MIT - see the LICENSE file for details.

Documentation

Overview

Package stringpool provides a sync.Pool of efficient strings.Builder workers that may be reused as needed, reducing the need to instantiate and allocate new builders in text heavy applications.

From the Go standard library:

A Builder is used to efficiently build a string using Write methods. It minimizes memory copying.

A Pool is used to cache allocated but unused items for later reuse, relieving pressure on the sgarbage collector. That is, it makes it easy to build efficient, thread-safe free lists.

Go 1.10 or later is required.

Index

• func Example()
• func Get() *strings.Builder
• func Release(b *strings.Builder)
• type StringPool
  • func New() *StringPool
  • func (bp StringPool) Get() *strings.Builder
  • func (bp StringPool) Release(b *strings.Builder)

Examples

• Example

Functions

func Example

func Example()

Example

package main

func Exampleexample() {
	example()
	

Output:

stringpool example:

0 + '\x00'
1 + '\x01'
2 + '\x02'
3 + '\x03'
4 + '\x04'
5 + '\x05'
6 + '\x06'
7 + '\a'
8 + '\b'
9 + '\t'
10 + '\n'
11 + '\v'
12 + '\f'
13 + '\r'
14 + '\x0e'
15 + '\x0f'
16 + '\x10'
17 + '\x11'
18 + '\x12'
19 + '\x13'
20 + '\x14'
21 + '\x15'
22 + '\x16'
23 + '\x17'
24 + '\x18'
25 + '\x19'
26 + '\x1a'
27 + '\x1b'
28 + '\x1c'
29 + '\x1d'
30 + '\x1e'
31 + '\x1f'
32 + ' '
33 + '!'
34 + '"'
35 + '#'
36 + '$'
37 + '%'
38 + '&'
39 + '\''
40 + '('
41 + ')'
42 + '*'
43 + '+'
44 + ','
45 + '-'
46 + '.'
47 + '/'
48 + '0'
49 + '1'
50 + '2'
51 + '3'
52 + '4'
53 + '5'
54 + '6'
55 + '7'
56 + '8'
57 + '9'
58 + ':'
59 + ';'
60 + '<'
61 + '='
62 + '>'
63 + '?'
64 + '@'
65 + 'A'
66 + 'B'
67 + 'C'
68 + 'D'
69 + 'E'
70 + 'F'
71 + 'G'
72 + 'H'
73 + 'I'
74 + 'J'
75 + 'K'
76 + 'L'
77 + 'M'
78 + 'N'
79 + 'O'
80 + 'P'
81 + 'Q'
82 + 'R'
83 + 'S'
84 + 'T'
85 + 'U'
86 + 'V'
87 + 'W'
88 + 'X'
89 + 'Y'
90 + 'Z'
91 + '['
92 + '\\'
93 + ']'
94 + '^'
95 + '_'
96 + '`'
97 + 'a'
98 + 'b'
99 + 'c'
100 + 'd'
101 + 'e'
102 + 'f'
103 + 'g'
104 + 'h'
105 + 'i'
106 + 'j'
107 + 'k'
108 + 'l'
109 + 'm'
110 + 'n'
111 + 'o'
112 + 'p'
113 + 'q'
114 + 'r'
115 + 's'
116 + 't'
117 + 'u'
118 + 'v'
119 + 'w'
120 + 'x'
121 + 'y'
122 + 'z'
123 + '{'
124 + '|'
125 + '}'
126 + '~'
127 + '\u007f'
128 + '\u0080'
129 + '\u0081'
130 + '\u0082'
131 + '\u0083'
132 + '\u0084'
133 + '\u0085'
134 + '\u0086'
135 + '\u0087'
136 + '\u0088'
137 + '\u0089'
138 + '\u008a'
139 + '\u008b'
140 + '\u008c'
141 + '\u008d'
142 + '\u008e'
143 + '\u008f'
144 + '\u0090'
145 + '\u0091'
146 + '\u0092'
147 + '\u0093'
148 + '\u0094'
149 + '\u0095'
150 + '\u0096'
151 + '\u0097'
152 + '\u0098'
153 + '\u0099'
154 + '\u009a'
155 + '\u009b'
156 + '\u009c'
157 + '\u009d'
158 + '\u009e'
159 + '\u009f'
160 + '\u00a0'
161 + '¡'
162 + '¢'
163 + '£'
164 + '¤'
165 + '¥'
166 + '¦'
167 + '§'
168 + '¨'
169 + '©'
170 + 'ª'
171 + '«'
172 + '¬'
173 + '\u00ad'
174 + '®'
175 + '¯'
176 + '°'
177 + '±'
178 + '²'
179 + '³'
180 + '´'
181 + 'µ'
182 + '¶'
183 + '·'
184 + '¸'
185 + '¹'
186 + 'º'
187 + '»'
188 + '¼'
189 + '½'
190 + '¾'
191 + '¿'
192 + 'À'
193 + 'Á'
194 + 'Â'
195 + 'Ã'
196 + 'Ä'
197 + 'Å'
198 + 'Æ'
199 + 'Ç'
200 + 'È'
201 + 'É'
202 + 'Ê'
203 + 'Ë'
204 + 'Ì'
205 + 'Í'
206 + 'Î'
207 + 'Ï'
208 + 'Ð'
209 + 'Ñ'
210 + 'Ò'
211 + 'Ó'
212 + 'Ô'
213 + 'Õ'
214 + 'Ö'
215 + '×'
216 + 'Ø'
217 + 'Ù'
218 + 'Ú'
219 + 'Û'
220 + 'Ü'
221 + 'Ý'
222 + 'Þ'
223 + 'ß'
224 + 'à'
225 + 'á'
226 + 'â'
227 + 'ã'
228 + 'ä'
229 + 'å'
230 + 'æ'
231 + 'ç'
232 + 'è'
233 + 'é'
234 + 'ê'
235 + 'ë'
236 + 'ì'
237 + 'í'
238 + 'î'
239 + 'ï'
240 + 'ð'
241 + 'ñ'
242 + 'ò'
243 + 'ó'
244 + 'ô'
245 + 'õ'
246 + 'ö'
247 + '÷'
248 + 'ø'
249 + 'ù'
250 + 'ú'
251 + 'û'
252 + 'ü'
253 + 'ý'
254 + 'þ'

stringpool example

Example import acknowledgement from package stringpool

func Get

func Get() *strings.Builder

Get returns an empty strings.Builder from the global pool.

A Builder is used to efficiently build a string using Write methods. It minimizes memory copying. The zero value is ready to use. Do not copy a non-zero Builder.

func Release

func Release(b *strings.Builder)

Release puts the given strings.Builder back into the global pool after resetting the Builder. It will no longer be accesible after this operation,ss but its resources will still be available to be reallocated in a new Get() call.

Builders stored in the Pool may be removed automatically at any time without notification. If the Pool holds the only reference when this happens, the item might be deallocated.

Types

type StringPool

type StringPool struct {
	// contains filtered or unexported fields
}

StringPool is a sync.Pool for strings.Builder objects.

Reference (Go standard library): A Pool is a set of temporary objects that may be individually saved and retrieved.

Any item stored in the Pool may be removed automatically at any time without notification. If the Pool holds the only reference when this happens, the item might be deallocated.

A Pool is safe for use by multiple goroutines simultaneously.

Pool's purpose is to cache allocated but unused items for later reuse, relieving pressure on the garbage collector. That is, it makes it easy to build efficient, thread-safe free lists. However, it is not suitable for all free lists.

An appropriate use of a Pool is to manage a group of temporary items silently shared among and potentially reused by concurrent independent clients of a package. Pool provides a way to amortize allocation overhead across many clients.

An example of good use of a Pool is in the fmt package, which maintains a dynamically-sized store of temporary output buffers. The store scales under load (when many goroutines are actively printing) and shrinks when quiescent.

On the other hand, a free list maintained as part of a short-lived object is not a suitable use for a Pool, since the overhead does not amortize well in that scenario. It is more efficient to have such objects implement their own free list.

A Pool must not be copied after first use.

func New

func New() *StringPool

New returns a new StringPool instance. A StringPool is used to allocate and release strings.Builder objects as needed.

A Pool must not be copied after first use. A Pool is safe for use by multiple goroutines simultaneously.

func (StringPool) Get

func (bp StringPool) Get() *strings.Builder

Get returns an empty strings.Builder from the pool.

A Builder is used to efficiently build a string using Write methods. It minimizes memory copying. The zero value is ready to use. Do not copy a non-zero Builder.

func (StringPool) Release

func (bp StringPool) Release(b *strings.Builder)

Release puts the given strings.Builder back into the pool after resetting the Builder. It will no longer be accesible after this operation,ss but its resources will still be available to be reallocated in a new Get() call.

Builders stored in the Pool may be removed automatically at any time without notification. If the Pool holds the only reference when this happens, the item might be deallocated.