ENH: Implement core/strings/wrap method
State: closed

This patch implements the str_wrap function within core/strings. The implementation follows 
the behavior of R's stringr library. When a string is 'wrap'ped, the return value will be a 
paragraph with lines of max(word length, width) length.

Example:

``` python
>>> str_wrap(Series([u'line to be wrapped', u'another line to be wrapped']), width=12)
Series([u'line to be\nwrapped', u'another\nline to be\nwrapped'])
```


Labels:
name: Enhancement
name: Strings
description: String extension data type and string data

Comments:
can you show an example in the top fo the PR of using this.

Also need to add to the documentation in `basics.rst` (mention this function, don't need an example)

also add to `comparison_with_r.rst`

Couldn't this leverage the `textwrap` module?

I've changed the implementation to use the `textwrap` module and expanded the documentation to reference many of the parameters `wrap` can now use.

I've also added a mention of `wrap` to basics.rst.

`comparison_with_r.rst` does not currently discuss any vectorized string operations. I think a new section to that file (to discuss all vectorized string operations) would be a PR by itself.

@jeffreystarr pls rebase this

@jeffreystarr - I'd also like to make width a positional argument, which lets you do something like: `df.str.wrap(30)`, which has a nice clarity to it vs. `df.str.wrap(width=30)`. I'd suggest `width` should be required, because I'd say there isn't really a "default" width that really makes sense. This is a pretty minimal change, just needs to be `def str_wrap(self, width, **kwargs)` in each function.

As an aside, this previously was just NotImplemented right? So there's no issue with forcing width to be passed?

You are correct - it was previously NotImplemented. There is no impact to
existing code by making width required.

On Sat, Apr 5, 2014 at 7:41 PM, Jeff Tratner notifications@github.comwrote:

> @jeffreystarr https://github.com/jeffreystarr - I'd also like to make
> width a positional argument, which lets you do something like:
> df.str.wrap(30), which has a nice clarity to it vs. df.str.wrap(width=30).
> I'd suggest width should be required, because I'd say there isn't really
> a "default" width that really makes sense. This is a pretty minimal change,
> just needs to be def str_wrap(self, width, **kwargs) in each function.
> 
> As an aside, this previously was just NotImplemented right? So there's no
> issue with forcing width to be passed?
> 
> ## 
> 
> Reply to this email directly or view it on GitHubhttps://github.com/pydata/pandas/pull/6705#issuecomment-39655369
> .

@jeffreystarr - great, then if it's okay with you, I'd suggest changing `width` to be required.

@jeffreystarr this looks good

can you can squash down to 1 commit would be great

I added some comments on the docstring.

@jeffreystarr @jreback @jtratner What do you think of my previous comment? To follow by default python's default values (for the kwargs) instead of R's (so follow the default values of textwrap.TextWrapper)? And then putting a note explaining the difference with R, and provide an example with the specified kwargs you need to mimic R's behaviour?

I think we should follow python's Textwrapper args (and just who the R differences). Most often someone would refer to the TextWrapper docs, so I agree with @jorisvandenbossche 

@jeffreystarr ?

I expect to update the PR April 22

can you rebase?

hmm...looks like you somehow rebase to a different head

```
git rebase -i origin/master
```

should do the trick

if it doesn't, then:
- pull master
- create a new branch
- `git cherry-pick <commits>` (you must pick 1 by one, starting with the oldest
  the are YOUR commits (I think you have 6)

then this 'starts' you over

you can then

`git push yourforck yourbranch -f`

and it will erase this and replace with your new

small note on the advice of @jreback: be sure that `origin` (if this is your fork) is also updated, or you can rebase on `upstream` (if this is `pydata/pandas`):

```
git fetch upstream
git rebase upstream/master
```

closing in favor of #6999