binstring 0.1.5

Store binary data as a string
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

# binstring

A Rust library for storing binary data as a string.

[![Crates.io](https://img.shields.io/crates/v/binstring)](https://crates.io/crates/binstring)
[![Documentation](https://docs.rs/binstring/badge.svg)](https://docs.rs/binstring)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Description

`binstring` provides a `BinString` type that wraps a `String` and provides conversion methods between binary data and strings. It's particularly useful when you need to store binary data in a string format while maintaining the ability to access it as both a string and bytes.

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
binstring = "0.1"
```

## Usage

### Basic Usage

```rust
use binstring::BinString;

// Create from a string
let bin_str = BinString::new("hello");
assert_eq!(bin_str.as_str(), "hello");

// Create from bytes
let bytes = vec![104, 101, 108, 108, 111]; // "hello" in bytes
let bin_str = BinString::from_bytes(bytes);
assert_eq!(bin_str.as_bytes(), &[104, 101, 108, 108, 111]);
```

### Converting Between Types

```rust
use binstring::BinString;

// From String
let s = String::from("hello");
let bin_str = BinString::from(s);

// From &str
let bin_str = BinString::from("hello");

// From Vec<u8>
let bytes = vec![104, 101, 108, 108, 111];
let bin_str = BinString::from(bytes);

// From &[u8]
let bytes = &[104, 101, 108, 108, 111];
let bin_str = BinString::from(bytes);
```

### Accessing Data

```rust
use binstring::BinString;

let bin_str = BinString::new("hello");

// As string slice (only safe with valid UTF-8)
assert_eq!(bin_str.as_str(), "hello");

// As byte slice (always safe)
assert_eq!(bin_str.as_bytes(), &[104, 101, 108, 108, 111]);

// Get length
assert_eq!(bin_str.len(), 5);

// Check if empty
assert!(!bin_str.is_empty());
```

### Byte-Level Operations

```rust
use binstring::BinString;

let s = BinString::new("hello");

// Concatenation
let s2 = BinString::new(" world");
assert_eq!(s.concat(&s2).as_bytes(), b"hello world");

// Slicing
assert_eq!(s.slice(1..4).as_bytes(), b"ell");

// Pattern matching
assert!(s.starts_with(b"he"));
assert!(s.ends_with(b"lo"));
assert!(s.contains(b"el"));
assert_eq!(s.find(b"el"), Some(1));
assert_eq!(s.rfind(b"l"), Some(3));

// Byte replacement
assert_eq!(s.replace(b'l', b'x').as_bytes(), b"hexxo");
```

### Converting Back

```rust
use binstring::BinString;

let bin_str = BinString::new("hello");

// Get the underlying String
let s = bin_str.unwrap();
assert_eq!(s, "hello");

// Or use From trait
let s: String = bin_str.into();
assert_eq!(s, "hello");
```

## Safety

While storing invalid UTF-8 in a `String` is perfectly safe, attempting to treat the string as valid UTF-8 (for example, by displaying it or using string operations that assume valid UTF-8) may lead to undefined behavior.

Most operations in this library work at the byte level and are safe to use with any binary data. However, some methods like `trim()` assume valid UTF-8 and should only be used when you are certain the data is valid UTF-8.