# to_snake_case

The primary use for this crate is to transform camelCase and PascalCase formats
to snake_case. This is especially useful for transforming `trait` and `struct` 
names to be used for generating module and function names.

Common patterns where this is detected in rust are some of the traits such as
`TryFrom` and `TryInto` where their function names are `try_from` and `try_into`
 respectively.

This crate provides the implementation of the trait `ToSnakeCase` for all 
`AsRef<str>`, where all individual words are transformed into snake case.

A word (in this context) would be considered a combination of letters that are
separated by spaces. This means that "ThrowItToMe" is considered a single word,
but can still be transformed into the appropriate snake case "throw_it_to_me".
Words separated by spaces will not be joined with underscores '_'.

Each call to `to_snake_case()` provides a newly allocated string containing the
transformed string.

```rust
use to_snake_case::ToSnakeCase;

assert_eq!("to_snake_case", "ToSnakeCase".to_snake_case());
assert_eq!("to_snake_case", "toSnakeCase".to_snake_case());
assert_eq!("the_children_are_wrong - seymour skinner", "theChildrenAreWrong - Seymour Skinner".to_string().to_snake_case());
```

## Acronyms

`to_snake_case` is capable of detecting acronyms inserted before, in between, or
after words, and transforming it as intended (assuming the tailing words
are capitalized).

```rust
use to_snake_case::ToSnakeCase;

assert_eq!("to_snake_case", "TOSnakeCASE".to_snake_case());
assert_eq!("to_snake_case", "ToSNAKECase".to_snake_case());

assert_eq!("canon_d", "CanonD".to_snake_case());
```

### Limitiations with Acronyms

It is not possible to recreate snake cases properly under conditions
where multiple acronyms are chained together. This is because it is not possible to 
logically identify where the start and end of the next word is, even with a dictionary.
Take for example the letters `"TOME"` - should it be transformed into `"tome"` or `"to_me"`?
Acronyms are also context specific and don't apply universally.

In `to_snake_case`, all sequenced capital letters will be transformed into lowercase 
without underscores as if it were one acronym/word, unless there was a precursor 
that makes it possible to identify a word (such as a lower case letter).

```rust
use to_snake_case::ToSnakeCase;

assert_eq!("tome", "TOME".to_snake_case());
```

# Build Dependencies
This was developed on rust 1.69.0-nightly with `#![feature(let_chains)]`.

# License
*__Copyright 2023 Tony Nguyen__*

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

> [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.