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, constructors like NewBuffer, NewBufferString, and NewReader delegate directly to the standard library, and helpers like Clone and TrimSpace mirror standard library behavior through the go-service import path.
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. Size.String and ParseSize use human-readable decimal size strings such as `64B`, `2MB`, and `4GB`.
Parsing and unmarshaling only convert syntax to byte counts. Bounds such as MaxConfigSize are enforced by typed configuration fields and public APIs that explicitly opt into that cap.
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 ¶
This function uses unsafe to create a string view over b's backing storage. As a result:
- The returned string aliases the same memory as b.
- The contents of b must be treated as read-only after calling String(b).
- Do not retain the returned string beyond the lifetime of b or after b's backing array may be 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.
func TrimSpace ¶
TrimSpace returns a subslice of s with all leading and trailing white space removed.
This is a thin wrapper around bytes.TrimSpace. The returned slice may refer to the same underlying array as s.
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.
Parsing and unmarshaling Size values do not enforce MaxConfigSize by themselves. Configuration fields that require repository-owned bounds use validation such as the config package's `config_size` rule after parsing.
const ( // KB is the decimal kilobyte size constant: 1,000 bytes. KB Size = Size(units.KB) // MB is the decimal megabyte size constant: 1,000,000 bytes. MB Size = Size(units.MB) // GB is the decimal gigabyte size constant: 1,000,000,000 bytes. GB Size = Size(units.GB) // TB is the decimal terabyte size constant: 1,000,000,000,000 bytes. TB Size = Size(units.TB) // PB is the decimal petabyte size constant: 1,000,000,000,000,000 bytes. PB Size = Size(units.PB) )
const ( // DefaultSize is the shared default size used by config surfaces that need a conservative byte limit. // // Its value is 4 megabytes. DefaultSize Size = 4 * MB // MaxConfigSize is the shared upper bound for typed configuration fields that opt into // repository-owned byte-size validation. // // It is used by fields and public APIs that explicitly promise the repository cap, such as cache // value sizes and server receive sizes. Low-level option maps and callers that parse [Size] values // directly must apply their own bounds when they need one. MaxConfigSize Size = 256 * MB )
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.
ParseSize does not enforce MaxConfigSize; callers that apply parsed values to bounded buffers or typed configuration fields must validate the returned size for their own contract.
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 before the size parser runs.
Source Files