Elaborate function usage, add examples and fix bug

Author: makbigc

pandas/core/dtypes/cast.py

@@ -167,9 +167,12 @@ def trans(x):  # noqa
     return result
 
 
-def maybe_upcast_putmask(result, mask, other):
+def maybe_upast_putmask(result, mask, other):
     """
-    A safe version of putmask that potentially upcasts the result
+    A safe version of putmask that potentially upcasts the result.
+    The result is replaced with the first N elements of other,
+    where N is the number of True values in mask.
+    If the length of other is shorter than N, other will be repeated.
 
     Parameters
     ----------
@@ -185,8 +188,18 @@ def maybe_upcast_putmask(result, mask, other):
     result : ndarray
     changed : boolean
         Set to true if the result array was upcasted
+
+    Examples
+    --------
+    >>> result, _ = maybe_upcast_putmask(np.arange(1,6),
+    np.array([False, True, False, True, True]), np.arange(21,23))
+    >>> result
+    array([1, 21, 3, 22, 21])
     """
 
+    if not isinstance(result, np.ndarray):
+        raise ValueError("The result input must be a ndarray.")
+
     if mask.any():
         # Two conversions for date-like dtypes that can't be done automatically
         # in np.place:
@@ -241,7 +254,7 @@ def changeit():
             # we have an ndarray and the masking has nans in it
             else:
 
-                if isna(other[mask]).any():
+                if isna(other).any():
                     return changeit()
 
         try: