Rust Htslib

https://docs.rs/rust-htslib/latest/rust_htslib
Admin
Rust-Htslib provides a high-level Rust API for reading and writing common HTS file formats, offering...
Tokens:451,943
Snippets:2,250
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Cow Slice Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Provides an example of using `Cow` (Clone-on-Write) with slices, demonstrating both owned and borrowed variants.

```Rust
let o: Cow<'_, [i32]> = Cow::Owned(vec![1, 2, 3]);
let b: Cow<'_, [i32]> = Cow::Borrowed(&[1, 2, 3]);
assert_eq!(Vec::from(o), Vec::from(b));
```

--------------------------------

### Rust Option zip Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/type

Demonstrates the `zip` method for Option, which combines two Options into an Option of a tuple if both are Some.

```rust
let x = Some(1);
let y = Some("hi");
let z = None::<u8>;

assert_eq!(x.zip(y), Some((1, "hi")));
assert_eq!(x.zip(z), None);
```

--------------------------------

### Rust Slice fill_with Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Demonstrates filling a slice with values generated by a closure.

```Rust
let mut buf = vec![1; 10];
buf.fill_with(Default::default);
assert_eq!(buf, vec![0; 10]);
```

--------------------------------

### Rust Option ok_or Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/type

Illustrates `ok_or` which converts an Option to a Result, mapping Some to Ok and None to Err.

```Rust
let x = Some("foo");
assert_eq!(x.ok_or(0), Ok("foo"));

let x: Option<&str> = None;
assert_eq!(x.ok_or(0), Err(0));
```

--------------------------------

### Rust Result expect() Method Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/errors/type

Illustrates the use of the expect() method on a Result, which unwraps the Ok value or panics with a provided message if it's an Err. Includes a recommended message style example for environment variables.

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
```

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

--------------------------------

### Get RecordBuffer Start Position in Rust

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/buffer/struct

Retrieves the starting position of the current buffer's data.

```Rust
pub fn start(&self) -> Option<u64>
```

--------------------------------

### Build Fasta Index and Read Sequences

Source: https://docs.rs/rust-htslib/latest/rust_htslib/faidx/struct

Demonstrates building a FASTA index and then using the `Reader` to fetch sequence names. This example showcases a common workflow for FASTA file processing.

```Rust
 use rust_htslib::faidx::build;
 let path = std::path::PathBuf::from(concat!(env!("CARGO_MANIFEST_DIR"),"/test/test_cram.fa"));
 build(&path).expect("Failed to build fasta index");
 let reader = rust_htslib::faidx::Reader::from_path(path).expect("Failed to open faidx");
 assert_eq!(reader.seq_names(), Ok(vec!["chr1".to_string(), "chr2".to_string(), "chr3".to_string()]));
```

--------------------------------

### Get CigarStringView Start Position

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Returns the 0-based start position of an alignment within the reference sequence, as represented by a CigarStringView. This is a key piece of information for read alignment.

```rust
pub fn pos(&self) -> i64
```

--------------------------------

### Rust: Get mutable slice from Option<T>

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/type

Demonstrates getting a mutable slice from an Option<T>, returning an empty mutable slice if None. Includes an example of modifying the value through the slice.

```Rust
assert_eq!(
    [Some(1234).as_mut_slice(), None.as_mut_slice()],
    [&mut [1234][..], &mut [][..]],
);

let mut x = Some(1234);
x.as_mut_slice()[0] += 1;
assert_eq!(x, Some(1235));

assert_eq!(Some(123).as_mut_slice().first_mut(), Some(&mut 123))
```

--------------------------------

### Rust Vec from Raw Parts Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Shows how to create a Vec from a raw pointer, length, and capacity, including managing memory and overwriting existing data. It also demonstrates using memory allocated elsewhere.

```rust
use std::ptr;
use std::mem;

let v = vec![1, 2, 3];

// Prevent running `v`'s destructor so we are in complete control
// of the allocation.
let mut v = mem::ManuallyDrop::new(v);

