DataFrame (Stata-Java API)

java.lang.Object
- com.stata.sfi.DataFrame

```
public final class DataFrame
extends Object
```
This class provides access to a Stata data frame. A data frame is a private instance of a Stata dataset. All variable and observation numbering begins at 1 unless otherwise stated. All methods are not thread-safe unless otherwise stated.

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static int`	`addVarByte(String rname, String vname)` Add a variable of type byte to a data frame.
`static int`	`addVarDouble(String rname, String vname)` Add a variable of type double to a data frame.
`static int`	`addVarFloat(String rname, String vname)` Add a variable of type float to a data frame.
`static int`	`addVarInt(String rname, String vname)` Add a variable of type int to a data frame.
`static int`	`addVarLong(String rname, String vname)` Add a variable of type long to a data frame.
`static int`	`addVarStr(String rname, String vname, int length)` Add a variable of type str to a data frame.
`static int`	`addVarStrL(String rname, String vname)` Add a variable of type strL to a data frame.
`static int`	`allocate(String rname)` Allocate a new data frame.
`static int`	`allocateStrL(StrLConnector dsc, long size)` Allocate a strL so that a buffer can be stored using `writeBytes`; the contents of the strL will not be initialized.
`static int`	`allocateStrL(StrLConnector dsc, long size, boolean binary)` Allocate a strL so that a buffer can be stored using `writeBytes`; the contents of the strL will not be initialized.
`static int`	`free(String rname)` Free a previously allocated data frame.
`static double`	`getNum(String rname, int var, int obs)` Deprecated. This method cannot access observations beyond 2^31-1. Use `getNum(String, int, long)` instead.
`static double`	`getNum(String rname, int var, long obs)` Read a numeric value from a data frame.
`static int`	`getObsCount(String rname)` Deprecated. This method cannot get counts beyond 2^31-1. Use `getObsTotal(String)` instead.
`static long`	`getObsTotal(String rname)` Get the number of observations in a data frame.
`static String`	`getStr(String rname, int var, int obs)` Deprecated. This method cannot access observations beyond 2^31-1. Use `getStr(String, int, long)` instead.
`static String`	`getStr(String rname, int var, long obs)` Read a string value from a data frame.
`static int`	`getStrVarWidth(String rname, int var)` Get the width of a variable of type str.
`static int`	`getType(String rname, int var)` Get the numeric data type for the specified variable.
`static int`	`getVarCount(String rname)` Get the number of variables in a data frame.
`static String`	`getVarFormat(String rname, int var)` Get the format for a variable in a data frame.
`static int`	`getVarIndex(String rname, String varname)` Look up the variable index for the specified name in the data frame.
`static String`	`getVarName(String rname, int var)` Get the variable name at a given variable index.
`static boolean`	`isVarTypeStr(String rname, int var)` Test if a variable is of type str.
`static boolean`	`isVarTypeString(String rname, int var)` Test if a variable is string or numeric.
`static boolean`	`isVarTypeStrL(String rname, int var)` Test if a variable is of type strL.
`static int`	`readBytes(StrLConnector dsc, byte[] b)` Read a sequence of bytes from a strL in the current Stata dataset.
`static int`	`readBytes(StrLConnector dsc, byte[] b, int off, int len)` Read a sequence of bytes from a strL in the current Stata dataset.
`static int`	`setObsCount(String rname, int obs)` Deprecated. This method cannot set observations beyond 2^31-1. Use `setObsTotal(String, long)` instead.
`static int`	`setObsTotal(String rname, long obs)` Set the number of observations in a data frame.
`static int`	`setVarFormat(String rname, int var, String format)` Set the format for a variable in a data frame.
`static int`	`storeBytes(String rname, int var, long obs, byte[] bytes, boolean binary)` Store a byte buffer to a strL in the current Stata dataset.
`static int`	`storeNum(String rname, int var, int obs, double value)` Deprecated. This method cannot access observations beyond 2^31-1. Use `storeNum(String, int, long, double)` instead.
`static int`	`storeNum(String rname, int var, long obs, double value)` Store a numeric value in a data frame.
`static int`	`storeStr(String rname, int var, int obs, String value)` Deprecated. This method cannot access observations beyond 2^31-1. Use `storeStr(String, int, long, String)` instead.
`static int`	`storeStr(String rname, int var, long obs, String value)` Store a string value in a data frame.
`static int`	`writeBytes(StrLConnector dsc, byte[] b)` Write a byte buffer to a strL in the current Stata dataset; the strL must be allocated using `allocateStrL` before calling this method.
`static int`	`writeBytes(StrLConnector dsc, byte[] b, int off, int len)` Write `len` bytes from the specified byte buffer starting at offset `off` to a strL in the current Stata dataset; the strL must be allocated using `allocateStrL` before calling this method.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - allocate
```
public static int allocate(String rname)
```
    Allocate a new data frame. When a data frame is no longer needed, free must be called to return the memory associated with the data frame to the system.
    
    Parameters:
    
    rname - Reference name for the new data frame.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - free
```
public static int free(String rname)
```
    Free a previously allocated data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - getNum
```
public static double getNum(String rname,
                            int var,
                            long obs)
