Data Tokens

Data Tokensはデータを保持するためのものです。各トークンは単一の変数のみを格納します。Data TokensはData DictionariesおよびData Listsで使用されます。

Data Tokensには、以下のToken Typesを含めることができます。

• Null
• Boolean
• SByte
• Byte
• Short
• UShort
• Int
• UInt
• Long
• ULong
• Float
• Double
• String
• Data Lists（他のDataTokensを格納）
• Data Dictionaries（他のDataTokensを格納）
• Object Reference（ボクシングを介してanythingを格納可能ですが、シリアル化はできません）
• Data Errors（何が問題であったかを示す列挙型）

Properties

Functions

DataTokenの作成

UdonSharp

UdonSharpでは、DataTokenを「暗黙的」に作成できます。つまり、関数がDataTokenを要求する際に、new DataToken(value)と記述する必要はありません。値を直接渡すだけで、自動的にDataTokenが作成されます。

// You could do this
DataToken _explicitFloat = new DataToken(5.3f);
DataToken _explicitInt = new DataToken(5);
DataToken _explicitString = new DataToken("value");
DataToken _explicitBool = new DataToken(true);

// But this is easier and simpler
DataToken _float = 5.3f;
DataToken _Int = 5;
DataToken _String = "value";
DataToken _Bool = true;

Udon Graph

Udon Graphでは、値を保持するDataTokenを作成するために、DataToken ImplicitノードまたはDataToken Constructorノードを使用する必要があります。

Data Tokenからの値の取得

DataTokenから値を取り出す前に、含まれている型を確実に把握する必要があります。互換性のない型を取り出そうとすると、UdonBehaviourが停止してしまうためです。含まれている型が目的の型と互換性があることを確認するには、いくつかの方法があります。

• DataToken.TokenTypeプロパティを確認して、正確な型を取得できます。
• Data ListやData Dictionaryから値を取得する際は、TryGetValueを使用してTokenTypeを指定できます。TokenTypeが正しくない場合、その関数はfalseを返します。
• DataToken.IsNumberプロパティを確認して、数値かどうかを判定できます。数値である場合、Numberプロパティを安全に取り出すことができます。これは、元の型が何であれ、64-bitのdouble型にキャストされて返されます。元の型がlongやulongであった場合、精度が失われる可能性があります。
• トークンの型にかかわらず、ToStringは常に有効な選択肢であり、エラーが発生することはありません。

// If we know that it's a string, we can safely pull the string out of the token
if (unknownToken.TokenType == TokenType.String)
{
    Debug.Log(unknownToken.String);
}

// We can use IsNumber to see if it's some type of number, even if we don't know which.
if (unknownToken.IsNumber)
{
    Debug.Log(unknownToken.Number);
}

// If we're pulling a value from a container, we can use the version that does its own type check
if (dictionary.TryGetValue("key", TokenType.String, out DataToken value))
{
    Debug.Log(value.String);
}

正しい型であることを確認できたら、DataToken.Float や DataToken.Boolean といった値プロパティにアクセスすることで、DataToken から値を取得できます。各型には、その特定の型を取り出すために使用できる専用のプロパティが用意されています。

扱うデータを完全に制御できている場合は、TokenType のチェックをすべて省略し、トークンから直接値を取得できます。これによりコードの記述量を減らすことができますが、外部ソースからデータが提供される場合や、データが別の型である可能性がある場合は、この方法をとらないようにしてください。

dictionary["A"] = 5;
dictionary["B"] = 10;

// This makes the assumption that A and B will always contain integers.
// This is a safe assumption to make since we set them just above in a controlled environment.
// If the data is coming from an external source, we shouldn't make these assumptions!
int sum = dictionary["A"].Int + dictionary["B"].Int;

Errors

Data List や Data Dictionary に対する操作が失敗して DataToken が返される場合、エラー用のトークンが生成されます。エラー用トークンには、エラーの種類を分類する enum と、エラーの詳細を説明する文字列が含まれています。詳細な説明が不要なエラーの場合は、文字列が生成されないこともあります。

Error型のトークンがある場合、DataToken.Errorを使用してエラーのenumを取得し、DataToken.Stringでメッセージを取得できます。また、DataToken.ToString()を使用すれば、enumと文字列を自動的に結合した読みやすい完全なメッセージが生成されるため、単に Debug.Log(token) を呼び出すだけで済み便利です。

エラーの種類には、以下のものがあります。

if (dictionary.TryGetValue("key", TokenType.Float out DataToken value)) {
    // If TryGetValue succeeds, we can do things with the token
    Debug.Log($"Successfully retrieved value {token.Float}");
} else {
    // If TryGetValue fails, the token will instead be an error
    Debug.Log($"Failed to retrieve value with error {token.Error}");
}

FAQ

StringとToStringの違いは何ですか？

DataToken.StringとDataToken.ToString()は似ていますが、全く同じではありません。DataToken.StringはDataToken内部の文字列値に直接アクセスするものであるのに対し、DataToken.ToString()はそこに何が存在していても文字列に変換するものであるためです。

その結果、DataTokenの中身が何であっても ToString は常に有効であり、UdonBehaviourが停止することはありません。DataTokenがbool型を含んでいる場合は true または false を返し、数値型を含んでいる場合は ToString("G", CultureInfo.InvariantCulture) を使用してその数値を文字列に変換します。

一方、DataToken.Stringへのアクセスは、DataTokenが文字列を含んでいる場合にのみ有効です。もしDataTokenがfloat型を含んでいる状態で DataToken.String にアクセスしようとすると、例外が発生し、UdonBehaviourが停止します。

DataErrorは、Error enumと文字列の両方を含んでいるという点で独特です。DataErrorに対しては ToString() を使用することをお勧めします。これは、ToString() を呼び出すことで、エラー内容とエラーの理由の両方を含む一つのメッセージに結合されるためです。

トークンを介さずに直接値を取得する TryGetValue を用意してはどうでしょうか？

TryGetValueメソッドを使用して、トークンを介さずに値を直接取得できるようにすると便利です。コンテナから毎回トークンを取得し、そこからさらに個別に値へアクセスする手間がかかるため、これはもっともな疑問です。このプロセスを簡略化するためにいくつかの選択肢が検討されており、実装済みの解決策として、TryGetValueに組み込みの型チェックを含めるという方法があります。

もう一つの検討案として、T引数を使用してシステム型を指定する汎用版のTryGetValueを作成する方法がありました。UdonSharpはこのアプローチをサポートしていますが（少なくとも静的メソッド内では）、Udon自体は対応していません。さらに、この選択肢は利便性がある一方で、エラー発生時にDataTokenを介したDataErrorの返却ができなくなり、代わりにデフォルト値が返されてしまうという欠点があります。最終的に、ユーザーからエラーが隠蔽され、問題の特定が困難になるという理由から、この手法を採用しないことに決定しました。幸い、ユーザーはUdonSharpのジェネリクス、静的変数、および拡張メソッドを利用して、独自の汎用値取得ソリューションを作成することが可能です。