// Pull out the various important pieces of information about `v`
let p = v.as_mut_ptr();
let len = v.len();
let cap = v.capacity();

unsafe {
    // Overwrite memory with 4, 5, 6
    for i in 0..len {
        ptr::write(p.add(i), 4 + i);
    }

    // Put everything back together into a Vec
    let rebuilt = Vec::from_raw_parts(p, len, cap);
    assert_eq!(rebuilt, [4, 5, 6]);
}
```

```rust
use std::alloc::{alloc, Layout};

fn main() {
    let layout = Layout::array::<u32>(16).expect("overflow cannot happen");

    let vec = unsafe {
        let mem = alloc(layout).cast::<u32>();
        if mem.is_null() {
            return;
        }

        mem.write(1_000_000);

        Vec::from_raw_parts(mem, 1, 16)
    };

    assert_eq!(vec, &[1_000_000]);
    assert_eq!(vec.capacity(), 16);
}
```

--------------------------------

### Rust Vec as_non_null Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Illustrates the usage of the experimental `as_non_null` method to get a `NonNull` pointer to a vector's buffer. Examples cover initialization and demonstrate the aliasing guarantee for safe pointer operations.

```Rust
#![feature(box_vec_non_null)]\n\n// Allocate vector big enough for 4 elements.\nlet size = 4;\nlet mut x: Vec<i32> = Vec::with_capacity(size);\nlet x_ptr = x.as_non_null();\n\n// Initialize elements via raw pointer writes, then set length.\nunsafe {\n    for i in 0..size {\n        x_ptr.add(i).write(i as i32);\n    }\n    x.set_len(size);\n}\nassert_eq!(&*x, &[0, 1, 2, 3]);
```

```Rust
#![feature(box_vec_non_null)]\n\unsafe {\n    let mut v = vec![0];\n    let ptr1 = v.as_non_null();\n    ptr1.write(1);\n    let ptr2 = v.as_non_null();\n    ptr2.write(2);\n    // Notably, the write to `ptr2` did *not* invalidate `ptr1`:\n    ptr1.write(3);\n}
```

--------------------------------

### Get Iterator for Slice (Rust)

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/struct

Returns an iterator that yields references to the elements of the slice from start to end.

```Rust
pub fn iter(&self) -> Iter<'_, T>
```

--------------------------------

### Rust Vec Length Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Shows how to get the number of elements in a vector using the `len()` method.

```rust
let a = vec![1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### Allocate Memory and Create Vec from Parts

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Shows how to allocate memory using a global allocator, write data to it, and then construct a Vec from the allocated memory using `Vec::from_parts_in`. This example emphasizes manual memory management and the use of `Layout`.

```Rust
#![feature(allocator_api, box_vec_non_null)]

use std::alloc::{AllocError, Allocator, Global, Layout};

fn main() {
    let layout = Layout::array::<u32>(16).expect("overflow cannot happen");

    let vec = unsafe {
        let mem = match Global.allocate(layout) {
            Ok(mem) => mem.cast::<u32>(),
            Err(AllocError) => return,
        };

        mem.write(1_000_000);

        Vec::from_parts_in(mem, 1, 16, Global)
    };

    assert_eq!(vec, &[1_000_000]);
    assert_eq!(vec.capacity(), 16);
}
```

--------------------------------

### Rust slice rsplit example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/struct

Demonstrates splitting a slice into subslices separated by elements that match a predicate, starting from the end. The matched element is excluded.

```rust
let slice = [11, 22, 33, 0, 44, 55];
let mut iter = slice.rsplit(|num| *num == 0);

assert_eq!(iter.next().unwrap(), &[44, 55]);
assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
assert_eq!(iter.next(), None);
```

--------------------------------

### Rust Option xor Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/type

Illustrates the `xor` method for Option, which returns Some if exactly one of the two Options is Some, and None otherwise.

```rust
let x = Some(2);
let y: Option<u32> = None;
assert_eq!(x.xor(y), Some(2));

let x: Option<u32> = None;
let y = Some(2);
assert_eq!(x.xor(y), Some(2));

let x = Some(2);
let y = Some(2);
assert_eq!(x.xor(y), None);

let x: Option<u32> = None;
let y: Option<u32> = None;
assert_eq!(x.xor(y), None);
```

--------------------------------

### Rust slice rsplitn_mut example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/struct

Demonstrates splitting a mutable slice into a maximum of `n` mutable subslices, starting from the end, using a predicate. The subslices can be modified.

```rust
let mut s = [10, 40, 30, 20, 60, 50];

for group in s.rsplitn_mut(2, |num| *num % 3 == 0) {
    group[0] = 1;
}
assert_eq!(s, [1, 40, 30, 20, 60, 1]);
```

--------------------------------

### Rust Vec with Capacity Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Demonstrates creating a Vec with a specified capacity and how it handles pushes without reallocating, up to its capacity. It also shows behavior with zero-sized types.

```rust
let mut vec = Vec::with_capacity(10);

// The vector contains no items, even though it has capacity for more
assert_eq!(vec.len(), 0);
assert!(vec.capacity() >= 10);

// These are all done without reallocating...
for i in 0..10 {
    vec.push(i);
}
assert_eq!(vec.len(), 10);
assert!(vec.capacity() >= 10);

// ...but this may make the vector reallocate
vec.push(11);
assert_eq!(vec.len(), 11);
assert!(vec.capacity() >= 11);

// A vector of a zero-sized type will always over-allocate, since no
// allocation is necessary
let vec_units = Vec::<()>::with_capacity(10);
assert_eq!(vec_units.capacity(), usize::MAX);
```

--------------------------------

### Rust slice rsplitn example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/struct

Shows splitting a slice into a maximum of `n` subslices, starting from the end, based on a predicate. The last subslice contains the remainder.

```rust
let v = [10, 40, 30, 20, 60, 50];

for group in v.rsplitn(2, |num| *num % 3 == 0) {
    println!("{group:?}");
}
```

--------------------------------

### Rust Option zip_with Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/type

Shows the nightly-only `zip_with` method for Option, which combines two Options using a provided function if both are Some.

```rust
#![feature(option_zip)]

#[derive(Debug, PartialEq)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
    fn new(x: f64, y: f64) -> Self {
        Self { x, y }
    }
}

let x = Some(17.5);
let y = Some(42.7);

assert_eq!(x.zip_with(y, Point::new), Some(Point { x: 17.5, y: 42.7 }));
assert_eq!(x.zip_with(None, Point::new), None);
```

--------------------------------

### Rust binary_search example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Demonstrates the binary_search method on a sorted slice. It shows how to find an element, handle cases where the element is not found, and how to interpret the result when multiple identical elements exist.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

assert_eq!(s.binary_search(&13),  Ok(9));
assert_eq!(s.binary_search(&4),   Err(7));
assert_eq!(s.binary_search(&100), Err(13));
let r = s.binary_search(&1);
assert!(match r {
    Ok(1..=4) => true,
    _ => false,
});
```

--------------------------------

### Rust: Get Reference to Underlying Allocator

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/struct

Provides an example of accessing the underlying allocator of a vector using the `allocator` method. Note: This is a nightly-only experimental API.

```Rust
#[cfg(feature = "allocator_api")]
let allocator = vec.allocator();
```

--------------------------------

### Rust slice rsplit_mut example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/struct

Shows how to split a mutable slice into mutable subslices using a predicate, starting from the end. The matched element is excluded, and the subslices can be modified.

```rust
let mut v = [100, 400, 300, 200, 600, 500];

let mut count = 0;
for group in v.rsplit_mut(|num| *num % 3 == 0) {
    count += 1;
    group[0] = count;
}
assert_eq!(v, [3, 400, 300, 2, 600, 1]);
```

--------------------------------

### Rust Vec as_mut_slice Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Demonstrates how to get a mutable slice of the entire Vec using `as_mut_slice`. This allows in-place modification of the vector's elements through the slice.

```rust
use std::io::{self, Read};
let mut buffer = vec![0; 3];
io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();
```

--------------------------------

### Rust Option take Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/type

Demonstrates the `take` method for Option, which removes the value from the Option, leaving None in its place.

```rust
let mut x = Some(2);
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, Some(2));

