-
Notifications
You must be signed in to change notification settings - Fork 16
/
go_standard_library.go.txt
425 lines (345 loc) · 23 KB
/
go_standard_library.go.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
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
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
GO_STANDARD_LIBRARY
VERSION ==> #See Go language
RELATED DOCUMENTATION ==> #See Go language
/=+===============================+=\
/ : : \
)==: RUNTIME OS :==(
\ :_______________________________: /
\=+===============================+=/
go version #Prints "go version goX.Y GOOS/GOARCH"
runtime.Version()->STR #'goX.Y' or 'COMMIT-DATE'
runtime.GOOS #OS name
#Among "linux", "darwin", "windows", "freebsd|netbsd|openbsd|dragonfly", "solaris|illumos", "plan9",
#"aix", "android", "ios", "nacl" (Chrome OS), "js" (with GOARCH "wasm")
#Can be set manually with ENVVAR GOOS
runtime.GOARCH #CPU architecture
#Among "386|amd64[p32]", "arm[64]", "ppc64[le]", "mips[64][le]", "s390x", "riscv64", "wasm"
#Can be set manually with ENVVAR GOARCH
ENVVAR GOARM #"5|6|7". ARM version, with GOARCH=arm
ENVVAR GO386 #"softfloat|sse2". Floating point version, with GOARCH=386
ENVVAR GOMIPS[64] #"hardfloat|softfloat". Floating point version, with GOARCH=mips[64][le]
ENVVAR GOWASM #"FEAT,...". Experimental features, with GOARCH=wasm, among "satconv|signext"
ENVVAR GOHOSTOS|GOHOSTARCH #Like ENVVAR GOOS|GOARCH except readonly
ENVVAR GOEXE #Built file file extension. "" on Unix, ".exe" on Windows
#Read-only
/=+===============================+=\
/ : : \
)==: RUNTIME CPU :==(
\ :_______________________________: /
\=+===============================+=/
runtime.NumCPU()->INT #Number of CPU cores
runtime.GOMAXPROCS(0)->INT2 #Max number of goroutines running in parallel
runtime.GOMAXPROCS(INT)->INT2 #Sets it, and returns the previous one
ENVVAR GOMAXPROCS #Default value for runtime.GOMAXPROCS.
#Def: runtime.NumCPU()
/=+===============================+=\
/ : : \
)==: RUNTIME STACK :==(
\ :_______________________________: /
\=+===============================+=/
ENVVAR GODEBUG=
"tracebackancestors=UINT" #Make stack trace include the stack of the UINT ancestor goroutines. Def: 0
ENVVAR GOTRACEBACK #On panic, how stack traces should be printed, among:
# - 'none|0'
# - 'single' (def): only current goroutine
# - 'all|1': all user-created goroutines
# - 'system|2': all user|system-created goroutines
# - 'crash': like 'system', but creates a core dump
debug.SetTraceback(STR) #Changes GOTRACEBACK. Can only increase level.
debug.Stack()->[]BYTE #Retrieve current call stack formatted
#Only for current goroutine
debug.PrintStack() #Like os.Stderr.Write(debug.Stack())
runtime.Stack([]BYTE, BOOL)->INT #Lower-level function.
#Write current call stack formatted to []BYTE, writing INT bytes
# - []BYTE must already have some length
# - if INT < len([]BYTE), must extend length, then call again
#If BOOL true, includes other goroutines
runtime.Callers(INT, []UINTPTR) #Fills []UINTPTR with current call stack frames (skipping INT innermost stack frames)
->INT2 #Returns number of UINTPTR written
runtime.Caller(INT) #Returns current stack FRAME.PC|File|Line
->UINTPTR,'/PATH',LINE_INT,OK #Skips INT innermost frames.
runtime.CallersFrames([]UINTPTR)
->*FRAMES #Transform to FRAMES
runtime.Frames #Call stack. From inner to outer
FRAMES.Next()->FRAME,BOOL #BOOL is false is last frame.
runtime.Frame #Stack frame
FRAME.PC #UINPTR. Address
#Can be 0 if inline func or not Go
FRAME.Func #*RUNTIME_FUNC.
#nil if non-Go or inlined.
FRAME.Function #Like FRAME.Func.Name()
FRAME.File #Like FRAME.Func.FileLine(FRAME.PC)[0]
FRAME.Line #Like FRAME.Func.FileLine(FRAME.PC)[1]
FRAME.Entry #Like FRAME.Func.Entry()
runtime.Func #Go function
runtime.FuncForPC(UINTPTR)
->*RUNTIME_FUNC #Find the function of a specific address
RUNTIME_FUNC.Name()
->'PACKAGE.FUNC_NAME' #Can be empty ''
RUNTIME_FUNC.FileLine(UINTPTR) #File|line of a specific line of code inside function
->'/PATH',LINE_INT #Can be empty ''|0
RUNTIME_FUNC.Entry()->UINTPTR #Function's address
#Can be 0 if inline func or not Go
debug.WriteHeapDump(UINTPTR) #Write heap core dump to file descriptor UINTPTR
#Includes current memory|state information: variables, goroutines, stack, threads, MemStats,
#There is no good viewer for those at the moment
/=+===============================+=\
/ : : \
)==: RUNTIME LIMITS :==(
\ :_______________________________: /
\=+===============================+=/
debug.SetMaxStack(INT)->INT2 #Sets max stack memory per function before crashing, in byte
#Meant to make infinite recursions crash
#Def: 1GB in 64-bits OS, 250MB in 32-bits
#Returns previous value
debug.SetMaxThread(INT)->INT2 #Sets max amount of OS threads before crashing
#This is not max amount of goroutines, since they re-use OS threads
#Def: 1e4
#Returns previous value
debug.SetPanicOnFault(BOOL)->BOOL2#If true (def), crash when accessing wrong address
#Disabling is only useful when using low-level memory-mapped files or pointer arithmetic
#and want to tolerate errors
#Returns previous value
/=+===============================+=\
/ : : \
)==: RUNTIME GC :==(
\ :_______________________________: /
\=+===============================+=/
GC ==> #Mark-and-sweep.
#Sweeping happens both:
# - incrementally ("heap scavenger"), concurrently
# - during stop-the-world events (STW), serially
#STW are triggered when MEM_STATS.HeapInuse reaches a specific threshold
# - computed by adding|subtracting a specific percentage (GOGC) from previous threshold
#STW are broken down into several "pauses".
ENVVAR GOGC #GC target percentage, from 0-100, or more
#Def: 100
#If negative or 'off', disables GC
debug.SetGCPercent(INT)->INT2 #Sets GOGC
#Returns previous value
runtime.GC() #Force running a GC stop-the-world
debug.FreeOSMemory() #Like runtime.GC() but also returns that memory to the OS
debug.ReadGCStats(*GC_STATS) #Fill GC_STATS
debug.GCStats #Based on runtime.MemStats, but simpler
GC_STATS.NumGC #INT64. Number of GC STWs
GC_STATS.PauseTotal #DURATION spent in all GC STWs
GC_STATS.Pause #[]DURATION spent in each of the last GC pauses. If none, 0
GC_STATS.PauseQuantiles #[]DURATION of the last GC pauses, as quantiles.
GC_STATS.LastGC #TIME of last GC. If none, 0.
GC_STATS.PauseEnd #[]TIME of the last GC pauses. If none, 0.
runtime.MemStats #See runtime.ReadMemStats()
MEM_STATS.NextGC UINT64 #Next GC threshold to trigger STW
MEM_STATS.NumGC UINT32 #Number of GC STWs
MEM_STATS.NumForcedGC UINT32 #Number of runtime.GC() calls
MEM_STATS.PauseTotalNs UINT64 #Number of ns spent in all GC STWs
MEM_STATS.PauseNs [256]UINT_64 #Time spent in each of the last 256 GC pauses. If none, 0.
MEM_STATS.GCCPUFraction FLOAT64 #How much % of CPU time was spent in GC
MEM_STATS.LastGC UINT64 #Last GC's Unix timestamp (in ns). If none, 0.
MEM_STATS.PauseEnd [256]UINT_64 #Unix timestamp (in ns) of the last 256 GC pauses. If none, 0.
MEM_STATS.EnableGC BOOL #Whether GC is enabled (def: true)
MEM_STATS.DebugGC BOOL #Always false
runtime.SetFinalizer #Calls FUNC(VAL) when VAL is about to be GC'd
(VAL, FUNC(VAL)|nil) # - should not rely:
# - on when|whether GC happens, since this is very variable
# - on it to guess when|whether GC happens
#If nil, removes any finalizer FUNC instead.
#VAL must be *STRUCT
#If VAL contains members with finalizers, run those first
runtime.KeepAlive(VAL) #When calling SetFinalizer(VAL) and last statement using VAL is async,
#finalizer might be run before async completes.
#Doing KeepAlive() right after async statement prevents this.
ENVVAR GODEBUG #'VAR=VAL,...'
GODEBUG="gctrace=1" #Print debug information about GC during different phases
GODEBUG="gcpacertrace=1" #Print debug information about GC sweeps
GODEBUG="scavenge=1" #Print debug information about GC heap scavenger
GODEBUG="scavtrace=1" #Print verbose debug information about GC heap scavenger
GODEBUG="gccheckmark=1" #After GC STW, do a second pass to find reachable object, and crash if find one. Meant to debug GC internals.
GODEBUG="allocfreetrace=1" #Print a stack trace each time an object is allocated|freed on the heap. Very verbose.
GODEBUG="gcstoptheworld=0|1|2" #Can be:
# - 0 (def): STW and sweeping are sometimes concurrent
# - 1: STW is serial, sweeping is sometimes concurrent
# - 2: STW and sweeping and serial
GODEBUG="clobberfree=1" #When GC is freeing an object, replace it in memory with random data.
GODEBUG="sbrk=1" #Do not return memory to OS nor run GC. Only meant for memory debugging.
GODEBUG="efence=1" #Allocate all memory in same page, and never re-use same address (i.e. run out of memory quickly). Meant for memory debugging.
GODEBUG="madvdontneed=1" #On Linux, use MADV_DONTNEED instead of MADV_FREE when returning memory to OS.
#Slower but makes RSS decrease faster.
GODEBUG="gcshrinkstackoff=1" #Disables optimizing goroutine stack size. Meant for memory debugging.
GODEBUG="invalidptr=1" #Do not crash when storing non-address values in *TYPE. Only meant for debugging.
GODEBUG="inittrace=1" #Print debug information about each package init and memory allocation
/=+===============================+=\
/ : : \
)==: CONTEXT :==(
\ :_______________________________: /
\=+===============================+=/
context.Context #INTERFACE
#Used to allow several goroutines to be terminated together (including cancellation|timeout)
#By convention, passed around as first argument between functions.
CONTEXT.Done()->(<-STRUCT_CHAN) #CHAN meant to await termination
# - closed on termination
# - meant to be used in select statement
# select { case <-CONTEXT.Done(): return CONTEXT.Err() }
#CHAN can be nil if can never cancel
CONTEXT.Deadline()->TIME,BOOL #Returns timeout's TIME
#BOOL is false is no timeout
CONTEXT.Err()->ERROR|nil #Termination ERROR
CONTEXT.Value(KEY)->VAL|nil #Arbitratry value associated with CONTEXT
#KEY should be package-specific to prevent collisions
# - should not be STR
# - is often an empty struct{}
context.Background()->CONTEXT #CONTEXT with no value and never cancelled|timed out.
#Intent is to use as top-level CONTEXT
context.TODO()->CONTEXT #Same except intention is to use when do not know yet which CONTEXT to use
#Prefered instead of using a nil CONTEXT
context.WithCancel(CONTEXT) #Create a CONTEXT's child:
->CANCEL_CONTEXT,CANCEL_FUNC # - inherits CONTEXT.Value()
#When CANCEL_FUNC() is called:
# - CANCEL_CONTEXT.Done()'s CHAN is closed
# - CANCEL_CONTEXT.Err()'s ERROR is set
# - cancels any child CONTEXT
# - does not cancel parent
#Should call CANCEL_FUNC() on successful termination too
# - usually with defer
#If CONTEXT already cancelled, cancel CANCEL_CONTEXT with it right away
context.CancelFunc #CANCEL_FUNC's type
context.Canceled #CANCEL_CONTEXT.Err()'s ERROR
CANCEL_CONTEXT.Context #Parent CONTEXT
context.WithDeadline
(CONTEXT, TIME)
->CONTEXT2,CANCEL_FUNC #Like context.WithCancel() but automatically calls CANCEL_FUNC() at TIME
context.WithTimeout
(CONTEXT, TIME_DURATION)
->CONTEXT2,CANCEL_FUNC #Same with TIME_DURATION
context.DeadlineExceeded #ERROR type for timeouts
DEADLINE_EXCEEDED.Error()->STR #Always "context deadline exceeded"
DEADLINE_EXCEEDED.Timeout()->true #
DEADLINE_EXCEEDED.
Temporary()->true #
context.WithValue
(CONTEXT, KEY, VAL)->CONTEXT2 #Create a CONTEXT's child with a specific Value()
/=+===============================+=\
/ : : \
)==: BREAKPOINTS :==(
\ :_______________________________: /
\=+===============================+=/
runtime.Breakpoint() #Sets a hardware breakpoint
#On x64, this will emit a SIGTRAP
#Must be done withing a debuffer that can handle those signals
/=+===============================+=\
/ : : \
)==: UNICODE :==(
\ :_______________________________: /
\=+===============================+=/
unicode.Version #Unicode version. '12.0.0'
unicode.MaxASCII #'\u007f'
unicode.MaxLatin1 #'\u00ff'
unicode.MaxRune #'\U0010ffff'
unicode.ReplacementChar #'\ufffd'
unicode.RangeTable #STRUCT. List of Unicode codepoints
RANGE_TABLE.R16 #[]RANGE16
RANGE_TABLE.R32 #[]RANGE32
RANGE_TABLE.LatinOffset #INT. Number of entries in R16 <= MaxLatin1
unicode.Is(*RANGE_TABLE, RUNE)->BOOL
unicode.In(RUNE, ...*RANGE_TABLE)->BOOL
unicode.IsOneOf([]*RANGE_TABLE, RUNE)->BOOL
unicode.IsControl(RUNE)->BOOL
unicode.IsDigit(RUNE)->BOOL
unicode.IsGraphic(RUNE)->BOOL
unicode.IsLetter(RUNE)->BOOL
unicode.IsLower(RUNE)->BOOL
unicode.IsMark(RUNE)->BOOL
unicode.IsNumber(RUNE)->BOOL
unicode.IsPrint(RUNE)->BOOL
unicode.IsPunct(RUNE)->BOOL
unicode.IsSpace(RUNE)->BOOL
unicode.IsSymbol(RUNE)->BOOL
unicode.IsTitle(RUNE)->BOOL
unicode.IsUpper(RUNE)->BOOL
unicode.To(INT, RUNE)->RUNE2
unicode.ToLower(RUNE)->RUNE2
unicode.ToTitle(RUNE)->RUNE2
unicode.ToUpper(RUNE)->RUNE2
unicode.SimpleFold(RUNE)->RUNE2
/=+===============================+=\
/ : : \
)==: STRINGS :==(
\ :_______________________________: /
\=+===============================+=/
strings.Compare(STR, STR2)->INT
strings.Contains(STR, STR2)->BOOL
strings.ContainsAny(STR, STR2)->BOOL
strings.ContainsRune(STR, RUNE)->BOOL
strings.Count(STR, STR2)->INT
strings.EqualFold(STR, STR2)->BOOL
strings.Fields(STR)->[]STR2
strings.FieldsFunc(STR, FUNC(RUNE)->BOOL)->[]STR2
strings.HasPrefix(STR, STR2)->BOOL
strings.HasSuffix(STR, STR2)->BOOL
strings.Index(STR, STR2)->INT
strings.IndexAny(STR, STR2)->INT
strings.IndexByte(STR, BYTE)->INT
strings.IndexFunc(STR, FUNC(RUNE)->BOOL)->INT
strings.IndexRune(STR, RUNE)->INT
strings.Join([]STR, STR2)->STR3
strings.LastIndex(STR, STR2)->INT
strings.LastIndexAny(STR, STR2)->INT
strings.LastIndexByte(STR, BYTE)->INT
strings.LastIndexFunc(STR, FUNC(RUNE)->BOOL)->INT
strings.Map(FUNC(RUNE)->RUNE2, STR)->STR2
strings.Repeat(STR, INT)->STR2
strings.Replace(STR, STR2, STR3, INT)->STR4
strings.ReplaceAll(STR, STR2, STR3)->STR4
strings.Split(STR, STR2)->[]STR3
strings.SplitAfter(STR, STR2)->[]STR3
strings.SplitAfterN(STR, STR2, INT)->[]STR3
strings.SplitN(STR, STR2, INT)->[]STR3
strings.Title(STR)->STR2
strings.ToLower(STR)->STR2
strings.ToTitle(STR)->STR2
strings.ToUpper(STR)->STR2
strings.ToLowerSpecial(unicode.SPECIALCASE, STR)->STR2
strings.ToTitleSpecial(unicode.SPECIALCASE, STR)->STR2
strings.ToUpperSpecial(unicode.SPECIALCASE, STR)->STR2
strings.ToValidUTF8(STR, STR2)->STR3
strings.Trim(STR, STR2)->STR3
strings.TrimFunc(STR, FUNC(RUNE)->BOOL)->STR2
strings.TrimLeft(STR, STR2)->STR3
strings.TrimLeftFunc(STR, FUNC(RUNE)->BOOL)->STR2
strings.TrimPrefix(STR, STR2)->STR3
strings.TrimRight(STR, STR2)->STR3
strings.TrimRightFunc(STR, FUNC(RUNE)->BOOL)->STR2
strings.TrimSpace(STR)->STR2
strings.TrimSuffix(STR, STR2)->STR3
/=+===============================+=\
/ : : \
)==: TEMPLATE :==(
\ :_______________________________: /
\=+===============================+=/
import "text/template" #Input is UTF-8 string + struct OBJ
#Is a string, which can contain {{...}} markers, which are substituted
#Can pipe with |
TEMPLATE #Anything in-between {{...}}
#Often used as -f CLI flag of commands exposing a -json CLI flag for output
{{VAL}} #STR, CHAR, BOOL, NUM, nil
{{.}} #OBJ
{{.VARR}} #OBJ.VARR
{{$VAR[.VARR]}} #Uses variable
{{.FUNC [...]}} #OBJ.FUNC(...)
{{FUNC [...]}} #FUNC(...)
{{/* COMMENT */}} #
{{- ...}}
{{... -}} #Trim whitespaces on left|right of {{}}
{{if BOOL}} ...
[{{else [if BOOL]}} ...] {{end}} #
{{range OBJ|ARR}} ... #Iterates, changing current context OBJ
[{{else}} ...] {{end}} #Else is if no iteration
{{with OBJ}} ... [{{else}} ...] {{end}} #Changes context
#Else is if OBJ is nothing
{{define "TEMPLATE"}} ... {{end}} #Defines template
{{template "TEMPLATE" [OBJ]}} #Expands template (with OBJ set as context)
{{block "TEMPLATE" OBJ}}...{{end}}#Same as:
# {{define "TEMPLATE"}} ... {{end}}
# {{template "TEMPLATE" [OBJ]}}
{{... (VAL) ...}} #Go subexpression