```
    Read a numeric value from a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    obs - Observation to access.
    
    Returns:
    
    The value.
  - getNum
```
@Deprecated
public static double getNum(String rname,
                                         int var,
                                         int obs)
```
    Deprecated. This method cannot access observations beyond 2^31-1. Use getNum(String, int, long) instead.
    
    Read a numeric value from a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    obs - Observation to access.
    
    Returns:
    
    The value.
  - getStrVarWidth
```
public static int getStrVarWidth(String rname,
                                 int var)
```
    Get the width of a variable of type str.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - The index of the variable to test.
    
    Returns:
    
    The width if the variable is of type str.
  - getStr
```
public static String getStr(String rname,
                            int var,
                            long obs)
```
    Read a string value from a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    obs - Observation to access.
    
    Returns:
    
    The String. Returns null if an error occurs.
  - getStr
```
@Deprecated
public static String getStr(String rname,
                                         int var,
                                         int obs)
```
    Deprecated. This method cannot access observations beyond 2^31-1. Use getStr(String, int, long) instead.
    
    Read a string value from a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    obs - Observation to access.
    
    Returns:
    
    The String. Returns null if an error occurs.
  - getType
```
public static int getType(String rname,
                          int var)
```
    Get the numeric data type for the specified variable.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    Returns:
    
    The value representing the data type; may be TYPE_BYTE, TYPE_INT, TYPE_LONG, TYPE_FLOAT, TYPE_DOUBLE, TYPE_STR, or TYPE_STRL.
  - storeNum
```
public static int storeNum(String rname,
                           int var,
                           long obs,
                           double value)
```
    Store a numeric value in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    obs - Observation to access.
    
    value - Value to store.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - storeNum
```
@Deprecated
public static int storeNum(String rname,
                                        int var,
                                        int obs,
                                        double value)
```
    Deprecated. This method cannot access observations beyond 2^31-1. Use storeNum(String, int, long, double) instead.
    
    Store a numeric value in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    obs - Observation to access.
    
    value - Value to store.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - storeStr
```
public static int storeStr(String rname,
                           int var,
                           long obs,
                           String value)
```
    Store a string value in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    obs - Observation to access.
    
    value - Value to store.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - storeStr
```
@Deprecated
public static int storeStr(String rname,
                                        int var,
                                        int obs,
                                        String value)
```
    Deprecated. This method cannot access observations beyond 2^31-1. Use storeStr(String, int, long, String) instead.
    
    Store a string value in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    obs - Observation to access.
    
    value - Value to store.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - getVarFormat
```
public static String getVarFormat(String rname,
                                  int var)
