Skip to content

Commit

Permalink
doc: Clarify when to construct a StringName ahead of time
Browse files Browse the repository at this point in the history
Fix docs don't give justification for manual construction.

Clarify how to apply manual StringName construction as an
optimization and that "string intern" means "work at parse time".

There are several godot-demo-projects (including 3d/platformer) that
incorrectly use StringName literals (they use & literals instead of just
passing strings), so clearly this is confusing.

AThousandShips did a disassembly test to prove it automatically converts
constant strings to StringName for annotated functions:

  func do_test(_var: StringName, _var2: String):
  pass

  func test():
  do_test("abc", "def")

Yields:

  Disassembling do_test(_var, _var2)
   0: line 2:     pass
   2: == END ==

  Disassembling test()
   0: line 5:     do_test("abc", "def")
   2: call self.do_test(const(&"abc"), const("def"))
   10: assign stack(3) = false
   12: == END ==

It also happens with built-in functions such as those of Input.
  • Loading branch information
idbrii authored and akien-mga committed Feb 9, 2024
1 parent 6588a4a commit 9cbc402
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion doc/classes/StringName.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
</brief_description>
<description>
[StringName]s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). Two [StringName]s with the same value are the same object. Comparing them is extremely fast compared to regular [String]s.
You will usually just pass a [String] to methods expecting a [StringName] and it will be automatically converted, but you may occasionally want to construct a [StringName] ahead of time with the [StringName] constructor or, in GDScript, the literal syntax [code]&amp;"example"[/code].
You will usually pass a [String] to methods expecting a [StringName] and it will be automatically converted (often at compile time), but in rare cases you can construct a [StringName] ahead of time with the [StringName] constructor or, in GDScript, the literal syntax [code]&amp;"example"[/code]. Manually constructing a [StringName] allows you to control when the conversion from [String] occurs or to use the literal and prevent conversions entirely.
See also [NodePath], which is a similar concept specifically designed to store pre-parsed scene tree paths.
All of [String]'s methods are available in this class too. They convert the [StringName] into a string, and they also return a string. This is highly inefficient and should only be used if the string is desired.
[b]Note:[/b] In a boolean context, a [StringName] will evaluate to [code]false[/code] if it is empty ([code]StringName("")[/code]). Otherwise, a [StringName] will always evaluate to [code]true[/code]. The [code]not[/code] operator cannot be used. Instead, [method is_empty] should be used to check for empty [StringName]s.
Expand Down

0 comments on commit 9cbc402

Please sign in to comment.