Skip to content

Commit eb8d3f4

Browse files
docs: mention String() can return different values (#820)
1 parent 9268756 commit eb8d3f4

2 files changed

Lines changed: 16 additions & 6 deletions

File tree

‎mime.go‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,14 @@ type MIME struct {
2323
}
2424

2525
// String returns the string representation of the MIME type, e.g., "application/zip".
26+
// String return values can change between releases, for example, when [IANA]
27+
// assigns a new media type. Use [MIME.Is] to avoid breaking changes.
28+
//
29+
// mtype := mimetype.Detect(zipFile)
30+
// if mtype.String() == "application/zip" { /* Plain string comparison is brittle. */ }
31+
// if mtype.Is("application/zip") { /* Will continue to work between releases */ }
32+
//
33+
// [IANA]: https://www.iana.org/assignments/media-types/media-types.xhtml
2634
func (m *MIME) String() string {
2735
return m.mime
2836
}
@@ -45,10 +53,12 @@ func (m *MIME) Parent() *MIME {
4553
return m.parent
4654
}
4755

48-
// Is checks whether this MIME type, or any of its aliases, is equal to the
56+
// Is checks whether this MIME type, or any of its [aliases], is equal to the
4957
// expected MIME type. MIME type equality test is done on the "type/subtype"
5058
// section, ignores any optional MIME parameters, ignores any leading and
5159
// trailing whitespace, and is case insensitive.
60+
//
61+
// [aliases]: https://github.com/gabriel-vasile/mimetype/blob/master/supported_mimes.md
5262
func (m *MIME) Is(expectedMIME string) bool {
5363
// Parsing is needed because some detected MIME types contain parameters
5464
// that need to be stripped for the comparison.

‎mimetype.go‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// Package mimetype uses magic number signatures to detect the MIME type of a file.
22
//
3-
// File formats are stored in a hierarchy with application/octet-stream at its root.
3+
// File formats are stored in a hierarchy with "application/octet-stream" at its root.
44
// For example, the hierarchy for HTML format is application/octet-stream ->
55
// text/plain -> text/html.
66
package mimetype
@@ -19,7 +19,7 @@ var readLimit uint32 = defaultLimit
1919

2020
// Detect returns the MIME type found from the provided byte slice.
2121
//
22-
// The result is always a valid MIME type, with application/octet-stream
22+
// The result is always a valid MIME type, with "application/octet-stream"
2323
// returned when identification failed.
2424
func Detect(in []byte) *MIME {
2525
// Using atomic because readLimit can be written at the same time in other goroutine.
@@ -34,7 +34,7 @@ func Detect(in []byte) *MIME {
3434

3535
// DetectReader returns the MIME type of the provided reader.
3636
//
37-
// The result is always a valid MIME type, with application/octet-stream
37+
// The result is always a valid MIME type, with "application/octet-stream"
3838
// returned when identification failed with or without an error.
3939
// Any error returned is related to the reading from the input reader.
4040
//
@@ -72,7 +72,7 @@ func DetectReader(r io.Reader) (*MIME, error) {
7272

7373
// DetectFile returns the MIME type of the provided file.
7474
//
75-
// The result is always a valid MIME type, with application/octet-stream
75+
// The result is always a valid MIME type, with "application/octet-stream"
7676
// returned when identification failed with or without an error.
7777
// Any error returned is related to the opening and reading from the input file.
7878
func DetectFile(path string) (*MIME, error) {
@@ -112,7 +112,7 @@ func SetLimit(limit uint32) {
112112
}
113113

114114
// Extend adds detection for other file formats.
115-
// It is equivalent to calling Extend() on the root MIME type "application/octet-stream".
115+
// It is equivalent to calling [MIME.Extend] on the root MIME type "application/octet-stream".
116116
func Extend(detector func(raw []byte, limit uint32) bool, mime, extension string, aliases ...string) {
117117
root.Extend(detector, mime, extension, aliases...)
118118
}

0 commit comments

Comments
 (0)