```
    Get the format for a variable in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Index of the variable to look up.
    
    Returns:
    
    The variable's format.
  - setVarFormat
```
public static int setVarFormat(String rname,
                               int var,
                               String format)
```
    Set the format for a variable in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Index of the variable to format.
    
    format - New format.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - getVarCount
```
public static int getVarCount(String rname)
```
    Get the number of variables in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    Returns:
    
    The number of variables.
  - getObsTotal
```
public static long getObsTotal(String rname)
```
    Get the number of observations in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    Returns:
    
    The number of observations.
  - getObsCount
```
@Deprecated
public static int getObsCount(String rname)
```
    Deprecated. This method cannot get counts beyond 2^31-1. Use getObsTotal(String) instead.
    
    Get the number of observations in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    Returns:
    
    The number of observations.
  - setObsTotal
```
public static int setObsTotal(String rname,
                              long obs)
```
    Set the number of observations in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    obs - The number of observations to set.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - setObsCount
```
@Deprecated
public static int setObsCount(String rname,
                                           int obs)
```
    Deprecated. This method cannot set observations beyond 2^31-1. Use setObsTotal(String, long) instead.
    
    Set the number of observations in a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    obs - The number of observations to set.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - addVarDouble
```
public static int addVarDouble(String rname,
                               String vname)
```
    Add a variable of type double to a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    vname - Name of the variable to be created.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - addVarFloat
```
public static int addVarFloat(String rname,
                              String vname)
```
    Add a variable of type float to a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    vname - Name of the variable to be created.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - addVarLong
```
public static int addVarLong(String rname,
                             String vname)
```
    Add a variable of type long to a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    vname - Name of the variable to be created.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - addVarInt
```
public static int addVarInt(String rname,
                            String vname)
```
    Add a variable of type int to a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    vname - Name of the variable to be created.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - addVarByte
```
public static int addVarByte(String rname,
                             String vname)
```
    Add a variable of type byte to a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    vname - Name of the variable to be created.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - addVarStr
```
public static int addVarStr(String rname,
                            String vname,
                            int length)
```
    Add a variable of type str to a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    vname - Name of the variable to be created.
    
    length - Initial size of the variable. If the length is greater than Data.getMaxStrLength(), then a variable of type strL will be created.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - addVarStrL
```
public static int addVarStrL(String rname,
                             String vname)
```
    Add a variable of type strL to a data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    vname - Name of the variable to be created.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - getVarIndex
```
public static int getVarIndex(String rname,
                              String varname)
```
    Look up the variable index for the specified name in the data frame.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    varname - Name of the variable.
    
    Returns:
    
    The variable index.
  - getVarName
```
public static String getVarName(String rname,
                                int var)
```
    Get the variable name at a given variable index.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Index of the variable to look up.
    
    Returns:
    
    The name of the data frame variable.
  - isVarTypeString
```
public static boolean isVarTypeString(String rname,
                                      int var)
```
    Test if a variable is string or numeric.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - The index of the variable to test.
    
    Returns:
    
    True if the variable is a string variable of either type str or type strL.
  - isVarTypeStr
```
public static boolean isVarTypeStr(String rname,
                                   int var)
```
    Test if a variable is of type str.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - The index of the variable to test.
    
    Returns:
    
    True if the variable is of type str.
  - isVarTypeStrL
```
public static boolean isVarTypeStrL(String rname,
                                    int var)
```
    Test if a variable is of type strL.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - The index of the variable to test.
    
    Returns:
    
    True if the variable is of type strL.
  - readBytes
```
public static int readBytes(StrLConnector dsc,
                            byte[] b,
                            int off,
                            int len)
                     throws IOException
