Documentation
¶
Overview ¶
Package bytes provides byte-oriented helpers used across go-service.
Most identifiers in this package are thin wrappers or aliases around the standard library `bytes` package. They exist to:
- provide a consistent import path within go-service, and
- centralize a small set of byte/string conversion utilities.
Aliases and wrappers ¶
`Buffer` is an alias for `bytes.Buffer`, and constructors like `NewBuffer`, `NewBufferString`, and `NewReader` delegate directly to the standard library.
Zero-copy conversions ¶
This package also exposes `String`, which converts a `[]byte` to a `string` without allocating. This is an advanced, performance-oriented helper with important safety constraints; see `String` for details.
Human-readable sizes ¶
`Size` is a named byte-count type for typed configuration surfaces. `String` and `ParseSize` use human-readable decimal size strings such as `64B`, `2MB`, and `4GB`.
Text and JSON marshaling emit exact raw byte counts with a `B` suffix, such as `4000000B`. Text and JSON unmarshaling accept the same decimal size inputs as `ParseSize`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Clone ¶ added in v2.240.0
Clone returns a copy of b.
This is a thin wrapper around bytes.Clone. Unlike helpers that may return subslices, Clone always allocates a new slice (unless b is nil, in which case it returns nil).
func NewBuffer ¶
NewBuffer returns a new Buffer initialized with buf's contents.
This is a thin wrapper around bytes.NewBuffer. The returned buffer uses buf as its initial contents; subsequent writes may grow the buffer.
func NewBufferString ¶
NewBufferString returns a new Buffer initialized with the contents of s.
This is a thin wrapper around bytes.NewBufferString.
func NewReader ¶
NewReader returns a new bytes.Reader reading from b.
This is a thin wrapper around bytes.NewReader. The returned reader reads from b without copying.
func String ¶
String converts b to a string without copying.
Safety and lifetime ¶
The returned string aliases the memory backing b. That means:
- You MUST NOT modify the contents of b after calling String(b).
- The returned string is only valid while b remains alive (reachable) and its backing array is not reused.
Violating these constraints can lead to surprising behavior, data races, or memory safety issues. Use this helper only when you control the lifecycle of b and need to avoid an allocation. If you need an owning copy, use `string(b)` instead.
Types ¶
type Buffer ¶
Buffer is an alias for bytes.Buffer.
It is provided so go-service code can depend on a consistent import path while still using the standard library implementation.
type Size ¶ added in v2.334.0
type Size int64
Size is the go-service decimal byte-size type used across the repository.
It is a named type over int64 so it can expose config-friendly text and JSON marshaling helpers while remaining easy to convert at API boundaries.
Size uses the decimal units understood by `github.com/docker/go-units`, such as `B`, `kB`, `MB`, `GB`, and `TB`.
Formatting and parsing intentionally follow go-units compatibility behavior. They are not a strict inverse for exabyte-scale values because go-units can format larger suffixes than FromHumanSize parses.
DefaultSize is the shared default size used by config surfaces that need a conservative byte limit.
Its value is 4 megabytes.
MaxConfigSize is the largest byte size accepted by configuration surfaces.
Configured sizes protect in-memory buffering paths such as cache values, HTTP request bodies, HTTP client response bodies, and gRPC messages. Keep this comfortably below integer and allocator edge cases while still allowing unusually large service payloads.
PB is the decimal petabyte size constant: 1,000,000,000,000,000 bytes.
func MustParseSize ¶ added in v2.334.0
MustParseSize parses s as a human-readable decimal size string and panics if parsing fails.
This helper is intended for strict startup/configuration paths where an invalid size is considered a fatal configuration/programming error. It panics by calling runtime.Must on the parse error.
If you need recoverable error handling, use ParseSize instead.
func ParseSize ¶ added in v2.334.0
ParseSize parses a human-readable decimal size string.
The input uses the suffix compatibility rules from `github.com/docker/go-units.FromHumanSize`. Parsed values are decimal sizes, so accepted suffix spellings such as `MB` and `MiB` both use the decimal `M` multiplier.
func (Size) MarshalJSON ¶ added in v2.334.0
MarshalJSON encodes s as a quoted exact raw byte count, such as `"4000000B"`.
func (Size) MarshalText ¶ added in v2.334.0
MarshalText encodes s as an exact raw byte count with a `B` suffix.
func (Size) String ¶ added in v2.334.0
String returns s in the human-readable decimal size format used by this package, such as `64B` or `4MB`.
func (*Size) UnmarshalJSON ¶ added in v2.334.0
UnmarshalJSON decodes a quoted decimal size string into s.
Non-string JSON values are rejected by the underlying JSON decoder before the size parser runs.
Source Files