Add DictionaryArray::try_new() to create dictionaries from pre existing arrays

[alamb]

Draft as it builds on #1263

Which issue does this PR close?

Closes #1299

Rationale for this change

Inspired by the challenge writing tests on #1263 from @viirya

Otherwise known as "no one should have to write the following to work with DictionaryArrays":

Click to expand!

  fn get_dict_arraydata(
        keys: Buffer,
        key_type: DataType,
        value_data: ArrayData,
    ) -> ArrayData {
        let value_type = value_data.data_type().clone();
        let dict_data_type =
            DataType::Dictionary(Box::new(key_type), Box::new(value_type));
        ArrayData::builder(dict_data_type)
            .len(3)
            .add_buffer(keys)
            .add_child_data(value_data)
            .build()
            .unwrap()
    }

    #[test]
    fn test_eq_dyn_dictionary_i8_array() {
        let key_type = DataType::Int8;
        // Construct a value array
        let value_data = ArrayData::builder(DataType::Int8)
            .len(8)
            .add_buffer(Buffer::from(
                &[10_i8, 11, 12, 13, 14, 15, 16, 17].to_byte_slice(),
            ))
            .build()
            .unwrap();

        let keys1 = Buffer::from(&[2_i8, 3, 4].to_byte_slice());
        let keys2 = Buffer::from(&[2_i8, 4, 4].to_byte_slice());
        let dict_array1: DictionaryArray<Int8Type> = Int8DictionaryArray::from(
            get_dict_arraydata(keys1, key_type.clone(), value_data.clone()),
        );
        let dict_array2: DictionaryArray<Int8Type> =
            Int8DictionaryArray::from(get_dict_arraydata(keys2, key_type, value_data));

        let result = eq_dyn(&dict_array1, &dict_array2);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), BooleanArray::from(vec![true, false, true]));
    }

What changes are included in this PR?

1. Add DictionaryArray::try_new() function
2. Tests
3. Doc tests
4. Update tests from Add DictionaryArray support in eq_dyn kernel #1263 to use the new API

[viirya]

Looks good. Thanks. This can make writing dictionary array test much easier!

[jhorstmann]

Looks good. The double validation for the dictionary values is a bit unfortunate, but since this is mostly a convenience feature that should be fine.

[alamb]

Looks good. The double validation for the dictionary values is a bit unfortunate, but since this is mostly a convenience feature that should be fine.

I agree it is unfortunately

I'll see if I can make a new_unchecked() and then also minimize the checking in try_new() to only verify that all indexes are within the range of the dictionary, which Ido think is required for this to be a safe API.

[alamb]

Filed #1313 to track performance improvement

[alamb]

Thanks for the comments and review @jhorstmann and @viirya