```
    Read a sequence of bytes from a strL in the current Stata dataset.
    
    Parameters:
    
    dsc - The StrLConnector representing a strL.
    
    b - The buffer into which the data are read.
    
    off - The start offset in the destination array b.
    
    len - The maximum number of bytes read.
    
    Returns:
    
    The total number of bytes read into the buffer, or -1 if there are no more data because the end has been reached; may return a negative Stata return code if an error occurs.
    
    Throws:
    
    IOException - throws an IOException if an error occurs.
  - readBytes
```
public static int readBytes(StrLConnector dsc,
                            byte[] b)
                     throws IOException
```
    Read a sequence of bytes from a strL in the current Stata dataset.
    
    Parameters:
    
    dsc - The StrLConnector representing a strL.
    
    b - The buffer into which the data are read.
    
    Returns:
    
    The total number of bytes read into the buffer, or -1 if there are no more data because the end has been reached; may return a negative Stata return code if an error occurs.
    
    Throws:
    
    IOException - throws an IOException if an error occurs.
  - storeBytes
```
public static int storeBytes(String rname,
                             int var,
                             long obs,
                             byte[] bytes,
                             boolean binary)
```
    Store a byte buffer to a strL in the current Stata dataset.
    
    Parameters:
    
    rname - Reference name for the data frame.
    
    var - Variable to access.
    
    obs - Observation to access.
    
    bytes - Bytes to store.
    
    binary - Mark the data as binary.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - writeBytes
```
public static int writeBytes(StrLConnector dsc,
                             byte[] b)
```
    Write a byte buffer to a strL in the current Stata dataset; the strL must be allocated using allocateStrL before calling this method. The buffer size may be smaller than the allocation size for the strL so that calling this method multiple times will write the data in chunks. The current position of each write will be automatically maintained. Writing beyond the allocation size is not permitted.
    
    Parameters:
    
    dsc - The StrLConnector representing a strL.
    
    b - The buffer holding the data to store.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - writeBytes
```
public static int writeBytes(StrLConnector dsc,
                             byte[] b,
                             int off,
                             int len)
```
    Write len bytes from the specified byte buffer starting at offset off to a strL in the current Stata dataset; the strL must be allocated using allocateStrL before calling this method. The buffer size may be smaller than the allocation size for the strL so that calling this method multiple times will write the data in chunks. The current position of each write will be automatically maintained. Writing beyond the allocation size is not permitted.
    
    Parameters:
    
    dsc - The StrLConnector representing a strL.
    
    b - The buffer holding the data to store.
    
    off - The offset into the buffer.
    
    len - The number of bytes to write.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - allocateStrL
```
public static int allocateStrL(StrLConnector dsc,
                               long size)
```
    Allocate a strL so that a buffer can be stored using writeBytes; the contents of the strL will not be initialized. By default, the data will be marked as binary.
    
    Parameters:
    
    dsc - The StrLConnector representing a strL.
    
    size - The size in bytes.
    
    Returns:
    
    Return code from Stata; 0 if successful.
  - allocateStrL
```
public static int allocateStrL(StrLConnector dsc,
                               long size,
                               boolean binary)
```
    Allocate a strL so that a buffer can be stored using writeBytes; the contents of the strL will not be initialized.
    
    Parameters:
    
    dsc - The StrLConnector representing a strL.
    
    size - The size in bytes.
    
    binary - Mark the data as binary.
    
    Returns:
    
    Return code from Stata; 0 if successful.

Class DataFrame

Method Summary

Methods inherited from class java.lang.Object

Method Detail

allocate

free

getNum

getNum

getStrVarWidth

getStr

getStr

getType

storeNum

storeNum

storeStr

storeStr

getVarFormat

setVarFormat

getVarCount

getObsTotal

getObsCount

setObsTotal

setObsCount

addVarDouble

addVarFloat

addVarLong

addVarInt

addVarByte

addVarStr

addVarStrL

getVarIndex

getVarName

isVarTypeString

isVarTypeStr

isVarTypeStrL

readBytes

readBytes

storeBytes

writeBytes

writeBytes

allocateStrL

allocateStrL