ref キーワードを活用した参照戻り値の実装例 - i-school

ref キーワード

　ref キーワードは、変数を参照して利用できるようにするための機能です。

MicroSoft
ref (C# リファレンス)

++C++; // 未確認飛行 C 様
参照渡し

　ref キーワード自体には複数(現在 5 種類)の利用方法が用意されていますが、ここでは【参照戻り値】と【ref ローカル変数】についての説明と実装例を提示します。

参照戻り値と ref (参照)ローカル変数

　メソッドの戻り値の型の前に ref キーワードを利用することで、戻り値の値に対して参照渡しを行うことが出来ます。

＜参照戻り値のあるメソッド＞

  private ref int SampleMethodRef(string name) { }

　利用する場合には、戻り値の型の前、値を渡す側、値を受ける側に、それぞれ ref 修飾子を記述します。

　ローカル変数についても ref キーワードを利用することで、代入する変数の値を参照渡しすることが出来ます。

　その場合、参照として引数を渡す側、そして参照を受け取る側の両側に ref キーワードが必要になります。

＜参照戻り値のあるメソッドを利用して ref ローカル変数に参照値を受け取る＞

  ref int count = ref SampleMethodRef("itemName");

参考サイト
++C++; // 未確認飛行 C 様
参照戻り値と参照ローカル変数

実装例

　上記の説明を元に、実際に利用する例を記載します。
なお、比較できるように、参照戻り値を利用するケースと利用しないケースを提示しています。

　複数の種類のアイテムが、それぞれ別の所持数として管理されている場合に、指定したアイテムの所持数の値を更新する処理に利用したケースです。

　通常の処理の場合、アイテムの種類ごとにメソッドを用意して、その中で所持数の更新を行うことが多いですが、
参照戻り値を利用することで、１つの変数に、そのときに更新が必要なアイテムの所持数を参照して取得することにより、
複数のメソッドを用意することなく、また、追加のプログラムの必要なく、プログラム内の所持数の更新部分を一元化することが出来ています。

ItemName .cs

<=　クリックすると開きます。

/// <summary>
/// アイテムの名前
/// </summary>
public enum ItemName {
    Bandage,            //包帯
    MedicinalPlants,    //薬草
    Syringe,            //注射器
}

＜参照戻り値を利用しないケース＞

PlayerHealth.cs

<=　クリックすると開きます。

using UnityEngine;

public class PlayerHealth : MonoBehaviour 
{
    //Playerの体力とプロパティ
    private int playerHp = 100;
    private int maxHp = 1000;
    public int PlayerHp
    {
        get => playerHp;
        set => playerHp = Mathf.Min(playerHp += value, maxHp);
    }

    //包帯の数とプロパティ
    private int bandageCount;
    public int BandageCount { get => bandageCount; }

    //薬草の数とプロパティ
    private int medicinalPlantscount;
    public int MedicinalPlantsCount { get => medicinalPlantscount; }

    //注射器の数とプロパティ
    private int syringeCount;
    public int SyringeCount { get => syringeCount; }

    // 回復アイテムの最大数(全アイテム共通の場合)
    private const int maxCount = 100;


    /// <summary>
    /// 回復アイテムの所持数を更新する
    /// </summary>
    /// <param name="itemName">アイテムの名前</param>
    /// <param name="updateValue">所持数の更新量</param>
    public void UpdateRecoveryItemCount(ItemDataSO.ItemName itemName, int updateValue)
    {
        //アイテムの名前に応じて処理を変更
        switch(itemName)
        {
            //包帯なら
            case ItemName.Bandage:
                bandageCount = Mathf.Clamp(bandageCount + updateValue, 0, maxCount);
                break;

            //薬草なら
            case ItemName.MedicinalPlants:
                medicinalPlantscount = Mathf.Clamp(medicinalPlantscount + updateValue, 0, maxCount);
                break;

            //注射器なら
            case ItemName.Syringe:
                syringeCount = Mathf.Clamp(syringeCount+updateValue, 0, maxCount);
                break;
        }
    }
}

　この実装の場合、アイテムの種類が増えるごとに、似たような処理を switch 文内に逐次追加していく必要があります。
そのため、アイテムの種類を増やすたびに、アイテムの所持数を更新する処理自体が追加されることになり、煩雑かつ、手間が増えることになります。

＜参照戻り値と参照ローカル変数を利用するケース＞

　参照戻り値と参照ローカル変数を利用することで、利用しない場合には１つのメソッド内で実装していた処理を２つのメソッドを分けて作成しています。

　参照している値の更新を行う UpdateRecoveryItemCount メソッドと、どの値を参照するかを決定する GetRecoveryItemCountRef メソッドに分けているので、
修正する場合には、GetRecoveryItemCountRef メソッドのみ修正する形式になっています。

　今回の場合、参照戻り値の機能を利用することにより、戻り値の値をメンバ変数の参照値とすることができますので、
その値を増減した場合には、メンバ変数の値そのものが変更されることになります。

PlayerHealth.cs

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class PlayerHealth : MonoBehaviour 
{
    //Playerの体力とプロパティ
    private int playerHp = 100;
    private int maxHp = 1000;
    public int PlayerHp
    {
        get => playerHp;
        set => playerHp = Mathf.Min(playerHp += value, maxHp);
    }

    //包帯の数とプロパティ
    private int bandageCount;
    public int BandageCount { get => bandageCount; }

    //薬草の数とプロパティ
    private int medicinalPlantscount;
    public int MedicinalPlantsCount { get => medicinalPlantscount; }

    //注射器の数とプロパティ
    private int syringeCount;
    public int SyringeCount { get => syringeCount; }

    // 回復アイテムの最大数(全アイテム共通の場合)
    private const int maxCount = 100;


////*  ここから変更  *////


    // 参照戻り値の switch 文内の default 判定時用の変数
    private int x = 0;


    /// <summary>
    /// 回復アイテムの所持数を更新する
    /// この処理があれば、複数の回復アイテムがあっても、アイテムごとに同じようなメソッドを用意しなくてよい
    /// よってゲーム内に登場するアイテムの種類が増減しても、所持数を更新するこのメソッド部分のプログラムは一切変更が不要になる
    /// </summary>
    /// <param name="itemName">アイテムの名前</param>
    /// <param name="updateValue">所持数の更新量</param>
    public void UpdateRecoveryItemCount(ItemName itemName, int updateValue) 
    {
        // ItemNameから更新する回復アイテムの個数と最大値を GetRecoveryItemCountRef メソッドに参照渡しをして処理し、戻り値を参照戻り値でもらって取得
        // 参照した値を戻り値として変数に代入しているので、それは新しい値ではなく、メンバ変数に用意している変数の情報を参照した値が取得できる
        ref int recoveryItemCount = ref GetRecoveryItemCountRef(itemName);   // ローカル変数の前と引数に値を渡すメソッドの前に ref を記述する

        // TODO 回復アイテムの最大所持数がアイテムごとに異なる場合には、ここで用意する

        // 回復アイテムの所持数を、最大値と最小値に収まるように制限して更新する
        recoveryItemCount = Mathf.Clamp(recoveryItemCount + updateValue, 0, maxCount);　　//　☆　参照値を更新するので、メンバ変数自体が変わる

　　　　// 参照している値が更新されているかを確認
　　　　Debug.Log($"{ itemName } : { recoveryItemCount }");
    }

    /// <summary>
    /// 指定した回復アイテムの所持数を参照戻り値で取得する
    /// アイテムが増えたり減ったりした場合には、 case の部分を追加・削除すれば、上記の所持数の更新の処理自体は何も変更しなくてよい。
    /// </summary>
    /// <param name="itemName">回復アイテムの名前</param>
    /// <returns>その回復アイテムの所持数</returns>
    private ref int GetRecoveryItemCountRef(ItemName itemName) 　　//　戻り値の前に ref を記述する
    {
        //アイテムの名前に応じて処理を変更
        switch(itemName) 
        {
　　　　　　// 各メンバ変数の値を参照して戻す
            case ItemName.Bandage: return ref bandageCount;                     // 戻す値の前にも ref を記述する
            case ItemName.MedicinalPlants: return ref medicinalPlantscount;
            case ItemName.Syringe: return ref syringeCount;
            default: return ref x;　　　　　　　　　　　　　　　　　　　　　　　// 参照戻り値に利用できる値はローカル変数を指定するとエラーとなるため、メンバ変数で定義している変数を指定している。
        }
    }
}

　こちらのケースの場合、UpdateRecoveryItemCount メソッド内で参照した値の更新を行う機能が備わっているので、
今後、アイテムの種類が増減しても、このメソッド内への修正は必要ありません。

　代わりに、GetRecoveryItemCountRef メソッド内の switch 文の分岐のみ修正すれば済みます。

　private int x = 0; の宣言は、GetRecoveryItemCountRef メソッド内の switch 文の default で利用するために宣言しています。
理由は、参照戻り値として指定できる変数にはローカル変数は利用できないというルールがあるためです。
例えば、GetRecoveryItemCountRef メソッド内で int x = 0; を宣言した場合、x は上記のルールにより、指定するとエラーになります。

　なお戻り値のある switch 文の場合には式での書式の switch 文が利用できますが、参照戻り値の場合には、式での書式は利用できません。
(通常の switch 文で記述する必要があります)

　参照利用しているポイントは、以下の部分に効果的に利用されています。

UpdateRecoveryItemCount メソッド内

  // 回復アイテムの所持数を、最大値と最小値に収まるように制限して更新する
  recoveryItemCount = Mathf.Clamp(recoveryItemCount + updateValue, 0, maxCount);　　//　☆　参照値を更新するので、メンバ変数自体が変わる

　この recoveryItemCount の値が、その前の処理で参照して取得した、いずれかのメンバ変数の値になっています。
メンバ変数の値のコピー値ではないので、この値を変更すると、メンバ変数の値が参照されて変化します。

　そのため、アイテムの所持数を更新する処理はこの１つだけですが、更新を行う値がその都度、参照先を変えるようなロジックになっているので
いずれのメンバ変数の値であっても対応出来るようになっています。

参照戻り値と参照ローカル変数を利用した場合のデバッグ用ソースコード

　上記の参照戻り値と参照ローカル変数を利用した場合のデバッグ用のソースコードを掲載しておきます。
作成したら、任意のゲームオブジェクトにアタッチしてゲームを実行してデバッグを行います。

　Start メソッド内で実行する UpdateRecoveryItemCount メソッドの指定を変えて、処理の内容を確認をします。
このソースコードでは減算のみしていますが、当然加算も出来ますので、自分で処理を書き換えて確認してみてください。

　このデバッグにおいて大切なのは、参照ローカル変数については、参照戻り値としてメンバ変数が参照されているかを確認します。
そして参照ローカル変数を更新することで、参照されているメンバ変数の値が正常に更新されていることを確認することです。

　デバッグする意味とデバッグの内容を理解した上で確認を行うことが大切になります。

PlayerHealth.cs

<=　クリックすると開きます。

using UnityEngine;

public class PlayerHealth : MonoBehaviour {

    //Playerの体力とプロパティ
    private int playerHp = 100;
    private int maxHp = 1000;
    public int PlayerHp
    {
        get => playerHp;
        set => playerHp = Mathf.Min(playerHp += value, maxHp);
    }

    //包帯の数とプロパティ
    private int bandageCount;
    public int BandageCount { get => bandageCount; }

    //薬草の数とプロパティ
    private int medicinalPlantscount;
    public int MedicinalPlantsCount { get => medicinalPlantscount; }

    //注射器の数とプロパティ
    private int syringeCount;
    public int SyringeCount { get => syringeCount; }

    // 回復アイテムの最大数(全アイテム共通の場合)
    private const int maxCount = 100;

    // 参照戻り値の switch 文内の default 判定時用の変数
    private int x = 0;


    void Reset() {
        bandageCount = 10;
        medicinalPlantscount = 5;
        syringeCount = 3;
    } 

    void Start() {
        Reset();

        // デバッグ用
        UpdateRecoveryItemCount(ItemName.Bandage, -1);
        UpdateRecoveryItemCount(ItemName.Bandage, -1);

        UpdateRecoveryItemCount(ItemName.MedicinalPlants, -2);
    }

    /// <summary>
    /// 回復アイテムの所持数を更新する
    /// この処理があれば、複数の回復アイテムがあっても、アイテムごとに同じようなメソッドを用意しなくてよい
    /// よってゲーム内に登場するアイテムの種類が増減しても、所持数を更新する部分のプログラムは一切変更が不要になる
    /// </summary>
    /// <param name="itemName">アイテムの名前</param>
    /// <param name="updateValue">所持数の更新量</param>
    public void UpdateRecoveryItemCount(ItemName itemName, int updateValue) {
        // ItemNameから更新する回復アイテムの個数と最大値を GetRecoveryItemCountRef メソッドに参照渡しをして処理し、戻り値を参照戻り値でもらって取得
        // 参照した値を戻り値として変数に代入しているので、それは新しい値ではなく、メンバ変数に用意している変数の情報を参照した値が取得できる
        ref int recoveryItemCount = ref GetRecoveryItemCountRef(itemName);

        // TODO 回復アイテムの最大所持数がアイテムごとに異なる場合には、ここで用意する

        // 回復アイテムの所持数を、最大値と最小値に収まるように制限して更新する
        recoveryItemCount = Mathf.Clamp(recoveryItemCount + updateValue, 0, maxCount);

        Debug.Log($"{ itemName } : { recoveryItemCount }");
    }

    /// <summary>
    /// 指定した回復アイテムの所持数を参照戻り値で取得する
    /// アイテムが増えたり減ったりした場合には、 case の部分を追加・削除すれば、上記の所持数の更新の処理自体は何も変更しなくてよい。
    /// </summary>
    /// <param name="itemName">回復アイテムの名前</param>
    /// <returns>その回復アイテムの所持数</returns>
    private ref int GetRecoveryItemCountRef(ItemName itemName) {
        //アイテムの名前に応じて処理を変更
        switch (itemName) {
            case ItemName.Bandage: return ref bandageCount;
            case ItemName.MedicinalPlants: return ref medicinalPlantscount;
            case ItemName.Syringe: return ref syringeCount;
            default: return ref x;
        }
    }
}

　出力結果です。

Console ビュー

　インスペクター内も、Debug モードに切り替えることで、メンバ変数が参照されて値が変化していることを確認できます。

インスペクター(Debug モード)　初期値

　　　　　↓

インスペクター(Debug モード)　デバッグ実行時

まとめ

　すべての処理に応用できるわけではありませんが、戻り値の利用方法の１つとして押さえておくとよい機能になります。
タプルを利用した戻り値もそうですが、スキルの引き出しを増やす(今回であれば、色々な戻り値の使い方を知っている)ことで視野の広い設計が可能になります。

　以上になります。