Skip to content

Add code examples for is_equivalent.#104767

Open
bruvzg wants to merge 1 commit intogodotengine:masterfrom
bruvzg:is_eq_docs
Open

Add code examples for is_equivalent.#104767
bruvzg wants to merge 1 commit intogodotengine:masterfrom
bruvzg:is_eq_docs

Conversation

@bruvzg
Copy link
Copy Markdown
Member

@bruvzg bruvzg commented Mar 29, 2025

Add sample code for #104597

@bruvzg bruvzg added this to the 4.5 milestone Mar 29, 2025
@bruvzg bruvzg requested a review from a team as a code owner March 29, 2025 15:31
Comment thread doc/classes/DirAccess.xml Outdated
Comment thread doc/classes/DirAccess.xml Outdated
Comment thread doc/classes/DirAccess.xml Outdated
Copy link
Copy Markdown
Member

@Mickeon Mickeon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know you're trying really hard to save vertical space here but this code snippet will be difficult to read in both the online and built-in class reference.
Even when proposing changes it's difficult to navigate for the sheer length.

Comment thread doc/classes/DirAccess.xml Outdated
Comment on lines +259 to +282
var dir = DirAccess.open("/")

print(dir.is_equivalent("/sbin/md5sum", "/sBin/MD5Sum")) # Prints `true` on a case-insensitive filesystem, `false` otherwise.

dir.create_link(ProjectSettings.globalize_path("res://icon.svg"), ProjectSettings.globalize_path("res://icon2.svg"))
print(dir.is_equivalent(ProjectSettings.globalize_path("res://icon.svg"), ProjectSettings.globalize_path("res://icon2.svg"))) # Prints `true`, symbolic link.
dir.remove(ProjectSettings.globalize_path("res://icon2.svg"))

dir.copy(ProjectSettings.globalize_path("res://icon.svg"), ProjectSettings.globalize_path("res://icon2.svg"))
print(dir.is_equivalent(ProjectSettings.globalize_path("res://icon.svg"), ProjectSettings.globalize_path("res://icon2.svg"))) # Prints `false`, identical file copy.
dir.remove(ProjectSettings.globalize_path("res://icon2.svg"))
[/gdscript]
[csharp]
using var dir = DirAccess.Open("/");

GD.Print(dir.IsEquivalent("/sbin/md5sum", "/sBin/MD5Sum")); // Prints `true` on a case-insensitive filesystem, `false` otherwise.

dir.CreateLink(ProjectSettings.GlobalizePath("res://icon.svg"), ProjectSettings.GlobalizePath("res://icon2.svg"));
GD.Print(dir.IsEquivalent(ProjectSettings.GlobalizePath("res://icon.svg"), ProjectSettings.GlobalizePath("res://icon2.svg"))); // Prints `true`, symbolic link.
dir.Remove(ProjectSettings.GlobalizePath("res://icon2.svg"));

dir.Copy(ProjectSettings.GlobalizePath("res://icon.svg"), ProjectSettings.GlobalizePath("res://icon2.svg"));
GD.Print(dir.IsEquivalent(ProjectSettings.GlobalizePath("res://icon.svg"), ProjectSettings.GlobalizePath("res://icon2.svg"))); // Prints `false`, identical file copy.
dir.Remove(ProjectSettings.GlobalizePath("res://icon2.svg"));
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The following changes are done assuming I understand these methods right. Something may be wrong but the idea is here

Also, quoting myself:

Beware of C# differences. GD.Print() outputs "True" and "False", trims the trailing .0, and outputs enum constants' names instead of their value.

