help mata mm_pieces()
-------------------------------------------------------------------------------

Title

    mm_pieces() -- Break a string into pieces


Syntax

        string rowvector mm_pieces(str, length [, nobreak])

        real matrix      mm_npieces(S, length [, nobreak])

        real scalar      _mm_npieces(str, length [, nobreak])


    where

          str:  string scalar containing string to be broken

       length:  real scalar specifying maximum length of pieces

      nobreak:  real scalar indicating that long words are not to be broken

            S:  string matrix S


Description

    mm_pieces() breaks a string into pieces of roughly the specified length.
    Words are not broken unless they are longer than the specified length.
    nobreak!=0 indicates that words are not to be broken even if they are
    longer than the specified length.

    mm_npieces() and _mm_npieces() return the number of pieces a string would
    be broken into by mm_pieces(). mm_npieces() may be applied to a sting
    matrix in which case it returns element-by-element results. _mm_npieces()
    is equivalent to cols(mm_pieces()) but is faster and consumes less
    memory.


Remarks

    Example:

        : s = "A string to be cut into pieces"
        
        : mm_pieces(s, 10)
                       1           2           3           4
            +-------------------------------------------------+
          1 |   A string   to be cut        into      pieces  |
            +-------------------------------------------------+
        
        : _mm_npieces(s,10)
          4
        

Conformability

    mm_pieces(str, length, nobreak):
           str:  1 x 1
        length:  1 x 1
       nobreak:  1 x 1
        result:  1 x 1
        
    mm_npieces(S, length, nobreak):
             S:  r x c
        length:  1 x 1
       nobreak:  1 x 1
        result:  r x c
        
    _mm_npieces(str, length, nobreak):
           str:  1 x 1
        length:  1 x 1
       nobreak:  1 x 1
        result:  1 x 1


Diagnostics

    Leading and trailing blanks are removed from the returned pieces. One
    piece is returned if length is missing. Pieces of length 1 will be
    returned if length<1.


Source code

    mm_pieces.mata


Author

    Ben Jann, ETH Zurich, jannb@ethz.ch


Also see

    Online:  help for [M-4] string, moremata