darwinscope

https://docs.rs/darwinscope
Admin
darwinscope is a Rust library for statically analyzing Mach-O binaries and decoding the rich...
Tokens:334,604
Snippets:3,048
Trust Score:9.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### map example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how to use map to apply a function to the Ok value of a Result. The example parses each line of a string and prints the number multiplied by two.

```rust
let line = "1\n2\n3\n4\n";

for num in line.lines() {
    match num.parse::<i32>().map(|i| i * 2) {
        Ok(n) => println!("{n}"),
        Err(..) => {}
    }
}
```

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

### as_mut example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Demonstrates using as_mut to get mutable references to the Ok or Err values. The example defines a mutate function that modifies the contained value based on the variant.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

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

### unwrap_or example: returns Ok value or default

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Demonstrates unwrap_or, which returns the contained Ok value or a provided default. The example shows both Ok and Err cases.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

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

### is_err_and example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how to use is_err_and to check if a Result is Err and the error value matches a predicate. The example uses std::io::Error and demonstrates true/false cases for different error kinds and an Ok case.

```rust
use std::io::{Error, ErrorKind};

let x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);

let x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, Error> = Ok(123);
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

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

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

### ok example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Demonstrates converting a Result to an Option using the ok method. Shows that Ok becomes Some and Err becomes None.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

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

### as_ref example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how to convert a Result to a Result of references using as_ref. The original Result is left in place.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

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

### Example: is_ok() on Result<T, E>

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Returns true if the result is Ok.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

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

### map_or_else example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how to use map_or_else to apply a fallback function to Err or a function to Ok. The example uses a constant k for the fallback.

```rust
let k = 21;

let x : Result<_, &str> = Ok("foo");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);

let x : Result<&str, _> = Err("bar");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);
```

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

### unwrap_or_else example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how to use unwrap_or_else to provide a fallback value when the Result is Err.

```rust
assert_eq!(Ok(2).unwrap_or_else(count), 2);
assert_eq!(Err("foo").unwrap_or_else(count), 3);
```

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

### or example: returns res if Err, otherwise Ok value

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Demonstrates the or method, which returns the provided res if self is Err, otherwise returns the Ok value of self. The example shows four cases covering combinations of Ok and Err.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```

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

### IntoIterator example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how to iterate over a Result, yielding one value if Ok and none if Err.

```rust
let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);

let x: Result<u32, &str> = Err("nothing!");
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, []);
```

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

### FromIterator example: subtract with underflow check

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how to collect an iterator of Results into a Result<Vec, E>, stopping at the first Err.

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

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

### unwrap_err_unchecked example (Err case)

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how to use unwrap_err_unchecked to get the Err value without checking for Ok.

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");
```

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

### Segment::initprot

Source: https://docs.rs/darwinscope/latest/src/darwinscope/segment.rs.html

Returns the initial VM protection flags.

```APIDOC
## Segment::initprot

### Description
Returns the initial VM protection (`VM_PROT_*`).

### Method
`pub fn initprot(&self) -> u32`

### Parameters
None.

### Returns
- `u32` - The initial VM protection flags.

### Example
```rust
let prot = segment.initprot();
```
```

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

### unwrap_unchecked example (Ok case)

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how to use unwrap_unchecked to get the Ok value without checking for Err. Calling on Err is undefined behavior.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

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

### ClassRo::instance_start

Source: https://docs.rs/darwinscope/latest/src/darwinscope/objc/class.rs.html

Returns the `instanceStart` offset where this class's ivars begin in the instance.

```APIDOC
## ClassRo::instance_start

### Description
Returns the `instanceStart` offset where this class's ivars begin in the instance.

### Method
`pub fn instance_start(&self) -> u32`

### Parameters
None.

### Returns
- **u32** - The offset where this class's ivars begin.

```

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

### and_then example: chaining fallible operations

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how and_then chains operations that may return Err. The first example uses a function sq_then_to_string that returns Result<String, &str>. The second example uses metadata() and modified() to demonstrate error handling with io::ErrorKind::NotFound.

```rust
assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
```

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

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

### swift()

Source: https://docs.rs/darwinscope/latest/src/darwinscope/binary.rs.html

Builds a SwiftRuntime walker for Swift 5 runtime metadata. Returns None if the image has no Swift content or is 32-bit.

```APIDOC
## swift()

### Description
Aggregate Swift 5 runtime walker. Returns `None` when the image carries no Swift content (none of `__swift5_types`, `__swift5_protos`, `__swift5_proto`, `__swift5_fieldmd` is present) or when the slice is 32-bit - the v0.1 Swift walker is 64-bit only. On success the returned `SwiftRuntime` owns parsed-once metadata (cached section lookups, segment table for VA translation, chained-fixup rebase / bind indices) so iterators can drain it independently of the originating `MachoBinary` borrow.

### Method
swift

### Signature
`pub fn swift(&self) -> Option<SwiftRuntime<'a>>`

### Parameters
- `self` (reference) - The `MachoBinary` instance.

### Returns
- `Option<SwiftRuntime<'a>>` - `Some` with a runtime walker on success, `None` if no Swift content or 32-bit slice.
```

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

### expect method usage and recommended style

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Returns the contained Ok value or panics. Includes examples of basic usage and recommended message style.

```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`");
```

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

### objc()

Source: https://docs.rs/darwinscope/latest/src/darwinscope/binary.rs.html

Builds an ObjcRuntime walker for the Mach-O binary. Returns None if the image carries no Objective-C metadata or is 32-bit.

```APIDOC
## objc()

### Description
Builds an `ObjcRuntime` walker for the Mach-O binary. Returns `None` when the image carries no Objective-C metadata or when the slice is 32-bit (the v0.1 walker is 64-bit only).

### Method
objc

### Signature
`pub fn objc(&self) -> Option<ObjcRuntime<'a>>`

