Documentation
¶
Overview ¶
Package filesize converts a number of bytes into a human readable string, a faithful port of the npm package "filesize".
Reach for this package whenever a raw byte count needs to be shown to a person: file managers, upload progress, download sizes, disk usage, and log output all read better as "1.34 kB" than as "1337". FileSize covers the common case with sensible defaults, while FileSizeOpts exposes the knobs needed to match a particular convention.
The rendering works by choosing an exponent e such that the value falls in the range [1, base) when divided by base^e, then formatting that quotient. The base is 1000 for SI/decimal units and 1024 for binary units. Because the exponent is first estimated with a floating-point logarithm, the code then nudges it up or down against exact powers of the divisor to correct for rounding error at the unit boundaries, guaranteeing that a value like exactly 1000 renders as "1 kB" rather than "1000 B".
Three unit families are supported through the Standard option: "si" gives the decimal units B, kB, MB, GB, ...; "iec" gives the binary units B, KiB, MiB, GiB, ...; and "jedec" gives the hybrid B, KB, MB, GB, ... with 1024-based magnitudes but SI-style spelling. When Standard is empty it is derived from Base, so base 2 defaults to "iec" and base 10 defaults to "si". The number of fractional digits is controlled by Round (default 2), and trailing zeros together with a dangling decimal point are stripped, so "1.50" becomes "1.5" and "1.00" becomes "1".
Edge cases follow the Node original closely. A value of zero always renders as "0 B" regardless of base or standard. Negative inputs are formatted by their magnitude with a leading "-", e.g. "-1.34 kB". Values large enough to exceed the last known unit (YB or YiB) are clamped to that final unit rather than overflowing the table. The parity gap is that this port returns only the formatted string: the npm library's ability to return an array or a rich object, to force a fixed exponent, or to customize the symbol table and separators is intentionally omitted in favour of a single string result.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FileSize ¶
FileSize converts a number of bytes into a human readable string using the default options (base 10, two decimals). For example FileSize(1337) returns "1.34 kB".
Example ¶
ExampleFileSize renders a raw byte count with the default options, which use base 10 (SI) units and two fractional digits. The value 1337 falls between one and two kilobytes, so it is divided by 1000 and shown in kB. The quotient 1.337 is rounded to two decimals, yielding "1.34 kB". This is the convenient entry point when the defaults are acceptable and no unit family override is needed. The unit label is separated from the number by a single space.
package main
import (
"fmt"
"github.com/malcolmston/express/filesize"
)
func main() {
fmt.Println(filesize.FileSize(1337))
}
Output: 1.34 kB
Example (RoundValues) ¶
ExampleFileSize_roundValues shows how trailing zeros are stripped. Exactly one thousand bytes divides evenly into one kilobyte, so instead of "1.00 kB" the result is the cleaner "1 kB". A value of 1500 divides to 1.5, and the dangling zero in "1.50" is removed to give "1.5 kB". Zero is a special case that always renders as "0 B". Negative inputs are formatted by magnitude with a leading minus sign.
package main
import (
"fmt"
"github.com/malcolmston/express/filesize"
)
func main() {
fmt.Println(filesize.FileSize(1000))
fmt.Println(filesize.FileSize(1500))
fmt.Println(filesize.FileSize(0))
fmt.Println(filesize.FileSize(-1337))
}
Output: 1 kB 1.5 kB 0 B -1.34 kB
func FileSizeOpts ¶
FileSizeOpts converts a number of bytes into a human readable string honouring the supplied Options.
Example ¶
ExampleFileSizeOpts demonstrates overriding the defaults through Options. Setting Base to 2 switches the divisor to 1024 and, since Standard is left empty, derives the IEC unit family (KiB, MiB, ...). The same 1337 bytes is now just over one kibibyte, rendering as "1.31 KiB". The jedec standard also uses the 1024 divisor but spells the units in the SI style (KB, MB, ...), so 1536 bytes becomes "1.5 KB". This is the entry point to use when a specific convention must be matched.
package main
import (
"fmt"
"github.com/malcolmston/express/filesize"
)
func main() {
fmt.Println(filesize.FileSizeOpts(1337, filesize.Options{Base: 2}))
fmt.Println(filesize.FileSizeOpts(1536, filesize.Options{Base: 2, Standard: "jedec"}))
}
Output: 1.31 KiB 1.5 KB
Example (Round) ¶
ExampleFileSizeOpts_round controls the number of fractional digits with the Round option, which points at an int so that zero is distinguishable from unset. A Round of 0 truncates 1337 bytes to a whole "1 kB". A Round of 3 keeps three decimals, exposing the full "1.337 kB". Trailing-zero stripping still applies after rounding, so a value that lands on a round number loses its decimals regardless of the requested precision. This makes Round an upper bound on the digits shown rather than a fixed width.
package main
import (
"fmt"
"github.com/malcolmston/express/filesize"
)
func main() {
zero := 0
three := 3
fmt.Println(filesize.FileSizeOpts(1337, filesize.Options{Round: &zero}))
fmt.Println(filesize.FileSizeOpts(1337, filesize.Options{Round: &three}))
}
Output: 1 kB 1.337 kB
Types ¶
type Options ¶
type Options struct {
// Base is the numeric base: 10 (divide by 1000) or 2 (divide by 1024).
// Zero means the default of 10.
Base int
// Round is the number of decimal places to keep. When nil the default of
// 2 is used.
Round *int
// Standard selects the unit family: "si" (kB), "iec" (KiB) or "jedec"
// (KB). When empty it is derived from Base: base 2 uses "iec" and base 10
// uses "si".
Standard string
}
Options configures how a byte count is rendered.
Source Files