You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`"x:" + x + " y:" + y + " z:" + z` is converted to `String.Concat(new []{ "x:", x.ToString(), " y:", y.ToString(), " z:", z.ToString() })` by C# compiler. It has each `.ToString` allocation and params array allocation. `string.Format` calls `String.Format(string, object, object, object)` so each arguments causes int -> object boxing.
28
+
29
+
All `ZString` methods only allocate final string. Also, `ZString` has enabled to access inner buffer so if output target has stringless api, you can achieve completely zero allocation.
30
+
31
+
Getting Started
10
32
---
11
-
Check the [releases](https://github.com/Cysharp/ZString/releases) page, download `ZString.Unity.unitypackage`.
For Unity, check the [releases](https://github.com/Cysharp/ZString/releases) page, download `ZString.Unity.unitypackage`.
18
38
19
-
voidUpdate()
39
+
```csharp
40
+
asyncvoidExample(intx, inty, intz)
20
41
{
21
-
text.SetTextFormat("Damage: {0}", count++);
22
-
}
23
-
```
42
+
// same as x + y + z
43
+
_=ZString.Concat(x, y, z);
24
44
25
-
SetTextFormat is extension method of `TMP_Text`, there parameter is generics so can avoid boxing, and ZString writes to buffer directly without any ToString allocation. Finally inner buffer copy to `TextMeshPro` buffer so avoid all string allocations.
45
+
// also can use numeric format strings
46
+
_=ZString.Format("x:{0}, y:{1:000}, z:{2:P}",x, y, z);
| CreateStringBuilder(bool notNested) | Utf16ValueStringBuilder | Create the Utf16 string StringBuilder, when true uses thread-static buffer that is faster but must return immediately. |
90
+
| CreateUtf8StringBuilder() | Utf8ValueStringBuilder | Create the Utf8(`Span<byte>`) StringBuilder. |
91
+
| CreateUtf8StringBuilder(bool notNested) | Utf8ValueStringBuilder | Create the Utf8(`Span<byte>`) StringBuilder, when true uses thread-static buffer that is faster but must return immediately. |
92
+
| `Join(char|string, T[]/IE<T>)` | string | Concatenates the elements of an array, using the specified seperator between each element. |
93
+
|`Concat<T0,..,T15>(T0,..,T15)`| string | Concatenates the string representation of some specified values. |
94
+
|`Format<T0,..,T15>(string, T0,..,T15)`| string | Replaces one or more format items in a string with the string representation of some specified values. |
| AsSpan() |`ReadOnlySpan<char>`| Get the written buffer data. |
102
+
| AsMemory() |`ReadOnlyMemory<char>`| Get the written buffer data. |
103
+
| AsArraySegment() |`ArraySegment<char>`| Get the written buffer data. |
104
+
| Dispose() | void | Return the inner buffer to pool. |
105
+
|`Append<T>(T value)`| void | Appends the string representation of a specified value to this instance. |
106
+
|`Append<T>(T value, string format)`| void | Appends the string representation of a specified value to this instance with numeric format strings. |
107
+
|`AppendLine()`| void | Appends the default line terminator to the end of this instance. |
108
+
|`AppendLine<T>(T value)`| void | Appends the string representation of a specified value followed by the default line terminator to the end of this instance. |
109
+
|`AppendLine<T>(T value, string format)`| void | Appends the string representation of a specified value with numeric format strings followed by the default line terminator to the end of this instance. |
110
+
|`AppendFormat<T0,..,T15>(string, T0,..,T15)`| void | Appends the string returned by processing a composite format string, each format item is replaced by the string representation of arguments. |
111
+
|`TryCopyTo(Span<char>, out int)`| bool | Copy inner buffer to the destination span. |
112
+
| ToString() | string | Converts the value of this instance to a System.String. |
| AsSpan() |`ReadOnlySpan<char>`| Get the written buffer data. |
124
+
| AsMemory() |`ReadOnlyMemory<char>`| Get the written buffer data. |
125
+
| AsArraySegment() |`ArraySegment<char>`| Get the written buffer data. |
126
+
| Dispose() | void | Return the inner buffer to pool. |
127
+
|`Append<T>(T value)`| void | Appends the string representation of a specified value to this instance. |
128
+
|`Append<T>(T value, StandardFormat format)`| void | Appends the string representation of a specified value to this instance with numeric format strings. |
129
+
|`AppendLine()`| void | Appends the default line terminator to the end of this instance. |
130
+
|`AppendLine<T>(T value)`| void | Appends the string representation of a specified value followed by the default line terminator to the end of this instance. |
131
+
|`AppendLine<T>(T value, StandardFormat format)`| void | Appends the string representation of a specified value with numeric format strings followed by the default line terminator to the end of this instance. |
132
+
|`AppendFormat<T0,..,T15>(string, T0,..,T15)`| void | Appends the string returned by processing a composite format string, each format item is replaced by the string representation of arguments. |
133
+
|`TryCopyTo(Span<byte>, out int)`| bool | Copy inner buffer to the destination span. |
**static class TextMeshProExtensions**(Unity only)
142
+
143
+
| method | returns | description |
144
+
| -- | -- | -- |
145
+
| SetText(Utf16ValueStringBuilder) | void | Set inner buffer to text mesh pro directly to avoid string allocation. |
146
+
|`SetTextFormat<T0,..,T15>(string, T0,..,T15)`| void | Set formatted string without string allocation. |
147
+
148
+
Advanced Tips
149
+
---
150
+
`ZString.CreateStringBuilder(notNested:true)` is a special optimized parameter that uses `ThreadStatic` buffer instead of rent from `ArrayPool`. It is slightly faster but can not use in nested.
35
151
36
152
```csharp
37
-
using(varsb=ZString.CreateStringBuilder())
153
+
using(varsb=ZString.CreateStringBuilder(true))
38
154
{
39
155
sb.Append("foo");
40
-
sb.AppendLine(42);
41
-
sb.AppendFormat("{0} {1}", "bar", 123.456);
42
-
sb.AppendMany(1, "foo", 100, "bar");
43
156
44
-
Debug.Log(sb.ToString());
157
+
usingvarsb2=ZString.CreateStringBuilder(true); // NG, nested stringbuilder uses conflicted same buffer
In default, `SByte`, `Int16`, `Int32`, `Int64`, `Byte`, `UInt16`, `UInt32`, `UInt64`, `Single`, `Double`, `TimeSpan`, `DateTime`, `DateTimeOffset`, `Decimal`, `Guid`, `String`, `Char` are used there own formatter to avoid `.ToString()` allocation, write directly to buffer. If not exists there list type, used `.ToString()` and copy string data.
176
+
177
+
If you want to avoid to convert string in custom type, you can register your own formatter.
varstr=ZString.Format("foo {0} bar {1}", 42, 123.456);
68
-
```
196
+
`CreateStringBuilder` and `CreateUtf8StringBuilder` must use with `using`. Because their builder rent 64K buffer from `ArrayPool`. If not return buffer, allocate 64K buffer when string builder is created.
197
+
198
+
---
199
+
200
+
`Utf8ValueStringBuilder` and `Utf16ValueStringBuilder` implements `IBufferWriter` so you can pass serializer(such as `JsonSerializer` of `System.Text.Json`). But be careful to boxing copy, `ValueStringBuilder` is mutable struct. For example,
69
201
70
202
```csharp
71
-
// write to Utf8 directly
72
203
usingvarsb=ZString.CreateUtf8StringBuilder();
204
+
IBufferWriter<byte>boxed=sb;
205
+
varwriter=newUtf8JsonWriter(boxed);
206
+
JsonSerializer.Serialize(writer, ....);
73
207
74
-
sb.AppendLine("foo");
75
-
sb.AppendLine(42);
76
-
sb.AppendLine("bar");
77
-
sb.AppendLine(123.456);
78
-
79
-
awaitsb.CopyToAsync(stream);
208
+
usingvarunboxed= (Utf8ValueStringBuilder)boxed;
209
+
varstr=unboxed.ToString();
80
210
```
81
211
82
212
License
83
213
---
84
-
This library is under the MIT License.
214
+
This library is licensed under the the MIT License.
215
+
216
+
.NET Standard 2.0 and Unity version borrows [dotnet/runtime](https://github.com/dotnet/runtime) conversion methods, there exists under `ZString/Number` directory.
0 commit comments