### Parameters
- `self` (reference) - The `MachoBinary` instance.

### Returns
- `Option<ObjcRuntime<'a>>` - `Some` with a runtime walker on success, `None` if no Objective-C metadata or 32-bit slice.
```

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

### unwrap_or_else example: computes value from closure

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows unwrap_or_else, which returns the contained Ok value or computes it from a closure. The example defines a function count that returns the length of a string.

```rust
fn count(x: &str) -> usize { x.len() }
```

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

### Product example: multiply parsed numbers from vector

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Uses the Product implementation for Result to multiply parsed numbers from a vector of strings. If any parse fails, the operation returns Err.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

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

### map_or_default example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Demonstrates using map_or_default to apply a function to Ok or return the default value for the type U on Err. The example shows a length calculation and default 0.

```rust
let x: Result<_, &str> = Ok("foo");
let y: Result<&str, _> = Err("bar");

assert_eq!(x.map_or_default(|x| x.len()), 3);
assert_eq!(y.map_or_default(|y| y.len()), 0);
```

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

### or_else example: control flow based on result values

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Shows how or_else calls a closure if the result is Err, otherwise returns the Ok value. The example uses functions sq and err to demonstrate chaining or_else calls.

```rust
fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
fn err(x: u32) -> Result<u32, u32> { Err(x) }

assert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));
assert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));
assert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));
assert_eq!(Err(3).or_else(err).or_else(err), Err(3));
```

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

### err example

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Demonstrates converting a Result to an Option using the err method. Shows that Ok becomes None and Err becomes Some with the error value.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.err(), None);

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.err(), Some("Nothing here"));
```

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

### Example: is_err() on Result<T, E>

Source: https://docs.rs/darwinscope/latest/darwinscope/error/type.Result.html

Returns true if the result is Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

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

### Rebase::segment_offset

Source: https://docs.rs/darwinscope/latest/darwinscope/fixup/struct.Rebase.html

Returns the byte offset of the rebase slot from the start of its segment.

```APIDOC
## Rebase::segment_offset

### Description
Returns the byte offset of the rebase slot from the start of its segment.

### Method
pub fn segment_offset(&self) -> u64

### Parameters
None

### Returns
- **u64** - The segment offset.

```

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

### Method::implementation

Source: https://docs.rs/darwinscope/latest/darwinscope/objc/struct.Method.html

Returns the IMP target virtual address (post-PAC-strip), or None for abstract methods.

```APIDOC
## Method::implementation

### Description
Returns the IMP target VA (post-PAC-strip). `None` for abstract methods - protocols emit method declarations with `imp = 0`.

### Method
`pub fn implementation(&self) -> Option<u64>`

### Parameters
None

### Returns
- `Option<u64>` - The IMP target VA, or `None` for abstract methods.

```

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

### Header::min_os

Source: https://docs.rs/darwinscope/latest/src/darwinscope/binary.rs.html

Returns the minimum OS version this image targets, preferring `LC_BUILD_VERSION` and falling back to legacy `LC_VERSION_MIN_*`.

```APIDOC
## Header::min_os

### Description
Returns the minimum OS version this image targets, preferring `LC_BUILD_VERSION` (modern) and falling back to `LC_VERSION_MIN_*` (legacy). Only the first match wins.

### Method
min_os

### Signature
pub fn min_os(&self) -> Option<MinOsVersion>

### Parameters
None

### Returns
- **Option<MinOsVersion>** - The minimum OS version, or `None` if not present.

```

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

### PrespecializationIter::step_by

Source: https://docs.rs/darwinscope/latest/darwinscope/swift/struct.PrespecializationIter.html

Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

```APIDOC
## PrespecializationIter::step_by

### Description
Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

### Method
`fn step_by(self, step: usize) -> StepBy<Self>`

### Parameters
- `step` (usize) - The step amount.

### Returns
- `StepBy<Self>` - A new iterator that steps by the given amount.

```

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

### pub fn swift(&self) -> Option<SwiftRuntime<'a>>

Source: https://docs.rs/darwinscope/latest/darwinscope/binary/struct.MachoBinary.html

Returns an aggregate Swift 5 runtime walker. Returns `None` when the image carries no Swift content or when the slice is 32-bit (v0.1 Swift walker is 64-bit only).

```APIDOC
## pub fn swift(&self) -> Option<SwiftRuntime<'a>>

### Description
Aggregate Swift 5 runtime walker. Returns `None` when the image carries no Swift content (none of `__swift5_types`, `__swift5_protos`, `__swift5_proto`, `__swift5_fieldmd` is present) or when the slice is 32-bit - the v0.1 Swift walker is 64-bit only. On success the returned `SwiftRuntime` owns parsed-once metadata (cached section lookups, segment table for VA translation, chained-fixup rebase / bind indices) so iterators can drain it independently of the originating `MachoBinary` borrow.

### Method
pub fn swift(&self) -> Option<SwiftRuntime<'a>>

### Parameters
None.

### Returns
- **Option<SwiftRuntime<'a>>** - Aggregate Swift 5 runtime walker, or `None` if not applicable.
```

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

### BindIter::step_by

Source: https://docs.rs/darwinscope/latest/darwinscope/fixup/struct.BindIter.html

Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

```APIDOC
## BindIter::step_by

### Description
Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

### Method
step_by

### Signature
fn step_by(self, step: usize) -> StepBy<Self>

### Parameters
- **self** (self) - Required - The iterator instance.
- **step** (usize) - Required - The step size.

### Returns
- **StepBy<Self>** - An iterator that steps by the given amount.

```
Tokens:
Raw