let mut x: Option<u32> = None;
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, None);
```

--------------------------------

### Standard File I/O

Source: https://docs.rs/rust-htslib/latest/rust_htslib/all

Standard C library file input/output functions available through htslib.

```Rust
hts_lib::fclose
hts_lib::fdopen
hts_lib::feof
hts_lib::feof_unlocked
```

--------------------------------

### Rust: Get slice from Option<T>

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/type

Provides an example of obtaining a slice from an Option<T>, returning an empty slice if the Option is None. Also shows the inverse using `first`.

```Rust
assert_eq!(
    [Some(1234).as_slice(), None.as_slice()],
    [&[1234][..], &[][..]],
);

for i in [Some(1234_u16), None] {
    assert_eq!(i.as_ref(), i.as_slice().first());
}
```

--------------------------------

### hts_file Plugin and Scheme Information

Source: https://docs.rs/rust-htslib/latest/rust_htslib/all

Functions to check for plugins and list available file schemes supported by `hts_file`.

```Rust
use htslib::hfile_t;
use htslib::hfile_has_plugin;
use htslib::hfile_list_plugins;
use htslib::hfile_list_schemes;

// Example usage:
// let mut file: htslib::hts_file = std::mem::zeroed();
// // Check if a plugin exists...
// if htslib::hfile_has_plugin(&mut file, b"bgzf") {
//     println!("BGZF plugin is available.");
// }
// // List schemes...
// let schemes = htslib::hfile_list_schemes();
```

--------------------------------

### Rust Vec: Get Capacity

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Shows how to retrieve the current capacity of a Vec, which is the total number of elements it can hold without reallocating. Includes examples for standard Vec and Vecs with zero-sized elements.

```rust
let mut vec: Vec<i32> = Vec::with_capacity(10);
vec.push(42);
assert!(vec.capacity() >= 10);
```

```rust
#[derive(Clone)]
struct ZeroSized;

