class_docstr: String Methods operating on object-dtype ndarrays.
class_docstr_tok: ["String","Methods","operating","on","object-dtype","ndarrays","."]
docstr: Map a callable over valid elements of the array.
  
  Parameters
  ----------
  f : Callable
      A function to call on each non-NA element.
  na_value : Scalar, optional
      The value to set for NA values. Might also be used for the
      fill value if the callable `f` raises an exception.
      This defaults to ``self._str_na_value`` which is ``np.nan``
      for object-dtype and Categorical and ``pd.NA`` for StringArray.
  dtype : Dtype, optional
      The dtype of the result array.
  convert : bool, default True
      Whether to call `maybe_convert_objects` on the resulting ndarray
docstr_tok: ["Map","a","callable","over","valid","elements","of","the","array",".","Parameters","--","--","--","--","--","f",":","Callable","A","function","to","call","on","each","non-NA","element",".","na_value",":","Scalar",",","optional","The","value","to","set","for","NA","values",".","Might","also","be","used","for","the","fill","value","if","the","callable","`","f","`","raises","an","exception",".","This","defaults","to","``","self._str_na_value","``","which","is","``","np.nan","``","for","object-dtype","and","Categorical","and","``","pd.NA","``","for","StringArray",".","dtype",":","Dtype",",","optional","The","dtype","of","the","result","array",".","convert",":","bool",",","default","True","Whether","to","call","`","maybe_convert_objects","`","on","the","resulting","ndarray"]
code: def _str_map(
      self,
      f,
      na_value=None,
      dtype: NpDtype | None = None,
      convert: bool = True,
  ):
      """
      Map a callable over valid elements of the array.
  
      Parameters
      ----------
      f : Callable
          A function to call on each non-NA element.
      na_value : Scalar, optional
          The value to set for NA values. Might also be used for the
          fill value if the callable `f` raises an exception.
          This defaults to ``self._str_na_value`` which is ``np.nan``
          for object-dtype and Categorical and ``pd.NA`` for StringArray.
      dtype : Dtype, optional
          The dtype of the result array.
      convert : bool, default True
          Whether to call `maybe_convert_objects` on the resulting ndarray
      """
      if dtype is None:
          dtype = np.dtype("object")
      if na_value is None:
          na_value = self._str_na_value
  
      if not len(self):
          return np.array([], dtype=dtype)
  
      arr = np.asarray(self, dtype=object)
      mask = isna(arr)
      map_convert = convert and not np.all(mask)
      try:
          result = lib.map_infer_mask(
              arr, f, mask.view(np.uint8), map_convert
          )
      except (TypeError, AttributeError) as err:
          # Reraise the exception if callable `f` got wrong number of args.
          # The user may want to be warned by this, instead of getting NaN
          p_err = (
              r"((takes)|(missing)) (?(2)from \d+ to )?\d+ "
              r"(?(3)required )positional arguments?"
          )
  
          if len(err.args) >= 1 and re.search(p_err, err.args[0]):
              # FIXME: this should be totally avoidable
              raise err
  
          def g(x):
              # This type of fallback behavior can be removed once
              # we remove object-dtype .str accessor.
              try:
                  return f(x)
              except (TypeError, AttributeError):
                  return na_value
  
          return self._str_map(g, na_value=na_value, dtype=dtype)
      if not isinstance(result, np.ndarray):
          return result
      if na_value is not np.nan:
          np.putmask(result, mask, na_value)
          if convert and result.dtype == object:
              result = lib.maybe_convert_objects(result)
      return result
  
imports: from __future__ import annotations
  import functools
  import re
  import sys
  import textwrap
  from typing import TYPE_CHECKING, Callable, Literal
  import unicodedata
  import numpy
  from pandas._libs import lib
  import pandas._libs.missing
  import pandas._libs.ops
  from pandas._typing import NpDtype, Scalar
  from pandas.core.dtypes.common import is_scalar
  from pandas.core.dtypes.missing import isna
  from pandas.core.strings.base import BaseStringArrayMethods
label_desc: Use image node_id 2 for calling the ObjectStringArrayMixin obj's underlying member method code with example usage: obj._str_map(f, na_value, dtype, convert) and returns: result, np, result, self, f, na_value