mask_cube() both acts in-place and returns the Cube

[SimonPeatman]

This is following a post I made on the Google Group: https://groups.google.com/forum/#!topic/scitools-iris/eZwzmiZO3UU

There has been some discussion in the past about whether functions acting on Cubes should modify the Cube in-place or return a new Cube (see #3430 and #2615). I find the behaviour of iris.util.mask_cube() surprising in that it does both. Seeing it returning a Cube, I was surprised to find my original Cube also masked:

>>> cube = iris.cube.Cube(range(5))
>>> points_to_mask = [False, True, False, False, True]
>>> cube2 = iris.util.mask_cube(cube, points_to_mask)
>>> cube.data
masked_array(data=[0, --, 2, 3, --],
             mask=[False,  True, False, False,  True],
       fill_value=999999)

Moreover, the returned Cube is the same object as the one I started with:

>>> cube2 is cube
True

I suggest mask_cube() should either modify the Cube in-place or return a new Cube, not both.