fn main() {
    assert_eq!(std::mem::size_of::<ZeroSized>(), 0);
    let v = vec![ZeroSized; 0];
    assert_eq!(v.capacity(), usize::MAX);
}
```

--------------------------------

### Rust: Get Raw Pointer to Vector Buffer

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/struct

Demonstrates obtaining a raw pointer to the vector's buffer using `as_ptr`. It includes examples of iterating through the buffer using the pointer and highlights aliasing guarantees.

```Rust
let x = vec![1, 2, 4];
let x_ptr = x.as_ptr();

unsafe {
    for i in 0..x.len() {
        assert_eq!(*x_ptr.add(i), 1 << i);
    }
}
```

```Rust
unsafe {
    let mut v = vec![0, 1, 2];
    let ptr1 = v.as_ptr();
    let _ = ptr1.read();
    let ptr2 = v.as_mut_ptr().offset(2);
    ptr2.write(2);
    // Notably, the write to `ptr2` did *not* invalidate `ptr1`
    // because it mutated a different element:
    let _ = ptr1.read();
}
```

--------------------------------

### Select Function

Source: https://docs.rs/rust-htslib/latest/rust_htslib/htslib/static

Function to monitor multiple file descriptors for readiness, `select`.

```rust
select
```

--------------------------------

### Select Function

Source: https://docs.rs/rust-htslib/latest/rust_htslib/htslib/type

Function to monitor multiple file descriptors for readiness, `select`.

```rust
select
```

--------------------------------

### Rust Vec as_ptr Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Demonstrates using `as_ptr` to get a raw pointer to a vector's buffer and iterating through elements using pointer arithmetic. It highlights the aliasing guarantee that allows safe concurrent access.

```Rust
let x = vec![1, 2, 4];\nlet x_ptr = x.as_ptr();\n\nunsafe {\n    for i in 0..x.len() {\n        assert_eq!(*x_ptr.add(i), 1 << i);\n    }\n}
```

```Rust
unsafe {\n    let mut v = vec![0, 1, 2];\n    let ptr1 = v.as_ptr();\n    let _ = ptr1.read();\n    let ptr2 = v.as_mut_ptr().offset(2);\n    ptr2.write(2);\n    // Notably, the write to `ptr2` did *not* invalidate `ptr1`\n    // because it mutated a different element:\n    let _ = ptr1.read();\n}
```

--------------------------------

### HTSlib Core Functions

Source: https://docs.rs/rust-htslib/latest/rust_htslib/htslib/fn

Essential functions for HTSlib, including opening files, detecting formats, managing threads, and logging.

```C
htsFile *hts_open(const char *fn, const char *mode);
htsFile *hts_open_format(const char *fn, const char *mode, const htsFormat *fmt);
int hts_close(htsFile *fp);
int hts_flush(htsFile *fp);
int hts_set_threads(htsFile *fp, int n_threads);
int hts_set_opt(htsFile *fp, int opt, ...);
int hts_opt_add(htsFile *fp, const char *opt_list);
int hts_opt_apply(htsFile *fp, const char *opt_list);
void hts_opt_free(hts_opt_list *opt_list);
```

```C
htsFormat hts_detect_format(const char *fn);
has_plugin hts_file_type(const char *fn);
const char *hts_format_description(const htsFormat *fmt);
const char *hts_format_file_extension(const htsFormat *fmt);
int hts_set_fai_filename(htsFile *fp, const char *fn);
int hts_set_filter_expression(htsFile *fp, const char *expr);
int hts_test_feature(htsFile *fp, int feature);
```

```C
void hts_log(int level, const char *format, ...);
void hts_set_log_level(int level);
```

```C
int hts_set_cache_size(htsFile *fp, int size);
```

```C
int hts_set_thread_pool(htsFile *fp, htsThreadPool *pool);
```

```C
int hts_parse_format(const char *str, htsFormat *fmt);
int hts_parse_opt_list(const char *str, hts_opt_list **opt_list);
int hts_parse_region(const char *str, int *tid, int *beg, int *end, int *is_rev);
int hts_parse_reg(const char *str, int *tid, int *beg, int *end, int *is_rev);
int hts_parse_reg64(const char *str, int *tid, int64_t *beg, int64_t *end, int *is_rev);
```

```C
char *hts_getline(htsFile *fp, int *fd);
char *hts_readlines(htsFile *fp, int *fd);
char *hts_readlist(htsFile *fp, int *fd);
```

```C
int hts_get_bgzfp(htsFile *fp);
htsFormat *hts_get_format(htsFile *fp);
int hts_get_log_level();
```

```C
int hts_feature_string(char *str, size_t size, const hts_feature *feature);
const char **hts_features();
```

```C
int hts_parse_decimal(const char *str, int *val);
int hts_parse_region(const char *str, int *tid, int *beg, int *end, int *is_rev);
```

```C
int hts_reglist_create(hts_reglist **reglist, const char *fname, int *tid, int *beg, int *end, int *is_rev);
void hts_reglist_free(hts_reglist *reglist);
```

```C
int hts_md5_init(hts_md5_context *ctx);
int hts_md5_update(hts_md5_context *ctx, const void *data, size_t size);
int hts_md5_final(char *hex, hts_md5_context *ctx);
int hts_md5_hex(char *hex, size_t size, const void *data, size_t size_data);
void hts_md5_reset(hts_md5_context *ctx);
void hts_md5_destroy(hts_md5_context *ctx);
```

```C
int hts_hopen(htsFile *fp, const char *fn, const char *mode);
int hfile_has_plugin(const char *scheme);
const char **hfile_list_plugins();
const char **hfile_list_schemes();
void *hfile_mem_get_buffer(htsFile *fp);
void hfile_mem_steal_buffer(htsFile *fp);
```

```C
int hflush(htsFile *fp);
char *hgets(char *s, int size, htsFile *fp);
int hisremote(htsFile *fp);
int hpeek(htsFile *fp, int c);
int hrec_add_idx(htsFile *fp, const char *idx_fname);
int hseek(htsFile *fp, hts_pos_t offset, int whence);
int hgetdelim(char **lineptr, size_t *n, int delimiter, htsFile *fp);
```

--------------------------------

### Rust: Get Element Offset in Slice (Nightly)

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Illustrates the nightly-only `element_offset` method, which returns the index of a given element reference within a slice using pointer arithmetic. It returns None if the element reference is not aligned to the start of an element. Panics for zero-sized types.

```Rust
#![feature(substr_range)]

let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

```Rust
#![feature(substr_range)]

let arr: &[[u32; 2]] = &[[0, 1], [2, 3]];
let flat_arr: &[u32] = arr.as_flattened();

let ok_elm: &[u32; 2] = flat_arr[0..2].try_into().unwrap();
let weird_elm: &[u32; 2] = flat_arr[1..3].try_into().unwrap();

assert_eq!(ok_elm, &[0, 1]);
assert_eq!(weird_elm, &[1, 2]);

assert_eq!(arr.element_offset(ok_elm), Some(0)); // Points to element 0
assert_eq!(arr.element_offset(weird_elm), None); // Points between element 0 and 1
```

--------------------------------

### Get Mutable Reference to Last Vec Item (Nightly)

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Provides a mutable reference to the last element of a Vec using the nightly-only `peek_mut` API. If the Vec is empty, it returns None. This example demonstrates its usage with an empty Vec and a Vec with elements, including modifying the last element.

```Rust
#![feature(vec_peek_mut)]
let mut vec = Vec::new();
assert!(vec.peek_mut().is_none());

vec.push(1);
vec.push(5);
vec.push(2);
assert_eq!(vec.last(), Some(&2));
if let Some(mut val) = vec.peek_mut() {
    *val = 0;
}
assert_eq!(vec.last(), Some(&0));
```

--------------------------------

### Allocate Memory and Construct Vec

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Shows how to allocate memory using the global allocator and construct a Vec<u32> from it. This example demonstrates writing data to the allocated memory and then creating a Vec from these raw parts, specifying the length and capacity.

```Rust
#![feature(box_vec_non_null)]

use std::alloc::{alloc, Layout};
use std::ptr::NonNull;

fn main() {
    let layout = Layout::array::<u32>(16).expect("overflow cannot happen");

    let vec = unsafe {
        let Some(mem) = NonNull::new(alloc(layout).cast::<u32>()) else {
            return;
        };

        mem.write(1_000_000);

        Vec::from_parts(mem, 1, 16)
    };

    assert_eq!(vec, &[1_000_000]);
    assert_eq!(vec.capacity(), 16);
}
```

--------------------------------

### Select Function

Source: https://docs.rs/rust-htslib/latest/rust_htslib/htslib/union

Function to monitor multiple file descriptors for readiness, `select`.

```rust
select
```

--------------------------------

### Rust: Unsafe Get Disjoint Mutable References by Index/Range

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Provides examples of using the unsafe `get_disjoint_unchecked_mut` method to obtain multiple mutable references to elements or sub-slices within a slice using indices or ranges. This method performs no checks and can lead to undefined behavior if indices overlap or are out of bounds.

```Rust
let x = &mut [1, 2, 4];

unsafe {
    let [a, b] = x.get_disjoint_unchecked_mut([0, 2]);
    *a *= 10;
    *b *= 100;
}
assert_eq!(x, &[10, 2, 400]);

unsafe {
    let [a, b] = x.get_disjoint_unchecked_mut([0..1, 1..3]);
    a[0] = 8;
    b[0] = 88;
    b[1] = 888;
}
assert_eq!(x, &[8, 88, 888]);

unsafe {
    let [a, b] = x.get_disjoint_unchecked_mut([1..=2, 0..=0]);
    a[0] = 11;
    a[1] = 111;
    b[0] = 1;
}
assert_eq!(x, &[1, 11, 111]);
```

--------------------------------

### Rust: Get mutable raw pointer to slice buffer

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/struct

Returns a mutable raw pointer to the start of the slice's data. Similar to `as_ptr`, the caller must manage the lifetime of the slice and pointer validity. This pointer allows for modification of the slice's contents via pointer arithmetic.

```Rust
pub fn as_mut_ptr(&mut self) -> *mut T
```

--------------------------------

### Select Function

Source: https://docs.rs/rust-htslib/latest/rust_htslib/htslib/fn

Function to monitor multiple file descriptors for readiness, `select`.

```rust
select
```

--------------------------------

### Rust Slice rotate_right on Subslice Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Provides an example of performing a right rotation on a sub-slice.

```Rust
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
a[1..5].rotate_right(1);
assert_eq!(a, ['a', 'e', 'b', 'c', 'd', 'f']);
```

--------------------------------

### BGZF Indexing and Threading

Source: https://docs.rs/rust-htslib/latest/rust_htslib/all

Utilities for building, dumping, and loading BGZF indexes, as well as managing thread pools and cache sizes for performance optimization.

```Rust
hts_lib::bgzf_index_build_init
hts_lib::bgzf_index_dump
hts_lib::bgzf_index_dump_hfile
hts_lib::bgzf_index_load
hts_lib::bgzf_index_load_hfile
hts_lib::bgzf_mt
hts_lib::bgzf_set_cache_size
hts_lib::bgzf_thread_pool
```

--------------------------------

### Rust partition_point example for insertion

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Demonstrates how to use partition_point to find the correct insertion index for an element in a sorted vector to maintain the sort order. It shows inserting an element and verifying the resulting sorted vector.

```rust
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let num = 42;
let idx = s.partition_point(|&x| x <= num);
// If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to
// `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` will allow `insert`
// to shift less elements.
s.insert(idx, num);
assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);
```

--------------------------------

### Rust: Get slice length

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Demonstrates how to get the number of elements in a slice using the `len` method.

```Rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### Create BAM Header - rust-htslib

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/header/struct

Creates a new, empty BAM header. This is the starting point for building a header from scratch.

```Rust
pub fn new() -> Self
```

--------------------------------

### Rust RecordBuffer::fetch Method

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/buffer/struct

Fills the RecordBuffer with variants within a specified genomic window (chrom, start, end). The start coordinate must be greater than the previous fetch's start. Coordinates are 0-based with an exclusive end. It returns the number of records added and deleted.

```Rust
pub fn fetch( &mut self, chrom: &[u8], start: u64, end: u64, ) -> Result<(usize, usize)>
```

--------------------------------

### htslib: Indexing Functions (SAM/BAM/VCF)

Source: https://docs.rs/rust-htslib/latest/rust_htslib/all

Provides functions for building, loading, and managing indexes for SAM, BAM, and VCF files.

```Rust
htslib::sam_idx_init
htslib::sam_idx_save
htslib::sam_index_build
htslib::sam_index_build2
htslib::sam_index_build3
htslib::sam_index_load
htslib::sam_index_load2
htslib::sam_index_load3
htslib::tbx_destroy
htslib::tbx_index
htslib::tbx_index_build
htslib::tbx_index_build2
htslib::tbx_index_build3
htslib::tbx_index_load
htslib::tbx_index_load2
htslib::tbx_index_load3
htslib::tbx_name2id
htslib::tbx_readrec
htslib::tbx_seqnames
```

--------------------------------

### Get TypeId for SyncedReader

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/synced/struct

Implements the Any trait for SyncedReader, providing a method to get the TypeId of the instance. This is useful for runtime type identification.

```Rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Rust Vec Clone From Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Demonstrates the `clone_from` method for efficiently copying the contents of one Vec to another, potentially avoiding reallocations. It shows how to use it and verify that no reallocation occurred.

```rust
let x = vec![5, 6, 7];\nlet mut y = vec![8, 9, 10];\nlet yp: *const i32 = y.as_ptr();\n\ny.clone_from(&x);\n\n// The value is the same\nassert_eq!(x, y);\n\n// And no reallocation occurred\nassert_eq!(yp, y.as_ptr());\n
```

--------------------------------

### Rust: Get mutable reference to first element

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Illustrates how to get a mutable reference to the first element of a slice using `first_mut()`, allowing modification.

```Rust
let x = &mut [0, 1, 2];

if let Some(first) = x.first_mut() {
    *first = 5;
}
assert_eq!(x, &[5, 1, 2]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.first_mut());
```

--------------------------------

### Rust Option::is_none_or Method Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/type

Provides an example of the `is_none_or` method in Rust, which checks if an `Option` is `None` or if its contained value satisfies a given predicate.

```Rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_none_or(|x| x > 1), true);

let x: Option<u32> = Some(0);
assert_eq!(x.is_none_or(|x| x > 1), false);

let x: Option<u32> = None;
assert_eq!(x.is_none_or(|x| x > 1), true);

let x: Option<String> = Some("ownership".to_string());
assert_eq!(x.as_ref().is_none_or(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Rust Slice binary_search Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bam/record/struct

Provides an example of using `binary_search` on a sorted slice to find an element. It returns `Ok(index)` if found, or `Err(insertion_point)` if not found.

```rust
let v = &[10, 40, 30]; // Note: For binary_search, this slice should be sorted.
// Example assuming a sorted slice:
let sorted_v = &[10, 20, 30, 40, 50];
assert_eq!(sorted_v.binary_search(&30), Ok(2));
assert_eq!(sorted_v.binary_search(&25), Err(2));
```

--------------------------------

### Rust Result unwrap_or_default() Method Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/errors/type

Demonstrates how unwrap_or_default() returns the Ok value or the default value for the type if the Result is an Err. Includes an example parsing strings to integers.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### Rust Vec: Example - Reconstructing from Raw Parts

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/header/type

Demonstrates reconstructing a Vec from raw memory using `from_raw_parts_in` after manually managing memory and data. It shows how to extract parts of an existing Vec, modify the underlying data, and then rebuild the Vec.

```rust
#![feature(allocator_api)]

use std::alloc::System;

use std::ptr;
use std::mem;

let mut v = Vec::with_capacity_in(3, System);
v.push(1);
v.push(2);
v.push(3);

// Prevent running `v`'s destructor so we are in complete control
// of the allocation.
let mut v = mem::ManuallyDrop::new(v);

// Pull out the various important pieces of information about `v`
let p = v.as_mut_ptr();
let len = v.len();
let cap = v.capacity();
let alloc = v.allocator();

unsafe {
    // Overwrite memory with 4, 5, 6
    for i in 0..len {
        ptr::write(p.add(i), 4 + i);
    }

    // Put everything back together into a Vec
    let rebuilt = Vec::from_raw_parts_in(p, len, cap, alloc.clone());
    assert_eq!(rebuilt, [4, 5, 6]);
}
```

--------------------------------

### Get Slice as Array Reference (Rust)

Source: https://docs.rs/rust-htslib/latest/rust_htslib/bcf/record/struct

Attempts to get a reference to the underlying array if the requested size `N` matches the slice's length. This is an experimental, nightly-only API.

```Rust
pub fn as_array<const N: usize>(&self) -> Option<&[T; N]>
```

--------------------------------

### Temporary File Creation

Source: https://docs.rs/rust-htslib/latest/rust_htslib/htslib/static

Functions for creating temporary files and directories, including `mkdtemp`, `mkstemp`, `mkstemps`, and `mktemp`.

```rust
mkdtemp
mkstemp
mkstemps
mktemp
```

--------------------------------

### Rust Result into_ok() Method Example

Source: https://docs.rs/rust-htslib/latest/rust_htslib/errors/type

Demonstrates the nightly-only experimental API into_ok(), which returns the Ok value without panicking. It's a safeguard against future error type changes.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### Temporary File Creation

Source: https://docs.rs/rust-htslib/latest/rust_htslib/htslib/fn

Functions for creating temporary files and directories, including `mkdtemp`, `mkstemp`, `mkstemps`, and `mktemp`.

```rust
mkdtemp
mkstemp
mkstemps
mktemp
```
Tokens:
Raw