Fix, test, and document build_extract_value

Author: TheDan64

src/builder.rs

@@ -945,16 +945,61 @@ impl Builder {
         }
     }
 
-    // REVIEW: How does LLVM treat out of bound index? Maybe we should return an Option?
-    // or is that only in bounds GEP
-    pub fn build_extract_value<AV: AggregateValue>(&self, value: AV, index: u32, name: &str) -> BasicValueEnum {
+    /// Builds an extract value instruction which extracts a `BasicValueEnum`
+    /// from a struct or array.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use inkwell::context::Context;
+    ///
+    /// let context = Context::create();
+    /// let module = context.create_module("av");
+    /// let void_type = context.void_type();
+    /// let f32_type = context.f32_type();
+    /// let i32_type = context.i32_type();
+    /// let struct_type = context.struct_type(&[i32_type.into(), f32_type.into()], false);
+    /// let array_type = i32_type.array_type(3);
+    /// let fn_type = void_type.fn_type(&[], false);
+    /// let fn_value = module.add_function("av_fn", fn_type, None);
+    /// let builder = context.create_builder();
+    /// let entry = fn_value.append_basic_block("entry");
+    ///
+    /// builder.position_at_end(&entry);
+    ///
+    /// let array_alloca = builder.build_alloca(array_type, "array_alloca");
+    /// let array = builder.build_load(array_alloca, "array_load").into_array_value();
+    /// let const_int1 = i32_type.const_int(2, false);
+    /// let const_int2 = i32_type.const_int(5, false);
+    /// let const_int3 = i32_type.const_int(6, false);
+    ///
+    /// assert!(builder.build_insert_value(array, const_int1, 0, "insert").is_some());
+    /// assert!(builder.build_insert_value(array, const_int2, 1, "insert").is_some());
+    /// assert!(builder.build_insert_value(array, const_int3, 2, "insert").is_some());
+    /// assert!(builder.build_insert_value(array, const_int3, 3, "insert").is_none());
+    ///
+    /// assert!(builder.build_extract_value(array, 0, "extract").unwrap().is_int_value());
+    /// assert!(builder.build_extract_value(array, 1, "extract").unwrap().is_int_value());
+    /// assert!(builder.build_extract_value(array, 2, "extract").unwrap().is_int_value());
+    /// assert!(builder.build_extract_value(array, 3, "extract").is_none());
+    /// ```
+    pub fn build_extract_value<AV: AggregateValue>(&self, agg: AV, index: u32, name: &str) -> Option<BasicValueEnum> {
+        let size = match agg.as_aggregate_value_enum() {
+            AggregateValueEnum::ArrayValue(av) => av.get_type().len(),
+            AggregateValueEnum::StructValue(sv) => sv.get_type().count_fields(),
+        };
+
+        if index >= size {
+            return None;
+        }
+
         let c_string = CString::new(name).expect("Conversion to CString failed unexpectedly");
 
         let value = unsafe {
-            LLVMBuildExtractValue(self.builder, value.as_value_ref(), index, c_string.as_ptr())
+            LLVMBuildExtractValue(self.builder, agg.as_value_ref(), index, c_string.as_ptr())
         };
 
-        BasicValueEnum::new(value)
+        Some(BasicValueEnum::new(value))
     }
 
     /// Builds an insert value instruction which inserts a `BasicValue` into a struct

tests/all/test_builder.rs

@@ -630,6 +630,11 @@ fn test_insert_value() {
     assert!(builder.build_insert_value(array, const_int3, 3, "insert").is_none());
     assert!(builder.build_insert_value(array, const_int3, 4, "insert").is_none());
 
+    assert!(builder.build_extract_value(array, 0, "extract").unwrap().is_int_value());
+    assert!(builder.build_extract_value(array, 1, "extract").unwrap().is_int_value());
+    assert!(builder.build_extract_value(array, 2, "extract").unwrap().is_int_value());
+    assert!(builder.build_extract_value(array, 3, "extract").is_none());
+
     let struct_alloca = builder.build_alloca(struct_type, "struct_alloca");
     let struct_value = builder.build_load(struct_alloca, "struct_load").into_struct_value();
 
@@ -638,6 +643,11 @@ fn test_insert_value() {
     assert!(builder.build_insert_value(struct_value, const_float, 2, "insert").is_none());
     assert!(builder.build_insert_value(struct_value, const_float, 3, "insert").is_none());
 
+    assert!(builder.build_extract_value(struct_value, 0, "extract").unwrap().is_int_value());
+    assert!(builder.build_extract_value(struct_value, 1, "extract").unwrap().is_float_value());
+    assert!(builder.build_extract_value(struct_value, 2, "extract").is_none());
+    assert!(builder.build_extract_value(struct_value, 3, "extract").is_none());
+
     builder.build_return(None);
 
     assert!(module.verify().is_ok());