【Gin-v1.9.0源码阅读】path.go

// Copyright 2013 Julien Schmidt. All rights reserved.
// Based on the path package, Copyright 2009 The Go Authors.
// Use of this source code is governed by a BSD-style license that can be found
// at https://github.com/julienschmidt/httprouter/blob/master/LICENSE.

package gin

// cleanPath is the URL version of path.Clean, it returns a canonical URL path
// for p, eliminating . and .. elements.
// cleanPath是路径的URL版本。Clean，它返回p的规范URL路径，消除。和元素
// The following rules are applied iteratively until no further processing can
// be done: 反复应用以下规则，直到无法进行进一步处理为止：
//  1. Replace multiple slashes with a single slash. 用一个斜杠替换多个斜杠。
//  2. Eliminate each . path name element (the current directory). 消除每一个。path name元素（当前目录）。
//  3. Eliminate each inner .. path name element (the parent directory)
//     along with the non-.. element that precedes it. 消除每个内部。。path name元素（父目录）以及非。。位于其前面的元素。
//  4. Eliminate .. elements that begin a rooted path:
//     that is, replace "/.." by "/" at the beginning of a path.
//
// 排除以根路径开头的元素：也就是说，将路径开头的“/..”替换为“/”。
// If the result of this process is an empty string, "/" is returned.
// 如果此过程的结果是一个空字符串，则返回“/”。
func cleanPath(p string) string {
	const stackBufSize = 128
	// Turn empty string into "/"
	if p == "" {
		return "/"
	}

	// Reasonably sized buffer on stack to avoid allocations in the common case.
	// If a larger buffer is required, it gets allocated dynamically.
	// 堆栈上的缓冲区大小合理，以避免在常见情况下进行分配。如果需要更大的缓冲区，则会动态分配。
	buf := make([]byte, 0, stackBufSize)

	n := len(p)

	// Invariants:
	//      reading from path; r is index of next byte to process.
	//      writing to buf; w is index of next byte to write.
	// 不变量：
	// 从路径读取；r是要处理的下一个字节的索引。
	// 写信给buf；w是要写入的下一个字节的索引。
	// path must start with '/'
	// 路径必须以“/”开头
	r := 1
	w := 1

	if p[0] != '/' {
		r = 0

		if n+1 > stackBufSize {
			buf = make([]byte, n+1)
		} else {
			buf = buf[:n+1]
		}
		buf[0] = '/'
	}

	trailing := n > 1 && p[n-1] == '/'

	// A bit more clunky without a 'lazybuf' like the path package, but the loop
	// gets completely inlined (bufApp calls).
	// 如果没有像路径包那样的“lazybuf”，会有点笨拙，但循环会完全内联（bufApp调用）。
	// loop has no expensive function calls (except 1x make)		// So in contrast to the path package this loop has no expensive function
	// calls (except make, if needed).
	// loop没有昂贵的函数调用（除了1x make）//因此，与路径包相比，该loop没有高昂的函数调用。

	for r < n {
		switch {
		case p[r] == '/':
			// empty path element, trailing slash is added after the end
			// 空的path元素，末尾添加尾部斜线
			r++

		case p[r] == '.' && r+1 == n:
			trailing = true
			r++

		case p[r] == '.' && p[r+1] == '/':
			// . element
			r += 2

		case p[r] == '.' && p[r+1] == '.' && (r+2 == n || p[r+2] == '/'):
			// .. element: remove to last /
			r += 3

			if w > 1 {
				// can backtrack
				w--

				if len(buf) == 0 {
					for w > 1 && p[w] != '/' {
						w--
					}
				} else {
					for w > 1 && buf[w] != '/' {
						w--
					}
				}
			}

		default:
			// Real path element. 实路径元素。
			// Add slash if needed 如果需要，添加斜线
			if w > 1 {
				bufApp(&buf, p, w, '/')
				w++
			}

			// Copy element 复制元素
			for r < n && p[r] != '/' {
				bufApp(&buf, p, w, p[r])
				w++
				r++
			}
		}
	}

	// Re-append trailing slash 重新追加尾部斜线
	if trailing && w > 1 {
		bufApp(&buf, p, w, '/')
		w++
	}

	// If the original string was not modified (or only shortened at the end),
	// return the respective substring of the original string.
	// Otherwise return a new string from the buffer.
	// 如果原始字符串未被修改（或仅在末尾缩短），则返回原始字符串的相应子字符串。否则，从缓冲区返回一个新字符串。
	if len(buf) == 0 {
		return p[:w]
	}
	return string(buf[:w])
}

// Internal helper to lazily create a buffer if necessary.
// Calls to this function get inlined.
// 内部帮助程序，以便在必要时惰性地创建缓冲区。对该函数的调用被内联。
func bufApp(buf *[]byte, s string, w int, c byte) {
	b := *buf
	if len(b) == 0 {
		// No modification of the original string so far.
		// If the next character is the same as in the original string, we do
		// not yet have to allocate a buffer.
		// 到目前为止，还没有修改原始字符串。如果下一个字符与原始字符串中的字符相同，我们还不需要分配缓冲区。
		if s[w] == c {
			return
		}

		// Otherwise use either the stack buffer, if it is large enough, or
		// allocate a new buffer on the heap, and copy all previous characters.
		// 否则，如果堆栈缓冲区足够大，请使用它，或者在堆上分配一个新的缓冲区，并复制所有以前的字符。
		length := len(s)
		if length > cap(b) {
			*buf = make([]byte, length)
		} else {
			*buf = (*buf)[:length]
		}
		b = *buf

		copy(b, s[:w])
	}
	b[w] = c
}