<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Change SYSTEM "https://itk.org/migrationv4/ITKMigration.dtd">

<!--**
**
** ConvertSingleElmentSetDataToSetDataSameSize.xml
**
**-->
<Change>
    <!--**
    ** Title for the online migration page
    **-->
    <Title>
      Convert Single Argument SetData To SetDataSameSize
    </Title>

    <!--**
    ** The author of the change
    **-->
    <Author>
      Hans Johnson
    </Author>

    <!--**
    ** Date of creation for the XML document
    **-->
    <Date>
      2016-03-16
    </Date>

    <!--**
    ** Plain text description of the change
    ** Extracted from git commit messages
    **-->
    <Description>
      <![CDATA[

      SizeValueType for an array is different than SizeValueType
      defined in itkIntTypes.h.  This causes ambiguities when
      a call to SetData(...) is made where the second parameter
      is not the same as itk::Array::SizeValueType.

      Most naturally, we would expect any integer type to
      be automatically typecast to itk::Array::SizeValueType,
      but one of signatures for SetData takes 2 arguments
      (with the second argument defaulting to false) that implicitly assumes
      that the size of the input array is exactly the same
      size as the array being passed in.  In this optimization case,
      the second argument is bool indicating if the memory should
      be managed by the array.  This optimized case conflicts
      with the 3 parameter version of SetData (with the third arugment
      defaulting to false) when the second argument does not exactly
      match itk::Array::SizeValueType.

      Additionally, due to ambiguity introduced by the default
      boolean option, if the type of variable pass to the function
      does not match SizeValueType exactly, it is unclear if that
      type should be cast to bool (matching the first signature)
      or to SizeValueType (matching the second signature).

      SetData was not called anywhere in [Slicer,BRAINSTools,UKF,
      ANTs, SlicerExectionModel, AnalyzeObjectMapIO,
      HigherOrderAccurateGradient, LesionSizingToolkit, MGHIO,
      SCIFIO, SmoothingRecursiveYvvGaussianFilter, SplitComponents]

      SimpleITK called SetData in 2 places, and in both cases it
      used the fully qualified 3 argument version.

      Internal to ITK, there was only 1 place where the
      two argument version was used.  Since the two argument version
      is such a specialized case with only a single use found in
      all source code, it&apos;s name was changed to be more specialized
      and avoid the ambiguitity.

      ]]>
    </Description>

    <!--**
    ** Sample code snippets
    ** Extracted from git diff of changed files in Examples and Testing
    **-->
    <SampleCode>
      <Old>
        <![CDATA[
        typedef float MyType;
        const size_t mySize=10
        itk::Array<MyType> myArray(mySize);
        float data = new  MyType[mySize];
        myArray->SetData(data); // Implicitly requires data size is same as myArray, & default value of false
        ]]>
      </Old>

      <New>
        <![CDATA[
        typedef float MyType;
        const size_t mySize=10
        itk::Array<MyType> myArray(mySize);
        float data = new  MyType[mySize];
        myArray->SetDataSameSize(data);
        //myArray->SetDataSameSize(data,false); // Prefer to explicitly state false
        ]]>
      </New>

    </SampleCode>

    <!--**
    ** The change-ids for all commits in the topic branch
    **-->
    <Gerrit-ChangeId>
      I0d726efcffa8499556492ccbfae9408cba1d09fe
    </Gerrit-ChangeId>

    <!--**
    ** List of all changed files from the topic branch
    **-->
    <FileList>
      Modules/Core/Common/include/itkArray.h
      Modules/Core/Common/include/itkArray.hxx
      Modules/Core/Common/test/itkArrayTest.cxx
      Modules/Numerics/Optimizers/src/itkMultipleValuedVnlCostFunctionAdaptor.cxx
      Modules/Numerics/Optimizers/src/itkSingleValuedVnlCostFunctionAdaptor.cxx
      Modules/Numerics/Optimizersv4/src/itkSingleValuedVnlCostFunctionAdaptorv4.cxx
    </FileList>

    <!--**
    ** If the migration can be accomplished by a simple string
    ** substitution, then use the following construct to define
    ** the substitution rule.
    **
    ** <MigrationFix-Automatic>
    **   <Old>
    **     <![CDATA[MipsleledName]]>
    **   </Old>
    **   <New>
    **     <![CDATA[MisspelledName]]>
    **   </New>
    ** </MigrationFix-Automatic>
    **-->

    <!--**
    ** If the migration can NOT be accomplished by a simple string
    ** substitution, but potential problem spots can be identified,
    ** use the following construct to define a migration flag rule.
    **
    ** <MigrationFix-Manual>
    **   OldFunctionName
    ** </MigrationFix-Manual>
    **-->

</Change>
