Add Deref(T *), to ease dereferencing a pointer safely

[N-Dekker]

Deref(ptr) throws an exception when its argument (ptr) is null.

A similar function template is being used internally in elastix for quite a while: https://github.com/SuperElastix/elastix/blob/f64965f09eb0903e7bf1da4a112d914c7ac2ce22/Common/elxDeref.h

[dzenanz]

Adding a follow-up commit with uses of this new functionality are highly welcome!

[dzenanz]

Is this file reported in the exception message, or the line where it is invoked?

[N-Dekker]

Yes indeed, both of them (source file and line number) are reported in the exception message.

[dzenanz]

I meant, is file == ".../Modules/Core/Common/include/itkDeref.h", or file == ".../my/file/in/my/code/which/tried/to/deref/null.cpp"?

[N-Dekker]

The itk::DerefError exception message proposed by this PR will have something like "Modules/Core/Common/include/itkDeref.h" in there. Of course, it would have been nicer to have something like "my/file/in/my/code/which/tried/to/deref/null.cpp". I think that can be implemented most elegantly by C++20 std::source_location 😃. Until then, I think it's still nice for users to know the location where the DerefError is thrown, in "itkDeref.h", so that they can put a breakpoint at that location, when they are debugging the problem.

[blowekamp]

Did you consider using the "itkSpecializedMessageExceptionMacro?

[N-Dekker]

Thanks @blowekamp, please check my force-push!

[dzenanz]

/azp run ITK.Windows

[N-Dekker]

Update: I just removed Deref support for smart pointers, because there is some risk that it might lead to bugs. Suppose a function CreateObject() would return a smart pointer to a newly created object. The following might then cause ref to refer to a destructed object (after the line of code is executed):

auto & ref = Deref( CreateObject() );

On the other hand, Deref can certainly be used safely on raw pointers, as a raw pointer does not control the lifetime of the object pointed to.

[N-Dekker]

@dave3d Can you please explain how to fix the Spell Checking failures?

Run comment_spell_check \
  comment_spell_check \
    --miss \
    --prefix "gdcm" --exclude ThirdParty \
    --dict additional_dictionary.txt \
    --dict .github/workflows/itk_dict.txt \
    --suffix ".h" \
    --suffix ".hxx" \
    --suffix ".py" \
    Modules
  shell: /usr/bin/bash -e {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.9.18/x64
    PKG_CONFIG_PATH: /opt/hostedtoolcache/Python/3.9.18/x64/lib/pkgconfig
    Python_ROOT_DIR: /opt/hostedtoolcache/Python/3.9.18/x64
    Python2_ROOT_DIR: /opt/hostedtoolcache/Python/3.9.18/x64
    Python3_ROOT_DIR: /opt/hostedtoolcache/Python/3.9.18/x64
    LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.9.18/x64/lib
    Modules/Core/Common/include/itkDeref.h, 28

    Modules/Core/Common/include/itkDeref.h, 43
DerefError:

2 misspellings found

At https://github.com/InsightSoftwareConsortium/ITK/actions/runs/6803791308/job/18499888354?pr=4278

[dave3d]

@dave3d Can you please explain how to fix the Spell Checking failures?

Run comment_spell_check \
  comment_spell_check \
    --miss \
    --prefix "gdcm" --exclude ThirdParty \
    --dict additional_dictionary.txt \
    --dict .github/workflows/itk_dict.txt \
    --suffix ".h" \
    --suffix ".hxx" \
    --suffix ".py" \
    Modules
  shell: /usr/bin/bash -e {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.9.18/x64
    PKG_CONFIG_PATH: /opt/hostedtoolcache/Python/3.9.18/x64/lib/pkgconfig
    Python_ROOT_DIR: /opt/hostedtoolcache/Python/3.9.18/x64
    Python2_ROOT_DIR: /opt/hostedtoolcache/Python/3.9.18/x64
    Python3_ROOT_DIR: /opt/hostedtoolcache/Python/3.9.18/x64
    LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.9.18/x64/lib
    Modules/Core/Common/include/itkDeref.h, 28

    Modules/Core/Common/include/itkDeref.h, 43
DerefError:

2 misspellings found

At https://github.com/InsightSoftwareConsortium/ITK/actions/runs/6803791308/job/18499888354?pr=4278

DerefError is a new keyword that should be added to the spelling dictionary. Add it to the file .github/workflows/itk_dict.txt.

[dzenanz]

Or perhaps use something which is "kosher", such as DereferenceError? It is a symbol which is not expected to be typed a lot.

[N-Dekker]

Thanks for your feedback, @dzenanz, @dave3d Personally I find "Deref" clear enough. When I google on "deref", it's all about dereferencing: https://www.google.com/search?q=deref And as "DerefError" is the error that may occur specifically when calling "Deref", I would prefer to stick with "DerefError". Hope that's acceptable to you both 🙏

@dave3d would it be sufficient to add "Deref" to .github/workflows/itk_dict.txt in order to use "DerefError"? I guess it knows "Error" already, right?

[dave3d]

Thanks for your feedback, @dzenanz, @dave3d Personally I find "Deref" clear enough. When I google on "deref", it's all about dereferencing: https://www.google.com/search?q=deref And as "DerefError" is the error that may occur specifically when calling "Deref", I would prefer to stick with "DerefError". Hope that's acceptable to you both 🙏

@dave3d would it be sufficient to add "Deref" to .github/workflows/itk_dict.txt in order to use "DerefError"? I guess it knows "Error" already, right?

Yes, you can just add 'deref'.

[dzenanz]

This is a good demonstration of how this is supposed to be used. I would like to see some more instances of use, better demonstrating a need for a new function and exception class.

[N-Dekker]

Thanks @dzenanz

I use elastix::Deref extensively within elastix, e.g. (source):

elastix::Deref(MersenneTwisterRandomVariateGenerator::GetInstance()).SetSeed(...);

and (source)

MultiThreaderBase & multiThreader = elastix::Deref(this->ProcessObject::GetMultiThreader());
multiThreader.SetSingleMethod(...);
multiThreader.SingleMethodExecute();

Once itk::Deref is available, I would like to replace those elastix::Deref calls with itk::Deref. I feel that this function isn't really elastix specific. It could be useful for other ITK users as well. Does that answer your question?