Stowage/go
2
0
Fork 0
mirror of https://github.com/golang/go.git synced 2025-12-08 06:10:04 +00:00
Code Issues Projects Releases Packages Wiki Activity

path/filepath: reword documentation for Rel

Browse source 
The existing func Rel's API documentation was presented in a rather
dense way without a lot of organization that oriented around topical
flow, so the documentation has been cleaned up to present the
function's behavior more clearly and concisely.

Fixes #75893

Change-Id: I6c8f6ef508250397be9d0127a15508e7335f18c4
Reviewed-on: https://go-review.googlesource.com/c/go/+/712440
Reviewed-by: David Chase <drchase@google.com>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
TryBot-Bypass: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
This commit is contained in:
Matt T. Proud 2025-10-16 19:14:45 +02:00 • committed by Gopher Robot
parent 39fd61ddb0
commit 6c3d0d259f
1 changed files with 17 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

33
src/path/filepath/path.go
View file

@ -173,19 +173,20 @@ func unixAbs(path string) (string, error) {
return Join(wd, path), nil
}
// Rel returns a relative path that is lexically equivalent to targpath when
// joined to basepath with an intervening separator. That is,
// [Join](basepath, Rel(basepath, targpath)) is equivalent to targpath itself.
// On success, the returned path will always be relative to basepath,
// even if basepath and targpath share no elements.
// An error is returned if targpath can't be made relative to basepath or if
// knowing the current working directory would be necessary to compute it.
// Rel calls [Clean] on the result.
func Rel(basepath, targpath string) (string, error) {
baseVol := VolumeName(basepath)
targVol := VolumeName(targpath)
base := Clean(basepath)
targ := Clean(targpath)
// Rel returns a relative path that is lexically equivalent to targPath when
// joined to basePath with an intervening separator. That is,
// [Join](basePath, Rel(basePath, targPath)) is equivalent to targPath itself.
//
// The returned path will always be relative to basePath, even if basePath and
// targPath share no elements. Rel calls [Clean] on the result.
//
// An error is returned if targPath can't be made relative to basePath
// or if knowing the current working directory would be necessary to compute it.
func Rel(basePath, targPath string) (string, error) {
baseVol := VolumeName(basePath)
targVol := VolumeName(targPath)
base := Clean(basePath)
targ := Clean(targPath)
if sameWord(targ, base) {
return ".", nil
}
@ -194,7 +195,7 @@ func Rel(basepath, targpath string) (string, error) {
if base == "." {
base = ""
} else if base == "" && filepathlite.VolumeNameLen(baseVol) > 2 /* isUNC */ {
// Treat any targetpath matching `\\host\share` basepath as absolute path.
// Treat any targetpath matching `\\host\share` basePath as absolute path.
base = string(Separator)
}
@ -202,7 +203,7 @@ func Rel(basepath, targpath string) (string, error) {
baseSlashed := len(base) > 0 && base[0] == Separator
targSlashed := len(targ) > 0 && targ[0] == Separator
if baseSlashed != targSlashed || !sameWord(baseVol, targVol) {
return "", errors.New("Rel: can't make " + targpath + " relative to " + basepath)
return "", errors.New("Rel: can't make " + targPath + " relative to " + basePath)
}
// Position base[b0:bi] and targ[t0:ti] at the first differing elements.
bl := len(base)
@ -228,7 +229,7 @@ func Rel(basepath, targpath string) (string, error) {
t0 = ti
}
if base[b0:bi] == ".." {
return "", errors.New("Rel: can't make " + targpath + " relative to " + basepath)
return "", errors.New("Rel: can't make " + targPath + " relative to " + basePath)
}
if b0 != bl {
// Base elements left. Must go up before going down.