doc: Clarify when to construct a StringName ahead of time
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.
This commit is contained in:
parent
6588a4a29a
commit
9cbc4026ee
|
@ -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]&"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]&"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.
|
||||
|
|
Loading…
Reference in New Issue