Suggested change
var dir = DirAccess.open("/")
print(dir.is_equivalent("/sbin/md5sum", "/sBin/MD5Sum")) # Prints `true` on a case-insensitive filesystem, `false` otherwise.
dir.create_link(ProjectSettings.globalize_path("res://icon.svg"), ProjectSettings.globalize_path("res://icon2.svg"))
print(dir.is_equivalent(ProjectSettings.globalize_path("res://icon.svg"), ProjectSettings.globalize_path("res://icon2.svg"))) # Prints `true`, symbolic link.
dir.remove(ProjectSettings.globalize_path("res://icon2.svg"))
dir.copy(ProjectSettings.globalize_path("res://icon.svg"), ProjectSettings.globalize_path("res://icon2.svg"))
print(dir.is_equivalent(ProjectSettings.globalize_path("res://icon.svg"), ProjectSettings.globalize_path("res://icon2.svg"))) # Prints `false`, identical file copy.
dir.remove(ProjectSettings.globalize_path("res://icon2.svg"))
[/gdscript]
[csharp]
using var dir = DirAccess.Open("/");
GD.Print(dir.IsEquivalent("/sbin/md5sum", "/sBin/MD5Sum")); // Prints `true` on a case-insensitive filesystem, `false` otherwise.
dir.CreateLink(ProjectSettings.GlobalizePath("res://icon.svg"), ProjectSettings.GlobalizePath("res://icon2.svg"));
GD.Print(dir.IsEquivalent(ProjectSettings.GlobalizePath("res://icon.svg"), ProjectSettings.GlobalizePath("res://icon2.svg"))); // Prints `true`, symbolic link.
dir.Remove(ProjectSettings.GlobalizePath("res://icon2.svg"));
dir.Copy(ProjectSettings.GlobalizePath("res://icon.svg"), ProjectSettings.GlobalizePath("res://icon2.svg"));
GD.Print(dir.IsEquivalent(ProjectSettings.GlobalizePath("res://icon.svg"), ProjectSettings.GlobalizePath("res://icon2.svg"))); // Prints `false`, identical file copy.
dir.Remove(ProjectSettings.GlobalizePath("res://icon2.svg"));
var dir = DirAccess.open("/")
# Prints "true" on a case-insensitive filesystem, "false" otherwise.
print(dir.is_equivalent("/sbin/md5sum", "/sBin/MD5Sum"))
var icon_1_path = ProjectSettings.globalize_path("res://icon.svg")
var icon_2_path = ProjectSettings.globalize_path("res://icon2.svg")
dir.create_link(icon_1_path, icon_2_path)
# Prints `true`, icon_2_path points to a symbolic link.
print(dir.is_equivalent(icon_1_path, icon_2_path))
dir.remove(icon_2_path)
dir.copy(icon_1_path, icon_2_path))
# Prints `false`, icon_2_path points to an identical copy.
print(dir.is_equivalent(icon_1_path, icon_2_path))
dir.remove(icon_2_path)
[/gdscript]
[csharp]
using var dir = DirAccess.Open("/");
// Prints "True" on a case-insensitive filesystem, "False" otherwise.
GD.Print(dir.IsEquivalent("/sbin/md5sum", "/sBin/MD5Sum"));
var icon1Path = ProjectSettings.GlobalizePath("res://icon.svg")
var icon2Path = ProjectSettings.GlobalizePath("res://icon2.svg")
dir.CreateLink(icon1Path, icon2Path);
// Prints `True`, symbolic link.
GD.Print(dir.IsEquivalent(icon1Path, icon2Path));
dir.Remove(icon2Path);
dir.Copy(icon1Path, icon2Path);
// Prints `False`, identical file copy.
GD.Print(dir.IsEquivalent(icon1Path, icon2Path));
dir.Remove(icon2Path);

We could actually go a step further and rename the path variables to be less generic, in reference to what they're used for here (symlink vs copy)

Comment thread doc/classes/DirAccess.xml Outdated
@@ -253,7 +253,35 @@
<param index="0" name="path_a" type="String" />
<param index="1" name="path_b" type="String" />
<description>
Returns [code]true[/code] if paths [param path_a] and [param path_b] resolve to the same file system object. Returns [code]false[/code] otherwise, even if the files are bit-for-bit identical (e.g., identical copies of the file that are not symbolic links).
Returns [code]true[/code] if paths [param path_a] and [param path_b] resolve to the same file system object (taking into account case sensitivity, relative paths, symbolic links, and hard links). Returns [code]false[/code] otherwise, even if the files are bit-for-bit identical (i.e. identical copies of a file that are not symbolic links).
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One time it's i.e., another time it's e.g.. I think we should begin not using both outright.

Suggested change
Returns [code]true[/code] if paths [param path_a] and [param path_b] resolve to the same file system object (taking into account case sensitivity, relative paths, symbolic links, and hard links). Returns [code]false[/code] otherwise, even if the files are bit-for-bit identical (i.e. identical copies of a file that are not symbolic links).
Returns [code]true[/code] if paths [param path_a] and [param path_b] resolve to the same file system object (taking into account case sensitivity, relative paths, symbolic links, and hard links). Returns [code]false[/code] otherwise, even if the files are exactly identical (copies of a file that are not symbolic links).

Comment thread doc/classes/DirAccess.xml
var icon_2_path = ProjectSettings.globalize_path("res://icon2.svg")

dir.create_link(icon_1_path, icon_2_path)
# Prints `true`, icon_2_path points to a symbolic link.
Copy link
Copy Markdown
Member

@Mickeon Mickeon Apr 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not going to highlight every occurrence of this but they should be surrounded by quotation marks. I guess it's my bad for not noticing sooner.

Suggested change
# Prints `true`, icon_2_path points to a symbolic link.
# Prints "true", icon_2_path points to a symbolic link.

@Repiteo Repiteo modified the milestones: 4.5, 4.x Sep 18, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants