Singularity/Library/PackageCache/com.unity.burst@1.8.4/Documentation~/csharp-string-support.md

String support

Burst supports string usage in the following scenarios:

• Debug.Log
• Assigning a string to the FixedString structs that Unity.Collections provides, for example FixedString128.
• The System.Runtime.CompilerServices attributes [CallerLineNumber], [CallerMemberName], and [CallerFilePath] on arguments to Burst functions. However, you can only pass the strings directly to calls to Debug.Log.

A string can be either:

• A string literal. For example: "This is a string literal".
• An interpolated string using $"This is an integer {value} or using string.Format, where the string to format is also a string literal.

For example, Burst supports the following constructions:

• Logging with a string literal:

  Debug.Log("This a string literal");
  

• Logging using string interpolation:

  int value = 256;
  Debug.Log($"This is an integer value {value}"); 
  

  This is the same as using string.Format directly:

  int value = 256;
  Debug.Log(string.Format("This is an integer value {0}", value));
  

Supported Debug.Log methods

Burst supports the following Debug.Log methods:

• Debug.Log(object)
• Debug.LogWarning(object)
• Debug.LogError(object)

String interpolation support

String interpolation has the following restrictions:

• The string must be a string literal

• Burst supports the following string.Format methods:

  • string.Format(string, object)
  • string.Format(string, object, object)
  • string.Format(string, object, object, object)
  • string.Format(string, object[]). Use this for a string interpolation that contains more than three arguments, for example $"{arg1} {arg2} {arg3} {arg4} {arg5}". In this case, the object[] array needs to be a constant size and no arguments should involve control flows (for example, $"This is a {(cond ? arg1 : arg2)}").

• The string must only use value types

• The string must take only built-in type arguments:

  • char
  • boolean
  • byte / sbyte
  • double
  • float
  • short / ushort
  • int / uint
  • long / ulong

• Burst supports sll vector types (for example int2, float3), except half vector types. For example:

  var value = new float3(1.0f, 2.0f, 3.0f);
  // Logs "This value float3(1f, 2f, 3f)"
  Debug.Log($"This value `{value}`");
  

• Burst doesn't support ToString() of structs. It displays the full name of the struct instead.

For more information, see the .NET documentation on String interpolation and Standard numeric format strings.

Managed strings

You can pass a managed string literal or an interpolated string directly to Debug.Log, but you can't pass a string to a user method or to use them as fields in a struct. To pass around or store strings, use one of the FixedString structs in the Unity.Collections package:

int value = 256;
FixedString128 text = $"This is an integer value {value} used with FixedString128";
MyCustomLog(text);

// ...

// String can be passed as an argument to a method using a FixedString, 
// but not using directly a managed `string`:
public static void MyCustomLog(in FixedString128 log)
{
    Debug.Log(text);
}

Arguments and specifiers

Burst has limited support for string format arguments and specifiers:

int value = 256;

// Padding left: "This value `  256`
Debug.Log($"This value `{value,5}`");

// Padding right: "This value `256  `
Debug.Log($"This value `{value,-5}`");

// Hexadecimal uppercase: "This value `00FF`
Debug.Log($"This value `{value:X4}`");

// Hexadecimal lowercase: "This value `00ff`
Debug.Log($"This value `{value:x4}`");

// Decimal with leading-zero: "This value `0256`
Debug.Log($"This value `{value:D4}`");