diff --git a/doc/helpdb.jl b/doc/helpdb.jl index d88a54df54dc1..cffc7f7521db6 100644 --- a/doc/helpdb.jl +++ b/doc/helpdb.jl @@ -2,220 +2,6 @@ { -("ArgParse","ArgParse","parse_args","parse_args([args], settings) - - This is the central function of the \"ArgParse\" module. It takes a - \"Vector\" of arguments and an \"ArgParseSettings\" objects (see - *this section*), and returns a \"Dict{String,Any}\". If \"args\" is - not provided, the global variable \"ARGS\" will be used. - - The returned \"Dict\" keys are defined (possibly implicitly) in - \"settings\", and their associated values are parsed from \"args\". - Special keys are used for more advanced purposes; at the moment, - one such key exists: \"%COMMAND%\" (see *this section*). - - Arguments are parsed in sequence and matched against the argument - table in \"settings\" to determine whether they are long options, - short options, option arguments or positional arguments: - - * long options begin with a doule dash \"\"--\"\"; if a \"'='\" - character is found, the remainder is the option argument; - therefore, \"[\"--opt=arg\"]\" and \"[\"--opt\", \"arg\"]\" are - equivalent if \"--opt\" takes at least one argument. Long options - can be abbreviated (e.g. \"--opt\" instead of \"--option\") as - long as there is no ambiguity. - - * short options begin with a single dash \"\"-\"\" and their name - consists of a single character; they can be grouped togheter - (e.g. \"[\"-x\", \"-y\"]\" can become \"[\"-xy\"]\"), but in that - case only the last option in the group can take an argument - (which can also be grouped, e.g. \"[\"-a\", \"-f\", - \"file.txt\"]\" can be passed as \"[\"-affile.txt\"]\" if \"-a\" - does not take an argument and \"-f\" does). The \"'='\" character - can be used to separate option names from option arguments as - well (e.g. \"-af=file.txt\"). - - * positional arguments are anything else; they can appear anywhere. - - The special string \"\"--\"\" can be used to signal the end of all - options; after that, everything is considered as a positional - argument (e.g. if \"args = [\"--opt1\", \"--\", \"--opt2\"]\", the - parser will recognize \"--opt1\" as a long option without argument, - and \"--opt2\" as a positional argument). - - The special string \"\"-\"\" is always parsed as a positional - argument. - - The parsing can stop early if a \":show_help\" or \":show_version\" - action is triggered, or if a parsing error is found. - - Some ambiguities can arise in parsing, see *this section* for a - detailed description of how they're solved. - -"), - -("ArgParse","ArgParse","@add_arg_table","@add_arg_table(settings, table...) - - This macro adds a table of arguments and options to the given - \"settings\". It can be invoked multiple times. The arguments - groups are determined automatically, or the current default group - is used if specified (see *this section* for more details). - - The \"table\" is a list in which each element can be either - \"String\", or a tuple or a vector of \"String\", or an assigmment - expression, or a block: - - * a \"String\", a tuple or a vector introduces a new positional - argument or option. Tuples and vectors are only allowed for - options and provide alternative names (e.g. \"[\"--opt\", - \"-o\"]\") - - * assignment expressions (i.e. expressions using \"=\", \":=\" or - \"=>\") describe the previous argument behavior (e.g. \"help = - \"an option\"\" or \"required => false\"). See *this section* - for a complete description - - * blocks (\"begin...end\" or lists of expressions in parentheses - separated by semicolons) are useful to group entries and span - multiple lines. - - These rules allow for a variety usage styles, which are discussed - in *this section*. In the rest of this document, we will mostly use - this style: - - @add_arg_table settings begin - \"--opt1\", \"-o\" - help = \"an option with an argument\" - \"--opt2\" - \"arg1\" - help = \"a positional argument\" - required = true - end - - In the above example, the \"table\" is put in a single - \"begin...end\" block and the line \"\"-opt1\", \"-o\"\" is parsed - as a tuple; indentation is used to help readability. - -"), - -("ArgParse","ArgParse","add_arg_table","add_arg_table(settings, [arg_name [,arg_options]]...) - - This function is almost equivalent to the macro version. Its syntax - is stricter (tuples and blocks are not allowed and argument options - are explicitly specified as \"Options\" objects) but the - \"arg_name\" entries need not be explicit, they can be anything - which evaluates to a \"String\" or a \"Vector{String}\". - - Example: - - add_arg_table(settings, - [\"--opt1\", \"-o\"], - @options begin - help = \"an option with an argument\" - end, - \"--opt2\", - \"arg1\", - @options begin - help = \"a positional argument\" - required = true - end) - - Note that the \"OptionsMod\" module must be imported in order to - use this function. - -"), - -("ArgParse","ArgParse","add_arg_group","add_arg_group(settings, description[, name[, set_as_default]]) - - This function adds an argument group to the argument table in - \"settings\". The \"description\" is a \"String\" used in the help - screen as a title for that group. The \"name\" is a unique name - which can be provided to refer to that group at a later time. - - After invoking this function, all subsequent invocations of the - \"@add_arg_table\" macro and \"add_arg_table\" function will use - the new group as the default, unless \"set_as_default\" is set to - \"false\" (the default is \"true\", and the option can only be set - if providing a \"name\"). Therefore, the most obvious usage pattern - is: for each group, add it and populate the argument table of that - group. Example: - - julia> settings = ArgParseSettings(); - - julia> add_arg_group(settings, \"custom group\"); - - julia> @add_arg_table settings begin - \"--opt\" - \"arg\" - end; - - julia> parse_args([\"--help\"], settings) - usage: [--opt OPT] [-h] [arg] - - optional arguments: - -h, --help show this help message and exit - - custom group: - --opt OPT - arg - - As seen from the example, new groups are always added at the end of - existing ones. - - The \"name\" can also be passed as a \"Symbol\". Forbidden names - are the standard groups names (\"\"command\"\", \"\"positional\"\" - and \"\"optional\"\") and those beginning with a hash character - \"'#'\". - -"), - -("ArgParse","ArgParse","set_default_arg_group","set_default_arg_group(settings[, name]) - - Set the default group for subsequent invocations of the - \"@add_arg_table\" macro and \"add_arg_table\" function. \"name\" - is a \"String\", and must be one of the standard group names - (\"\"command\"\", \"\"positional\"\" or \"\"optional\"\") or one of - the user-defined names given in \"add_arg_group\" (groups with no - assigned name cannot be used with this function). - - If \"name\" is not provided or is the empty string \"\"\"\", then - the default behavior is reset (i.e. arguments will be automatically - assigned to the standard groups). The \"name\" can also be passed - as a \"Symbol\". - -"), - -("ArgParse","ArgParse","import_settings","import_settings(settings, other_settings[, args_only]) - - Imports \"other_settings\" into \"settings\", where both are - \"ArgParseSettings\" objects. If \"args_only\" is \"true\" (this is - the default), only the argument table will be imported; otherwise, - the default argument group will also be imported, and all general - settings except \"prog\", \"description\", \"epilog\" and - \"usage\". - - Sub-settings associated with commands will also be imported - recursively; the \"args_only\" setting applies to those as well. If - there are common commands, their sub-settings will be merged. - - While importing, conflicts may arise: if - \"settings.error_on_conflict\" is \"true\", this will result in an - error, otherwise conflicts will be resolved in favor of - \"other_settings\" (see *this section* for a detailed discussion of - how conflicts are handled). - - Argument groups will also be imported; if two groups in - \"settings\" and \"other_settings\" match, they are merged (groups - match either by name, or, if unnamed, by their description). - - Note that the import will have effect immediately: any subsequent - modification of \"other_settings\" will not have any effect on - \"settings\". - - This function can be used at any time. - -"), - ("Getting Around","Base","exit","exit([code]) Quit (or control-D at the prompt). The default exit code is zero, @@ -5499,1987 +5285,162 @@ error(Exception) "), -("GLPK","GLPK","set_prob_name","set_prob_name(glp_prob, name) - - Assigns a name to the problem object (or deletes it if \"name\" is - empty or \"nothing\"). - -"), - -("GLPK","GLPK","set_obj_name","set_obj_name(glp_prob, name) - - Assigns a name to the objective function (or deletes it if \"name\" - is empty or \"nothing\"). - -"), - -("GLPK","GLPK","set_obj_dir","set_obj_dir(glp_prob, dir) - - Sets the optimization direction, \"GLPK.MIN\" (minimization) or - \"GLPK.MAX\" (maximization). - -"), - -("GLPK","GLPK","add_rows","add_rows(glp_prob, rows) - - Adds the given number of rows (constraints) to the problem object; - returns the number of the first new row added. - -"), - -("GLPK","GLPK","add_cols","add_cols(glp_prob, cols) - - Adds the given number of columns (structural variables) to the - problem object; returns the number of the first new column added. - -"), - -("GLPK","GLPK","set_row_name","set_row_name(glp_prob, row, name) - - Assigns a name to the specified row (or deletes it if \"name\" is - empty or \"nothing\"). - -"), - -("GLPK","GLPK","set_col_name","set_col_name(glp_prob, col, name) - - Assigns a name to the specified column (or deletes it if \"name\" - is empty or \"nothing\"). - -"), - -("GLPK","GLPK","set_row_bnds","set_row_bnds(glp_prob, row, bounds_type, lb, ub) - - Sets the type and bounds on a row. \"type\" must be one of - \"GLPK.FR\" (free), \"GLPK.LO\" (lower bounded), \"GLPK.UP\" (upper - bounded), \"GLPK.DB\" (double bounded), \"GLPK.FX\" (fixed). - - At initialization, each row is free. - -"), - -("GLPK","GLPK","set_col_bnds","set_col_bnds(glp_prob, col, bounds_type, lb, ub) - - Sets the type and bounds on a column. \"type\" must be one of - \"GLPK.FR\" (free), \"GLPK.LO\" (lower bounded), \"GLPK.UP\" (upper - bounded), \"GLPK.DB\" (double bounded), \"GLPK.FX\" (fixed). - - At initialization, each column is fixed at 0. - -"), - -("GLPK","GLPK","set_obj_coef","set_obj_coef(glp_prob, col, coef) - - Sets the objective coefficient to a column (\"col\" can be 0 to - indicate the constant term of the objective function). - -"), - -("GLPK","GLPK","set_mat_row","set_mat_row(glp_prob, row[, len], ind, val) - - Sets (replaces) the content of a row. The content is specified in - sparse format: \"ind\" is a vector of indices, \"val\" is the - vector of corresponding values. \"len\" is the number of vector - elements which will be considered, and must be less or equal to the - length of both \"ind\" and \"val\". If \"len\" is 0, \"ind\" - and/or \"val\" can be \"nothing\". - - In Julia, \"len\" can be omitted, and then it is inferred from - \"ind\" and \"val\" (which need to have the same length in such - case). - -"), - -("GLPK","GLPK","set_mat_col","set_mat_col(glp_prob, col[, len], ind, val) - - Sets (replaces) the content of a column. Everything else is like - \"set_mat_row\". - -"), - -("GLPK","GLPK","load_matrix","load_matrix(glp_prob[, numel], ia, ja, ar) -load_matrix(glp_prob, A) - - Sets (replaces) the content matrix (i.e. sets all rows/coluns at - once). The matrix is passed in sparse format. - - In the first form (original C API), it's passed via 3 vectors: - \"ia\" and \"ja\" are for rows/columns indices, \"ar\" is for - values. \"numel\" is the number of elements which will be read and - must be less or equal to the length of any of the 3 vectors. If - \"numel\" is 0, any of the vectors can be passed as \"nothing\". - - In Julia, \"numel\" can be omitted, and then it is inferred from - \"ia\", \"ja\" and \"ar\" (which need to have the same length in - such case). - - Also, in Julia there's a second, simpler calling form, in which the - matrix is passed as a \"SparseMatrixCSC\" object. - -"), - -("GLPK","GLPK","check_dup","check_dup(rows, cols[, numel], ia, ja) - - Check for duplicates in the indices vectors \"ia\" and \"ja\". - \"numel\" has the same meaning and (optional) use as in - \"load_matrix\". Returns 0 if no duplicates/out-of-range indices - are found, or a positive number indicating where a duplicate - occurs, or a negative number indicating an out-of-bounds index. - -"), - -("GLPK","GLPK","sort_matrix","sort_matrix(glp_prob) - - Sorts the elements of the problem object's matrix. - -"), - -("GLPK","GLPK","del_rows","del_rows(glp_prob[, num_rows], rows_ids) - - Deletes rows from the problem object. Rows are specified in the - \"rows_ids\" vector. \"num_rows\" is the number of elements of - \"rows_ids\" which will be considered, and must be less or equal to - the length id \"rows_ids\". If \"num_rows\" is 0, \"rows_ids\" can - be \"nothing\". In Julia, \"num_rows\" is optional (it's inferred - from \"rows_ids\" if not given). - -"), - -("GLPK","GLPK","del_cols","del_cols(glp_prob, cols_ids) - - Deletes columns from the problem object. See \"del_rows\". - -"), - -("GLPK","GLPK","copy_prob","copy_prob(glp_prob_dest, glp_prob, copy_names) - - Makes a copy of the problem object. The flag \"copy_names\" - determines if names are copied, and must be either \"GLPK.ON\" or - \"GLPK.OFF\". - -"), - -("GLPK","GLPK","erase_prob","erase_prob(glp_prob) - - Resets the problem object. - -"), - -("GLPK","GLPK","get_prob_name","get_prob_name(glp_prob) - - Returns the problem object's name. Unlike the C version, if the - problem has no assigned name, returns an empty string. - -"), - -("GLPK","GLPK","get_obj_name","get_obj_name(glp_prob) - - Returns the objective function's name. Unlike the C version, if the - objective has no assigned name, returns an empty string. - -"), -("GLPK","GLPK","get_obj_dir","get_obj_dir(glp_prob) +("Punctuation","","punctuation","punctuation - Returns the optimization direction, \"GLPK.MIN\" (minimization) or - \"GLPK.MAX\" (maximization). + +-----------+---------------------------------------------------------------------------------------------+ + | symbol | meaning | + +===========+=============================================================================================+ + | \\\"@m\\\" | invoke macro m; followed by space-separated expressions | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"!\\\" | prefix \\\"not\\\" operator | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"!\\\" | at the end of a function name, indicates that a function modifies its argument(s) | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"#\\\" | begin single line comment | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"\\\$\\\" | xor operator, string and expression interpolation | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"%\\\" | remainder operator | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"^\\\" | exponent operator | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"&\\\" | bitwise and | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"*\\\" | multiply, or matrix multiply | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"()\\\" | the empty tuple | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"~\\\" | bitwise not operator | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"\\\\\\\" | backslash operator | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"a[]\\\" | array indexing | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"[,]\\\" | vertical concatenation | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"[;]\\\" | also vertical concatenation | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"[ ]\\\" | with space-separated expressions, horizontal concatenation | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"T{ }\\\" | parametric type instantiation | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"{ }\\\" | construct a cell array | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\";\\\" | statement separator | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\",\\\" | separate function arguments or tuple components | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"?\\\" | 3-argument conditional operator | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"\\\"\\\"\\\" | delimit string literals | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"''\\\" | delimit character literals | + +-----------+---------------------------------------------------------------------------------------------+ + | >>``<< | delimit external process (command) specifications | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"...\\\" | splice arguments into a function call, or declare a varargs function | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\".\\\" | access named fields in objects or names inside modules, also prefixes elementwise operators | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"a:b\\\" | range | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"a:s:b\\\" | range | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\":\\\" | index an entire dimension | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\"::\\\" | type annotation | + +-----------+---------------------------------------------------------------------------------------------+ + | \\\":( )\\\" | quoted expression | + +-----------+---------------------------------------------------------------------------------------------+ "), -("GLPK","GLPK","get_num_rows","get_num_rows(glp_prob) +("Base.Sort","Base.Sort","sort","sort(v[, alg[, ord]]) - Returns the current number of rows. + Sort a vector in ascending order. Specify \"alg\" to choose a + particular sorting algorithm (\"Sort.InsertionSort\", + \"Sort.QuickSort\", \"Sort.MergeSort\", or \"Sort.TimSort\"), and + \"ord\" to sort with a custom ordering (e.g., Sort.Reverse or a + comparison function). "), -("GLPK","GLPK","get_num_cols","get_num_cols(glp_prob) +("Base.Sort","Base.Sort","sort!","sort!(...) - Returns the current number of columns. + In-place sort. "), -("GLPK","GLPK","get_row_name","get_row_name(glp_prob, row) +("Base.Sort","Base.Sort","sortby","sortby(v, by[, alg]) - Returns the name of the specified row. Unlike the C version, if the - row has no assigned name, returns an empty string. + Sort a vector according to \"by(v)\". Specify \"alg\" to choose a + particular sorting algorithm (\"Sort.InsertionSort\", + \"Sort.QuickSort\", \"Sort.MergeSort\", or \"Sort.TimSort\"). "), -("GLPK","GLPK","get_col_name","get_col_name(glp_prob, col) +("Base.Sort","Base.Sort","sortby!","sortby!(...) - Returns the name of the specified column. Unlike the C version, if - the column has no assigned name, returns an empty string. + In-place \"sortby\". "), -("GLPK","GLPK","get_row_type","get_row_type(glp_prob, row) +("Base.Sort","Base.Sort","sortperm","sortperm(v[, alg[, ord]]) - Returns the type of the specified row: \"GLPK.FR\" (free), - \"GLPK.LO\" (lower bounded), \"GLPK.UP\" (upper bounded), - \"GLPK.DB\" (double bounded), \"GLPK.FX\" (fixed). + Return a permutation vector, which when applied to the input vector + \"v\" will sort it. Specify \"alg\" to choose a particular sorting + algorithm (\"Sort.InsertionSort\", \"Sort.QuickSort\", + \"Sort.MergeSort\", or \"Sort.TimSort\"), and \"ord\" to sort with + a custom ordering (e.g., Sort.Reverse or a comparison function). "), -("GLPK","GLPK","get_row_lb","get_row_lb(glp_prob, row) +("Base.Sort","Base.Sort","issorted","issorted(v[, ord]) - Returns the lower bound of the specified row, \"-DBL_MAX\" if - unbounded. + Test whether a vector is in ascending sorted order. If specified, + \"ord\" gives the ordering to test. "), -("GLPK","GLPK","get_row_ub","get_row_ub(glp_prob, row) - - Returns the upper bound of the specified row, \"+DBL_MAX\" if - unbounded. - -"), +("Base.Sort","Base.Sort","searchsorted","searchsorted(a, x[, ord]) -("GLPK","GLPK","get_col_type","get_col_type(glp_prob, col) + Returns the index of the first value of \"a\" equal to or + succeeding \"x\", according to ordering \"ord\" (default: + \"Sort.Forward\"). - Returns the type of the specified column: \"GLPK.FR\" (free), - \"GLPK.LO\" (lower bounded), \"GLPK.UP\" (upper bounded), - \"GLPK.DB\" (double bounded), \"GLPK.FX\" (fixed). + Alias for \"searchsortedfirst()\" "), -("GLPK","GLPK","get_col_lb","get_col_lb(glp_prob, col) +("Base.Sort","Base.Sort","searchsortedfirst","searchsortedfirst(a, x[, ord]) - Returns the lower bound of the specified column, \"-DBL_MAX\" if - unbounded. + Returns the index of the first value of \"a\" equal to or + succeeding \"x\", according to ordering \"ord\" (default: + \"Sort.Forward\"). "), -("GLPK","GLPK","get_col_ub","get_col_ub(glp_prob, col) +("Base.Sort","Base.Sort","searchsortedlast","searchsortedlast(a, x[, ord]) - Returns the upper bound of the specified column, \"+DBL_MAX\" if - unbounded. + Returns the index of the last value of \"a\" preceding or equal to + \"x\", according to ordering \"ord\" (default: \"Sort.Forward\"). "), -("GLPK","GLPK","get_obj_coef","get_obj_coef(glp_prob, col) +("Base.Sort","Base.Sort","select","select(v, k[, ord]) - Return the objective coefficient to a column (\"col\" can be 0 to - indicate the constant term of the objective function). + Find the element in position \"k\" in the sorted vector \"v\" + without sorting, according to ordering \"ord\" (default: + \"Sort.Forward\"). "), -("GLPK","GLPK","get_num_nz","get_num_nz(glp_prob) - - Return the number of non-zero elements in the constraint matrix. - -"), - -("GLPK","GLPK","get_mat_row","get_mat_row(glp_prob, row, ind, val) -get_mat_row(glp_prob, row) - - Returns the contents of a row. In the first form (original C API), - it fills the \"ind\" and \"val\" vectors provided, which must be of - type \"Vector{Int32}\" and \"Vector{Float64}\" respectively, and - have a sufficient length to hold the result (or they can be empty - or \"nothing\", and then they're not filled). It returns the length - of the result. - - In Julia, there's a second, simpler calling form which allocates - and returns the two vectors as \"(ind, val)\". - -"), - -("GLPK","GLPK","get_mat_col","get_mat_col(glp_prob, col, ind, val) -get_mat_col(glp_prob, col) - - Returns the contents of a column. See \"get_mat_row\". - -"), - -("GLPK","GLPK","create_index","create_index(glp_prob) - - Creates the name index (used by \"find_row\", \"find_col\") for the - problem object. - -"), - -("GLPK","GLPK","find_row","find_row(glp_prob, name) - - Finds the numeric id of a row by name. Returns 0 if no row with the - given name is found. - -"), - -("GLPK","GLPK","find_col","find_col(glp_prob, name) - - Finds the numeric id of a column by name. Returns 0 if no column - with the given name is found. - -"), - -("GLPK","GLPK","delete_index","delete_index(glp_prob) - - Deletes the name index for the problem object. - -"), - -("GLPK","GLPK","set_rii","set_rii(glp_prob, row, rii) - - Sets the rii scale factor for the specified row. - -"), - -("GLPK","GLPK","set_sjj","set_sjj(glp_prob, col, sjj) - - Sets the sjj scale factor for the specified column. - -"), - -("GLPK","GLPK","get_rii","get_rii(glp_prob, row) - - Returns the rii scale factor for the specified row. - -"), - -("GLPK","GLPK","get_sjj","get_sjj(glp_prob, col) - - Returns the sjj scale factor for the specified column. - -"), - -("GLPK","GLPK","scale_prob","scale_prob(glp_prob, flags) - - Performs automatic scaling of problem data for the problem object. - The parameter \"flags\" can be \"GLPK.SF_AUTO\" (automatic) or a - bitwise OR of the forllowing: \"GLPK.SF_GM\" (geometric mean), - \"GLPK.SF_EQ\" (equilibration), \"GLPK.SF_2N\" (nearest power of - 2), \"GLPK.SF_SKIP\" (skip if well scaled). - -"), - -("GLPK","GLPK","unscale_prob","unscale_prob(glp_prob) - - Unscale the problem data (cancels the scaling effect). - -"), - -("GLPK","GLPK","set_row_stat","set_row_stat(glp_prob, row, stat) - - Sets the status of the specified row. \"stat\" must be one of: - \"GLPK.BS\" (basic), \"GLPK.NL\" (non-basic lower bounded), - \"GLPK.NU\" (non-basic upper-bounded), \"GLPK.NF\" (non-basic - free), \"GLPK.NS\" (non-basic fixed). - -"), - -("GLPK","GLPK","set_col_stat","set_col_stat(glp_prob, col, stat) - - Sets the status of the specified column. \"stat\" must be one of: - \"GLPK.BS\" (basic), \"GLPK.NL\" (non-basic lower bounded), - \"GLPK.NU\" (non-basic upper-bounded), \"GLPK.NF\" (non-basic - free), \"GLPK.NS\" (non-basic fixed). - -"), - -("GLPK","GLPK","std_basis","std_basis(glp_prob) - - Constructs the standard (trivial) initial LP basis for the problem - object. - -"), - -("GLPK","GLPK","adv_basis","adv_basis(glp_prob[, flags]) - - Constructs an advanced initial LP basis for the problem object. The - flag \"flags\" is optional; it must be 0 if given. - -"), - -("GLPK","GLPK","cpx_basis","cpx_basis(glp_prob) - - Constructs an initial LP basis for the problem object with the - algorithm proposed by R. Bixby. - -"), - -("GLPK","GLPK","simplex","simplex(glp_prob[, glp_param]) - - The routine \"simplex\" is a driver to the LP solver based on the - simplex method. This routine retrieves problem data from the - specified problem object, calls the solver to solve the problem - instance, and stores results of computations back into the problem - object. - - The parameters are specified via the optional \"glp_param\" - argument, which is of type \"GLPK.SimplexParam\" (or \"nothing\" to - use the default settings). - - Returns 0 in case of success, or a non-zero flag specifying the - reason for failure: \"GLPK.EBADB\" (invalid base), \"GLPK.ESING\" - (singular matrix), \"GLPK.ECOND\" (ill-conditioned matrix), - \"GLPK.EBOUND\" (incorrect bounds), \"GLPK.EFAIL\" (solver - failure), \"GLPK.EOBJLL\" (lower limit reached), \"GLPK.EOBJUL\" - (upper limit reached), \"GLPK.ITLIM\" (iterations limit exceeded), - \"GLPK.ETLIM\" (time limit exceeded), \"GLPK.ENOPFS\" (no primal - feasible solution), \"GLPK.ENODFS\" (no dual feasible solution). - -"), - -("GLPK","GLPK","exact","exact(glp_prob[, glp_param]) - - A tentative implementation of the primal two-phase simplex method - based on exact (rational) arithmetic. Similar to \"simplex\". The - optional \"glp_param\" is of type \"GLPK.SimplexParam\". - - The possible return values are \"0\" (success) or \"GLPK.EBADB\", - \"GLPK.ESING\", \"GLPK.EBOUND\", \"GLPK.EFAIL\", \"GLPK.ITLIM\", - \"GLPK.ETLIM\" (see \"simplex()\"). - -"), - -("GLPK","GLPK","init_smcp","init_smcp(glp_param) - - Initializes a \"GLPK.SimplexParam\" object with the default values. - In Julia, this is done at object creation time; this function can - be used to reset the object. - -"), - -("GLPK","GLPK","get_status","get_status(glp_prob) - - Returns the generic status of the current basic solution: - \"GLPK.OPT\" (optimal), \"GLPK.FEAS\" (feasible), \"GLPK.INFEAS\" - (infeasible), \"GLPK.NOFEAS\" (no feasible solution), - \"GLPK.UNBND\" (unbounded solution), \"GLPK.UNDEF\" (undefined). - -"), - -("GLPK","GLPK","get_prim_stat","get_prim_stat(glp_prob) - - Returns the status of the primal basic solution: \"GLPK.FEAS\", - \"GLPK.INFEAS\", \"GLPK.NOFEAS\", \"GLPK.UNDEF\" (see - \"get_status()\"). - -"), - -("GLPK","GLPK","get_dual_stat","get_dual_stat(glp_prob) - - Returns the status of the dual basic solution: \"GLPK.FEAS\", - \"GLPK.INFEAS\", \"GLPK.NOFEAS\", \"GLPK.UNDEF\" (see - \"get_status()\"). - -"), - -("GLPK","GLPK","get_obj_val","get_obj_val(glp_prob) - - Returns the current value of the objective function. - -"), - -("GLPK","GLPK","get_row_stat","get_row_stat(glp_prob, row) - - Returns the status of the specified row: \"GLPK.BS\", \"GLPK.NL\", - \"GLPK.NU\", \"GLPK.NF\", \"GLPK.NS\" (see \"set_row_stat()\"). - -"), - -("GLPK","GLPK","get_row_prim","get_row_prim(glp_prob, row) - - Returns the primal value of the specified row. - -"), - -("GLPK","GLPK","get_row_dual","get_row_dual(glp_prob, row) - - Returns the dual value (reduced cost) of the specified row. - -"), - -("GLPK","GLPK","get_col_stat","get_col_stat(glp_prob, col) - - Returns the status of the specified column: \"GLPK.BS\", - \"GLPK.NL\", \"GLPK.NU\", \"GLPK.NF\", \"GLPK.NS\" (see - \"set_row_stat()\"). - -"), - -("GLPK","GLPK","get_col_prim","get_col_prim(glp_prob, col) - - Returns the primal value of the specified column. - -"), - -("GLPK","GLPK","get_col_dual","get_col_dual(glp_prob, col) - - Returns the dual value (reduced cost) of the specified column. - -"), - -("GLPK","GLPK","get_unbnd_ray","get_unbnd_ray(glp_prob) - - Returns the number k of a variable, which causes primal or dual - unboundedness (if 1 <= k <= rows it's row k; if rows+1 <= k <= - rows+cols it's column k-rows, if k=0 such variable is not defined). - -"), - -("GLPK","GLPK","interior","interior(glp_prob[, glp_param]) - - The routine \"interior\" is a driver to the LP solver based on the - primal-dual interior-point method. This routine retrieves problem - data from the specified problem object, calls the solver to solve - the problem instance, and stores results of computations back into - the problem object. - - The parameters are specified via the optional \"glp_param\" - argument, which is of type \"GLPK.InteriorParam\" (or \"nothing\" - to use the default settings). - - Returns 0 in case of success, or a non-zero flag specifying the - reason for failure: \"GLPK.EFAIL\" (solver failure), - \"GLPK.ENOCVG\" (very slow convergence, or divergence), - \"GLPK.ITLIM\" (iterations limit exceeded), \"GLPK.EINSTAB\" - (numerical instability). - -"), - -("GLPK","GLPK","init_iptcp","init_iptcp(glp_param) - - Initializes a \"GLPK.InteriorParam\" object with the default - values. In Julia, this is done at object creation time; this - function can be used to reset the object. - -"), - -("GLPK","GLPK","ipt_status","ipt_status(glp_prob) - - Returns the status of the interior-point solution: \"GLPK.OPT\" - (optimal), \"GLPK.INFEAS\" (infeasible), \"GLPK.NOFEAS\" (no - feasible solution), \"GLPK.UNDEF\" (undefined). - -"), - -("GLPK","GLPK","ipt_obj_val","ipt_obj_val(glp_prob) - - Returns the current value of the objective function for the - interior-point solution. - -"), - -("GLPK","GLPK","ipt_row_prim","ipt_row_prim(glp_prob, row) - - Returns the primal value of the specified row for the interior- - point solution. - -"), - -("GLPK","GLPK","ipt_row_dual","ipt_row_dual(glp_prob, row) - - Returns the dual value (reduced cost) of the specified row for the - interior-point solution. - -"), - -("GLPK","GLPK","ipt_col_prim","ipt_col_prim(glp_prob, col) - - Returns the primal value of the specified column for the interior- - point solution. - -"), - -("GLPK","GLPK","ipt_col_dual","ipt_col_dual(glp_prob, col) - - Returns the dual value (reduced cost) of the specified column for - the interior-point solution. - -"), - -("GLPK","GLPK","set_col_kind","set_col_kind(glp_prob, col, kind) - - Sets the kind for the specified column (for mixed-integer - programming). \"kind\" must be one of: \"GLPK.CV\" (continuous), - \"GLPK.IV\" (integer), \"GLPK.BV\" (binary, 0/1). - -"), - -("GLPK","GLPK","get_col_kind","get_col_kind(glp_prob, col) - - Returns the kind for the specified column (see \"set_col_kind()\"). - -"), - -("GLPK","GLPK","get_num_int","get_num_int(glp_prob) - - Returns the number of columns marked as integer (including binary). - -"), - -("GLPK","GLPK","get_num_bin","get_num_bin(glp_prob) - - Returns the number of columns marked binary. - -"), - -("GLPK","GLPK","intopt","intopt(glp_prob[, glp_param]) - - The routine \"intopt\" is a driver to the mixed-integer-programming - (MIP) solver based on the branch- and-cut method, which is a hybrid - of branch-and-bound and cutting plane methods. - - The parameters are specified via the optional \"glp_param\" - argument, which is of type \"GLPK.IntoptParam\" (or \"nothing\" to - use the default settings). - - Returns 0 in case of success, or a non-zero flag specifying the - reason for failure: \"GLPK.EBOUND\" (incorrect bounds), - \"GLPK.EROOT\" (no optimal LP basis given), \"GLPK.ENOPFS\" (no - primal feasible LP solution), \"GLPK.ENODFS\" (no dual feasible LP - solution), \"GLPK.EFAIL\" (solver failure), \"GLPK.EMIPGAP\" (mip - gap tolearance reached), \"GLPK.ETLIM\" (time limit exceeded), - \"GLPK.ESTOP\" (terminated by application). - -"), - -("GLPK","GLPK","init_iocp","init_iocp(glp_param) - - Initializes a \"GLPK.IntoptParam\" object with the default values. - In Julia, this is done at object creation time; this function can - be used to reset the object. - -"), - -("GLPK","GLPK","mip_status","mip_status(glp_prob) - - Returns the generic status of the MIP solution: \"GLPK.OPT\" - (optimal), \"GLPK.FEAS\" (feasible), \"GLPK.NOFEAS\" (no feasible - solution), \"GLPK.UNDEF\" (undefined). - -"), - -("GLPK","GLPK","mip_obj_val","mip_obj_val(glp_prob) - - Returns the current value of the objective function for the MIP - solution. - -"), - -("GLPK","GLPK","mip_row_val","mip_row_val(glp_prob, row) - - Returns the value of the specified row for the MIP solution. - -"), - -("GLPK","GLPK","mip_col_val","mip_col_val(glp_prob, col) - - Returns the value of the specified column for the MIP solution. - -"), - -("GLPK","GLPK","read_mps","read_mps(glp_prob, format[, param], filename) - - Reads problem data in MPS format from a text file. \"format\" must - be one of \"GLPK.MPS_DECK\" (fixed, old) or \"GLPK.MPS_FILE\" - (free, modern). \"param\" is optional; if given it must be - \"nothing\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","write_mps","write_mps(glp_prob, format[, param], filename) - - Writes problem data in MPS format from a text file. See - \"read_mps\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","read_lp","read_lp(glp_prob[, param], filename) - - Reads problem data in CPLEX LP format from a text file. \"param\" - is optional; if given it must be \"nothing\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","write_lp","write_lp(glp_prob[, param], filename) - - Writes problem data in CPLEX LP format from a text file. See - \"read_lp\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","read_prob","read_prob(glp_prob[, flags], filename) - - Reads problem data in GLPK LP/MIP format from a text file. - \"flags\" is optional; if given it must be 0. - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","write_prob","write_prob(glp_prob[, flags], filename) - - Writes problem data in GLPK LP/MIP format from a text file. See - \"read_prob\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","mpl_read_model","mpl_read_model(glp_tran, filename, skip) - - Reads the model section and, optionally, the data section, from a - text file in MathProg format, and stores it in \"glp_tran\", which - is a \"GLPK.MathProgWorkspace\" object. If \"skip\" is nonzero, the - data section is skipped if present. - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","mpl_read_data","mpl_read_data(glp_tran, filename) - - Reads data section from a text file in MathProg format and stores - it in \"glp_tran\", which is a \"GLPK.MathProgWorkspace\" object. - May be called more than once. - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","mpl_generate","mpl_generate(glp_tran[, filename]) - - Generates the model using its description stored in the - \"GLPK.MathProgWorkspace\" translator workspace \"glp_tran\". The - optional \"filename\" specifies an output file; if not given or - \"nothing\", the terminal is used. - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","mpl_build_prob","mpl_build_prob(glp_tran, glp_prob) - - Transfer information from the \"GLPK.MathProgWorkspace\" translator - workspace \"glp_tran\" to the \"GLPK.Prob\" problem object - \"glp_prob\". - -"), - -("GLPK","GLPK","mpl_postsolve","mpl_postsolve(glp_tran, glp_prob, sol) - - Copies the solution from the \"GLPK.Prob\" problem object - \"glp_prob\" to the \"GLPK.MathProgWorkspace\" translator workspace - \"glp_tran\" and then executes all the remaining model statements, - which follow the solve statement. - - The parameter \"sol\" specifies which solution should be copied - from the problem object to the workspace: \"GLPK.SOL\" (basic), - \"GLPK.IPT\" (interior-point), \"GLPK.MIP\" (MIP). - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","print_sol","print_sol(glp_prob, filename) - - Writes the current basic solution to a text file, in printable - format. - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","read_sol","read_sol(glp_prob, filename) - - Reads the current basic solution from a text file, in the format - used by \"write_sol\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","write_sol","write_sol(glp_prob, filename) - - Writes the current basic solution from a text file, in a format - which can be read by \"read_sol\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","print_ipt","print_ipt(glp_prob, filename) - - Writes the current interior-point solution to a text file, in - printable format. - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","read_ipt","read_ipt(glp_prob, filename) - - Reads the current interior-point solution from a text file, in the - format used by \"write_ipt\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","write_ipt","write_ipt(glp_prob, filename) - - Writes the current interior-point solution from a text file, in a - format which can be read by \"read_ipt\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","print_mip","print_mip(glp_prob, filename) - - Writes the current MIP solution to a text file, in printable - format. - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","read_mip","read_mip(glp_prob, filename) - - Reads the current MIP solution from a text file, in the format used - by \"write_mip\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","write_mip","write_mip(glp_prob, filename) - - Writes the current MIP solution from a text file, in a format which - can be read by \"read_mip\". - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","print_ranges","print_ranges(glp_prob, [[len,] list,] [flags,] filename) - - Performs sensitivity analysis of current optimal basic solution and - writes the analysis report in human-readable format to a text file. - \"list\" is a vector specifying the rows/columns to analyze (if 1 - <= list[i] <= rows, analyzes row list[i]; if rows+1 <= list[i] <= - rows+cols, analyzes column list[i]-rows). \"len\" is the number of - elements of \"list\" which will be consideres, and must be smaller - or equal to the length of the list. In Julia, \"len\" is optional - (it's inferred from \"len\" if not given). \"list\" can be empty of - \"nothing\" or not given at all, implying all indices will be - analyzed. \"flags\" is optional, and must be 0 if given. - - To call this function, the current basic solution must be optimal, - and the basis factorization must exist. - - Returns 0 upon success, non-zero otherwise. - -"), - -("GLPK","GLPK","bf_exists","bf_exists(glp_prob) - - Returns non-zero if the basis fatorization for the current basis - exists, 0 otherwise. - -"), - -("GLPK","GLPK","factorize","factorize(glp_prob) - - Computes the basis factorization for the current basis. - - Returns 0 if successful, otherwise: \"GLPK.EBADB\" (invalid - matrix), \"GLPK.ESING\" (singluar matrix), \"GLPK.ECOND\" (ill- - conditioned matrix). - -"), - -("GLPK","GLPK","bf_updated","bf_updated(glp_prob) - - Returns 0 if the basis factorization was computed from scratch, - non-zero otherwise. - -"), - -("GLPK","GLPK","get_bfcp","get_bfcp(glp_prob, glp_param) - - Retrieves control parameters, which are used on computing and - updating the basis factorization associated with the problem - object, and stores them in the \"GLPK.BasisFactParam\" object - \"glp_param\". - -"), - -("GLPK","GLPK","set_bfcp","set_bfcp(glp_prob[, glp_param]) - - Sets the control parameters stored in the \"GLPK.BasisFactParam\" - object \"glp_param\" into the problem object. If \"glp_param\" is - \"nothing\" or is omitted, resets the parameters to their defaults. - - The \"glp_param\" should always be retreived via \"get_bfcp\" - before changing its values and calling this function. - -"), - -("GLPK","GLPK","get_bhead","get_bhead(glp_prob, k) - - Returns the basis header information for the current basis. \"k\" - is a row index. - - Returns either i such that 1 <= i <= rows, if \"k\" corresponds to - i-th auxiliary variable, or rows+j such that 1 <= j <= columns, if - \"k\" corresponds to the j-th structural variable. - -"), - -("GLPK","GLPK","get_row_bind","get_row_bind(glp_prob, row) - - Returns the index of the basic variable \"k\" which is associated - with the specified row, or \"0\" if the variable is non-basic. If - \"GLPK.get_bhead(glp_prob, k) == row\", then - \"GLPK.get_bind(glp_prob, row) = k\". - -"), - -("GLPK","GLPK","get_col_bind","get_col_bind(glp_prob, col) - - Returns the index of the basic variable \"k\" which is associated - with the specified column, or \"0\" if the variable is non-basic. - If \"GLPK.get_bhead(glp_prob, k) == rows+col\", then - \"GLPK.get_bind(glp_prob, col) = k\". - -"), - -("GLPK","GLPK","ftran","ftran(glp_prob, v) - - Performs forward transformation (FTRAN), i.e. it solves the system - Bx = b, where B is the basis matrix, x is the vector of unknowns to - be computed, b is the vector of right-hand sides. At input, \"v\" - represents the vector b; at output, it contains the vector x. \"v\" - must be a \"Vector{Float64}\" whose length is the number of rows. - -"), - -("GLPK","GLPK","btran","btran(glp_prob, v) - - Performs backward transformation (BTRAN), i.e. it solves the system - \"B'x = b\", where \"B\" is the transposed of the basis matrix, - \"x\" is the vector of unknowns to be computed, \"b\" is the vector - of right-hand sides. At input, \"v\" represents the vector \"b\"; - at output, it contains the vector \"x\". \"v\" must be a - \"Vector{Float64}\" whose length is the number of rows. - -"), - -("GLPK","GLPK","warm_up","warm_up(glp_prob) - - \"Warms up\" the LP basis using current statuses assigned to rows - and columns, i.e. computes factorization of the basis matrix (if it - does not exist), computes primal and dual components of basic - solution, and determines the solution status. - - Returns 0 if successful, otherwise: \"GLPK.EBADB\" (invalid - matrix), \"GLPK.ESING\" (singluar matrix), \"GLPK.ECOND\" (ill- - conditioned matrix). - -"), - -("GLPK","GLPK","eval_tab_row","eval_tab_row(glp_prob, k, ind, val) -eval_tab_row(glp_prob, k) - - Computes a row of the current simplex tableau which corresponds to - some basic variable specified by the parameter \"k\". If 1 <= \"k\" - <= rows, uses \"k\"-th auxiliary variable; if rows+1 <= \"k\" <= - rows+cols, uses (\"k\"-rows)-th structural variable. The basis - factorization must exist. - - In the first form, stores the result in the provided vectors - \"ind\" and \"val\", which must be of type \"Vector{Int32}\" and - \"Vector{Float64}\", respectively, and returns the length of the - outcome; in Julia, the vectors will be resized as needed to hold - the result. - - In the second, simpler form, \"ind\" and \"val\" are returned in a - tuple as the output of the function. - -"), - -("GLPK","GLPK","eval_tab_col","eval_tab_col(glp_prob, k, ind, val) -eval_tab_col(glp_prob, k) - - Computes a column of the current simplex tableau which corresponds - to some non-basic variable specified by the parameter \"k\". See - \"eval_tab_row\". - -"), - -("GLPK","GLPK","transform_row","transform_row(glp_prob[, len], ind, val) - - Performs the same operation as \"eval_tab_row\" with the exception - that the row to be transformed is specified explicitly as a sparse - vector. The parameter \"len\" is the number of elements of \"ind\" - and \"val\" which will be used, and must be smaller or equal to the - length of both vectors; in Julia it is optional (and the \"ind\" - and \"val\" must have the same length). The vectors \"int\" and - \"val\" must be of type \"Vector{Int32}\" and \"Vector{Float64}\", - respectively, since they will also hold the result; in Julia, they - will be resized to the resulting required length. - - Returns the length if the resulting vectors \"ind\" and \"val\". - -"), - -("GLPK","GLPK","transform_col","transform_col(glp_prob[, len], ind, val) - - Performs the same operation as \"eval_tab_col\" with the exception - that the row to be transformed is specified explicitly as a sparse - vector. See \"transform_row\". - -"), - -("GLPK","GLPK","prim_rtest","prim_rtest(glp_prob[, len], ind, val, dir, eps) - - Performs the primal ratio test using an explicitly specified column - of the simplex table. The current basic solution must be primal - feasible. The column is specified in sparse format by \"len\" - (length of the vector), \"ind\" and \"val\" (indices and values of - the vector). \"len\" is the number of elements which will be - considered and must be smaller or equal to the length of both - \"ind\" and \"val\"; in Julia, it can be omitted (and then \"ind\" - and \"val\" must have the same length). The indices in \"ind\" must - be between 1 and rows+cols; they must correspond to basic - variables. \"dir\" is a direction parameter which must be either +1 - (increasing) or -1 (decreasing). \"eps\" is a tolerance parameter - and must be positive. See the GLPK manual for a detailed - explanation. - - Returns the position in \"ind\" and \"val\" which corresponds to - the pivot element, or 0 if the choice cannot be made. - -"), - -("GLPK","GLPK","dual_rtest","dual_rtest(glp_prob[, len], ind, val, dir, eps) - - Performs the dual ratio test using an explicitly specified row of - the simplex table. The current basic solution must be dual - feasible. The indices in \"ind\" must correspond to non-basic - variables. Everything else is like in \"prim_rtest\". - -"), - -("GLPK","GLPK","analyze_bound","analyze_bound(glp_prob, k) - - Analyzes the effect of varying the active bound of specified non- - basic variable. See the GLPK manual for a detailed explanation. In - Julia, this function has a different API then C. It returns - \"(limit1, var1, limit2, var2)\" rather then taking them as - pointers in the argument list. - -"), - -("GLPK","GLPK","analyze_coef","analyze_coef(glp_prob, k) - - Analyzes the effect of varying the objective coefficient at - specified basic variable. See the GLPK manual for a detailed - explanation. In Julia, this function has a different API then C. It - returns \"(coef1, var1, value1, coef2, var2, value2)\" rather then - taking them as pointers in the argument list. - -"), - -("GLPK","GLPK","init_env","init_env() - - Initializes the GLPK environment. Not normally needed. - - Returns 0 (initilization successful), 1 (environment already - initialized), 2 (failed, insufficient memory) or 3 (failed, - unsupported programming model). - -"), - -("GLPK","GLPK","version","version() - - Returns the GLPK version number. In Julia, instead of returning a - string as in C, it returns a tuple of integer values, containing - the major and the minor number. - -"), - -("GLPK","GLPK","free_env","free_env() - - Frees all resources used by GLPK routines (memory blocks, etc.) - which are currently still in use. Not normally needed. - - Returns 0 if successful, 1 if envirnoment is inactive. - -"), - -("GLPK","GLPK","term_out","term_out(flag) - - Enables/disables the terminal output of glpk routines. \"flag\" is - either \"GLPK.ON\" (output enabled) or \"GLPK.OFF\" (output - disabled). - - Returns the previous status of the terminal output. - -"), - -("GLPK","GLPK","open_tee","open_tee(filename) - - Starts copying all the terminal output to an output text file. - - Returns 0 if successful, 1 if already active, 2 if it fails - creating the output file. - -"), - -("GLPK","GLPK","close_tee","close_tee() - - Stops copying the terminal output to the output text file - previously open by the \"open_tee\". - - Return 0 if successful, 1 if copying terminal output was not - started. - -"), - -("GLPK","GLPK","malloc","malloc(size) - - Replacement of standard C \"malloc\". Allocates uninitialized - memeory which must freed with \"free\". - - Returns a pointer to the allocated memory. - -"), - -("GLPK","GLPK","calloc","calloc(n, size) - - Replacement of standard C \"calloc\", but does not initialize the - memeory. Allocates uninitialized memeory which must freed with - \"free\". - - Returns a pointer to the allocated memory. - -"), - -("GLPK","GLPK","free","free(ptr) - - Deallocates a memory block previously allocated by \"malloc\" or - \"calloc\". - -"), - -("GLPK","GLPK","mem_usage","mem_usage() - - Reports some information about utilization of the memory by the - routines \"malloc\", \"calloc\", and \"free\". In Julia, this - function has a different API then C. It returns \"(count, cpeak, - total, tpeak)\" rather then taking them as pointers in the argument - list. - -"), - -("GLPK","GLPK","mem_limit","mem_limit(limit) - - Limits the amount of memory avaliable for dynamic allocation to a - value in megabyes given by the integer parameter \"limit\". - -"), - -("GLPK","GLPK","time","time() - - Returns the current universal time (UTC), in milliseconds. - -"), - -("GLPK","GLPK","difftime","difftime(t1, t0) - - Returns the difference between two time values \"t1\" and \"t0\", - expressed in seconds. - -"), - -("GLPK","GLPK","sdf_open_file","sdf_open_file(filename) - - Opens a plain data file. - - If successful, returns a \"GLPK.Data\" object, otherwise throws an - error. - -"), - -("GLPK","GLPK","sdf_read_int","sdf_read_int(glp_data) - - Reads an integer number from the plain data file specified by the - \"GLPK.Data\" parameter \"glp_data\", skipping initial whitespace. - -"), - -("GLPK","GLPK","sdf_read_num","sdf_read_num(glp_data) - - Reads a floating point number from the plain data file specified by - the \"GLPK.Data\" parameter \"glp_data\", skipping initial - whitespace. - -"), - -("GLPK","GLPK","sdf_read_item","sdf_read_item(glp_data) - - Reads a data item (a String) from the plain data file specified by - the \"GLPK.Data\" parameter \"glp_data\", skipping initial - whitespace. - -"), - -("GLPK","GLPK","sdf_read_text","sdf_read_text(glp_data) - - Reads a line of text from the plain data file specified by the - \"GLPK.Data\" parameter \"glp_data\", skipping initial and final - whitespace. - -"), - -("GLPK","GLPK","sdf_line","sdf_line(glp_data) - - Returns the current line in the \"GLPK.Data\" object \"glp_data\" - -"), - -("GLPK","GLPK","sdf_close_file","sdf_close_file(glp_data) - - Closes the file associated to \"glp_data\" and frees the resources. - -"), - -("GLPK","GLPK","read_cnfsat","read_cnfsat(glp_prob, filename) - - Reads the CNF-SAT problem data in DIMACS format from a text file. - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","check_cnfsat","check_cnfsat(glp_prob) - - Checks if the problem object encodes a CNF-SAT problem instance, in - which case it returns 0, otherwise returns non-zero. - -"), - -("GLPK","GLPK","write_cnfsat","write_cnfsat(glp_prob, filename) - - Writes the CNF-SAT problem data in DIMACS format into a text file. - - Returns 0 upon success; throws an error in case of failure. - -"), - -("GLPK","GLPK","minisat1","minisat1(glp_prob) - - The routine \"minisat1\" is a driver to MiniSat, a CNF-SAT solver - developed by Niklas Eén and Niklas Sörensson, Chalmers University - of Technology, Sweden. - - Returns 0 in case of success, or a non-zero flag specifying the - reason for failure: \"GLPK.EDATA\" (problem is not CNF-SAT), - \"GLPK.EFAIL\" (solver failure). - -"), - -("GLPK","GLPK","intfeas1","intfeas1(glp_prob, use_bound, obj_bound) - - The routine \"glp_intfeas1\" is a tentative implementation of an - integer feasibility solver based on a CNF-SAT solver (currently - MiniSat). \"use_bound\" is a flag: if zero, any feasible solution - is seeked, otherwise seraches for an integer feasible solution. - \"obj_bound\" is used only if \"use_bound\" is non-zero, and - specifies an upper/lower bound (for maximization/minimazion - respectively) to the objective function. - - All variables (columns) must either be binary or fixed. All - constraint and objective coeffient must be integer. - - Returns 0 in case of success, or a non-zero flag specifying the - reason for failure: \"GLPK.EDATA\" (problem data is not valid), - \"GLPK.ERANGE\" (integer overflow occurred), \"GLPK.EFAIL\" (solver - failure). - -"), - -("GZip","GZip","gzopen","gzopen(fname[, gzmode[, buf_size]]) - - Opens a file with mode (default \"\"r\"\"), setting internal buffer - size to buf_size (default \"Z_DEFAULT_BUFSIZE=8192\"), and returns - a the file as a \"GZipStream\". - - \"gzmode\" must contain one of - - +------+-----------------------------------+ - | r | read | - +------+-----------------------------------+ - | w | write, create, truncate | - +------+-----------------------------------+ - | a | write, create, append | - +------+-----------------------------------+ - - In addition, gzmode may also contain - - +-------+-----------------------------------+ - | x | create the file exclusively | - +-------+-----------------------------------+ - | 0-9 | compression level | - +-------+-----------------------------------+ - - and/or a compression strategy: - - +------+-----------------------------------+ - | f | filtered data | - +------+-----------------------------------+ - | h | Huffman-only compression | - +------+-----------------------------------+ - | R | run-length encoding | - +------+-----------------------------------+ - | F | fixed code compression | - +------+-----------------------------------+ - - Note that \"+\" is not allowed in gzmode. - - If an error occurs, \"gzopen\" throws a \"GZError\" - -"), - -("GZip","GZip","gzdopen","gzdopen(fd[, gzmode[, buf_size]]) - - Create a \"GZipStream\" object from an integer file descriptor. See - \"gzopen()\" for \"gzmode\" and \"buf_size\" descriptions. - -"), - -("GZip","GZip","gzdopen","gzdopen(s[, gzmode[, buf_size]]) - - Create a \"GZipStream\" object from \"IOStream\" \"s\". - -"), - -("GZip","GZip","GZipStream","type GZipStream(name, gz_file[, buf_size[, fd[, s]]]) - - Subtype of \"IO\" which wraps a gzip stream. Returned by - \"gzopen()\" and \"gzdopen()\". - -"), - -("GZip","GZip","GZError","type GZError(err, err_str) - - gzip error number and string. Possible error values: - - +-----------------------+------------------------------------------+ - | \\\"Z_OK\\\" | No error | - +-----------------------+------------------------------------------+ - | \\\"Z_ERRNO\\\" | Filesystem error (consult \\\"errno()\\\") | - +-----------------------+------------------------------------------+ - | \\\"Z_STREAM_ERROR\\\" | Inconsistent stream state | - +-----------------------+------------------------------------------+ - | \\\"Z_DATA_ERROR\\\" | Compressed data error | - +-----------------------+------------------------------------------+ - | \\\"Z_MEM_ERROR\\\" | Out of memory | - +-----------------------+------------------------------------------+ - | \\\"Z_BUF_ERROR\\\" | Input buffer full/output buffer empty | - +-----------------------+------------------------------------------+ - | \\\"Z_VERSION_ERROR\\\" | zlib library version is incompatible | - +-----------------------+------------------------------------------+ - -"), - - -("OptionsMod","OptionsMod","@options","@options([check_flag], assignments...) - - Use the \"@options\" macro to set the value of optional parameters - for a function that has been written to use them (see - \"defaults()\" to learn how to write such functions). The syntax - is: - - opts = @options a=5 b=7 - - For a function that uses optional parameters \"a\" and \"b\", this - will override the default settings for these parameters. You would - likely call that function in the following way: - - myfunc(requiredarg1, requiredarg2, ..., opts) - - Most functions written to use optional arguments will probably - check to make sure that you are not supplying parameters that are - never used by the function or its sub-functions. Typically, - supplying unused parameters will result in an error. You can - control the behavior this way: - - # throw an error if a or b is not used (the default) - opts = @options CheckError a=5 b=2 - # issue a warning if a or b is not used - opts = @options CheckWarn a=5 b=2 - # don't check whether a and b are used - opts = @options CheckNone a=5 b=2 - - As an alternative to the macro syntax, you can also say: - - opts = Options(CheckWarn, :a, 5, :b, 2) - - The check flag is optional. - -"), - -("OptionsMod","OptionsMod","@set_options","@set_options(opts, assigments...) - - The \"@set_options\" macro lets you add new parameters to an - existing options structure. For example: - - @set_options opts d=99 - - would add \"d\" to the set of parameters in \"opts\", or re-set its - value if it was already supplied. - -"), - -("OptionsMod","OptionsMod","@defaults","@defaults(opts, assignments...) - - The \"@defaults\" macro is for writing functions that take optional - parameters. The typical syntax of such functions is: - - function myfunc(requiredarg1, requiredarg2, ..., opts::Options) - @defaults opts a=11 b=2a+1 c=a*b d=100 - # The function body. Use a, b, c, and d just as you would - # any other variable. For example, - k = a + b - # You can pass opts down to subfunctions, which might supply - # additional defaults for other variables aa, bb, etc. - y = subfun(k, opts) - # Terminate your function with check_used, then return values - @check_used opts - return y - end - - Note the function calls \"@check_used()\" at the end. - - It is possible to have more than one Options parameter to a - function, for example: - - function twinopts(x, plotopts::Options, calcopts::Options) - @defaults plotopts linewidth=1 - @defaults calcopts n_iter=100 - # Do stuff - @check_used plotopts - @check_used calcopts - end - - Within a given scope, you should only have one call to - \"@defaults\" per options variable. - -"), - -("OptionsMod","OptionsMod","@check_used","@check_used(opts) - - The \"@check_used\" macro tests whether user-supplied parameters - were ever accessed by the \"@defaults()\" macro. The test is - performed at the end of the function body, so that subfunction - handling parameters not used by the parent function may be - \"credited\" for their usage. Each sub-function should also call - \"@check_used\", for example: - - function complexfun(x, opts::Options) - @defaults opts parent=3 both=7 - println(parent) - println(both) - subfun1(x, opts) - subfun2(x, opts) - @check_used opts - end - - function subfun1(x, opts::Options) - @defaults opts sub1=\"sub1 default\" both=0 - println(sub1) - println(both) - @check_used opts - end - - function subfun2(x, opts::Options) - @defaults opts sub2=\"sub2 default\" both=22 - println(sub2) - println(both) - @check_used opts - end - -"), - -("OptionsMod","OptionsMod","Options","type Options(OptionsChecking, param1, val1, param2, val2, ...) - - \"Options\" is the central type used for handling optional - arguments. Its fields are briefly described below. - - key2index - - A \"Dict\" that looks up an integer index, given the symbol for - a variable (e.g., \"key2index[:a]\" for the variable \"a\") - - vals - - \"vals[key2index[:a]]\" is the value to be assigned to the - variable \"a\" - - used - - A vector of booleans, one per variable, with - \"used[key2index[:a]]\" representing the value for variable - \"a\". These all start as \"false\", but access by a - \"@defaults\" command sets the corresponding value to \"true\". - This marks the variable as having been used in the function. - - check_lock - - A vector of booleans, one per variable. This is a \"lock\" that - prevents sub-functions from complaining that they did not access - variables that were intended for the parent function. - \"@defaults()\" sets the lock to true for any options variables - that have already been defined; new variables added through - \"@set_options()\" will start with their \"check_lock\" set to - \"false\", to be handled by a subfunction. - -"), - -("profile.jl","","@profile","@profile() - - Profiling is controlled via the \"@profile\" macro. Your first step - is to determine which code you want to profile and encapsulate it - inside a \"@profile begin ... end\" block, like this: - - @profile begin - function f1(x::Int) - z = 0 - for j = 1:x - z += j^2 - end - return z - end - - function f1(x::Float64) - return x+2 - end - - function f1{T}(x::T) - return x+5 - end - - f2(x) = 2*x - end # @profile begin - - Now load the file and execute the code you want to profile, e.g.: - - f1(215) - for i = 1:100 - f1(3.5) - end - for i = 1:150 - f1(uint8(7)) - end - for i = 1:125 - f2(11) - end - - To view the execution times, type \"@profile report\". - - Here are the various options you have for controlling profiling: - - * \"@profile report\": display cumulative profiling results - - * \"@profile clear\": clear all timings accumulated thus far (start - from zero) - - * \"@profile off\": turn profiling off (there is no need to remove - \"@profile begin ... end\" blocks) - - * \"@profile on\": turn profiling back on - -"), - -("Punctuation","","punctuation","punctuation - - +-----------+---------------------------------------------------------------------------------------------+ - | symbol | meaning | - +===========+=============================================================================================+ - | \\\"@m\\\" | invoke macro m; followed by space-separated expressions | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"!\\\" | prefix \\\"not\\\" operator | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"!\\\" | at the end of a function name, indicates that a function modifies its argument(s) | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"#\\\" | begin single line comment | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"\\\$\\\" | xor operator, string and expression interpolation | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"%\\\" | remainder operator | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"^\\\" | exponent operator | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"&\\\" | bitwise and | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"*\\\" | multiply, or matrix multiply | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"()\\\" | the empty tuple | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"~\\\" | bitwise not operator | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"\\\\\\\" | backslash operator | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"a[]\\\" | array indexing | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"[,]\\\" | vertical concatenation | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"[;]\\\" | also vertical concatenation | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"[ ]\\\" | with space-separated expressions, horizontal concatenation | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"T{ }\\\" | parametric type instantiation | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"{ }\\\" | construct a cell array | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\";\\\" | statement separator | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\",\\\" | separate function arguments or tuple components | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"?\\\" | 3-argument conditional operator | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"\\\"\\\"\\\" | delimit string literals | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"''\\\" | delimit character literals | - +-----------+---------------------------------------------------------------------------------------------+ - | >>``<< | delimit external process (command) specifications | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"...\\\" | splice arguments into a function call, or declare a varargs function | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\".\\\" | access named fields in objects or names inside modules, also prefixes elementwise operators | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"a:b\\\" | range | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"a:s:b\\\" | range | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\":\\\" | index an entire dimension | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\"::\\\" | type annotation | - +-----------+---------------------------------------------------------------------------------------------+ - | \\\":( )\\\" | quoted expression | - +-----------+---------------------------------------------------------------------------------------------+ - -"), - -("Base.Sort","Base.Sort","sort","sort(v[, alg[, ord]]) - - Sort a vector in ascending order. Specify \"alg\" to choose a - particular sorting algorithm (\"Sort.InsertionSort\", - \"Sort.QuickSort\", \"Sort.MergeSort\", or \"Sort.TimSort\"), and - \"ord\" to sort with a custom ordering (e.g., Sort.Reverse or a - comparison function). - -"), - -("Base.Sort","Base.Sort","sort!","sort!(...) - - In-place sort. - -"), - -("Base.Sort","Base.Sort","sortby","sortby(v, by[, alg]) - - Sort a vector according to \"by(v)\". Specify \"alg\" to choose a - particular sorting algorithm (\"Sort.InsertionSort\", - \"Sort.QuickSort\", \"Sort.MergeSort\", or \"Sort.TimSort\"). - -"), - -("Base.Sort","Base.Sort","sortby!","sortby!(...) - - In-place \"sortby\". - -"), - -("Base.Sort","Base.Sort","sortperm","sortperm(v[, alg[, ord]]) - - Return a permutation vector, which when applied to the input vector - \"v\" will sort it. Specify \"alg\" to choose a particular sorting - algorithm (\"Sort.InsertionSort\", \"Sort.QuickSort\", - \"Sort.MergeSort\", or \"Sort.TimSort\"), and \"ord\" to sort with - a custom ordering (e.g., Sort.Reverse or a comparison function). - -"), - -("Base.Sort","Base.Sort","issorted","issorted(v[, ord]) - - Test whether a vector is in ascending sorted order. If specified, - \"ord\" gives the ordering to test. - -"), - -("Base.Sort","Base.Sort","searchsorted","searchsorted(a, x[, ord]) - - Returns the index of the first value of \"a\" equal to or - succeeding \"x\", according to ordering \"ord\" (default: - \"Sort.Forward\"). - - Alias for \"searchsortedfirst()\" - -"), - -("Base.Sort","Base.Sort","searchsortedfirst","searchsortedfirst(a, x[, ord]) - - Returns the index of the first value of \"a\" equal to or - succeeding \"x\", according to ordering \"ord\" (default: - \"Sort.Forward\"). - -"), - -("Base.Sort","Base.Sort","searchsortedlast","searchsortedlast(a, x[, ord]) - - Returns the index of the last value of \"a\" preceding or equal to - \"x\", according to ordering \"ord\" (default: \"Sort.Forward\"). - -"), - -("Base.Sort","Base.Sort","select","select(v, k[, ord]) - - Find the element in position \"k\" in the sorted vector \"v\" - without sorting, according to ordering \"ord\" (default: - \"Sort.Forward\"). - -"), - -("Base.Sort","Base.Sort","select!","select!(v, k[, ord]) +("Base.Sort","Base.Sort","select!","select!(v, k[, ord]) Version of \"select\" which permutes the input vector in place. "), -("Sound","Sound","wavread","wavread(io[, options]) - - Reads and returns the samples from a RIFF/WAVE file. The samples - are converted to floating point values in the range from -1.0 to - 1.0 by default. The \"io\" argument accepts either an \"IO\" object - or a filename (\"String\"). The options are passed via an - \"Options\" object (see the \"OptionsMod\" module). - - The available options, and the default values, are: - - * \"format\" (default = \"double\"): changes the format of the - returned samples. The string \"double\" returns double precision - floating point values in the range -1.0 to 1.0. The string - \"native\" returns the values as encoded in the file. The string - \"size\" returns the number of samples in the file, rather than - the actual samples. - - * \"subrange\" (default = \"Any\"): controls which samples are - returned. The default, \"Any\" returns all of the samples. - Passing a number (\"Real\"), \"N\", will return the first \"N\" - samples of each channel. Passing a range (\"Range1{Real}\"), - \"R\", will return the samples in that range of each channel. - - The returned values are: - - * \"y\": The acoustic samples; A matrix is returned for files that - contain multiple channels. - - * \"Fs\": The sampling frequency - - * \"nbits\": The number of bits used to encode each sample - - * \"extra\": Any additional bytes used to encode the samples (is - always \"None\") - - The following functions are also defined to make this function - compatible with MATLAB: - - wavread(filename::String) = wavread(filename, @options) - wavread(filename::String, fmt::String) = wavread(filename, @options format=fmt) - wavread(filename::String, N::Int) = wavread(filename, @options subrange=N) - wavread(filename::String, N::Range1{Int}) = wavread(filename, @options subrange=N) - wavread(filename::String, N::Int, fmt::String) = wavread(filename, @options subrange=N format=fmt) - wavread(filename::String, N::Range1{Int}, fmt::String) = wavread(filename, @options subrange=N format=fmt) - -"), - -("Sound","Sound","wavwrite","wavwrite(samples, io[, options]) - - Writes samples to a RIFF/WAVE file io object. The \"io\" - argument accepts either an \"IO\" object or a filename - (\"String\"). The function assumes that the sample rate is 8 kHz - and uses 16 bits to encode each sample. Both of these values can - be changed with the options parameter. Each column of the data - represents a different channel. Stereo files should contain two - columns. The options are passed via an \"Options\" object (see - the \"OptionsMod\" module). - - The available options, and the default values, are: - - * \"sample_rate\" (default = \"8000\"): sampling frequency - - * \"nbits\" (default = \"16\"): number of bits used to encode each - sample - - * \"compression\" (default = \"WAVE_FORMAT_PCM\"): The desired - compression technique; accepted values are: WAVE_FORMAT_PCM, - WAVE_FORMAT_IEEE_FLOAT - - The type of the input array, samples, also affects the generated - file. \"Native\" WAVE files are written when integers are passed - into wavwrite. This means that the literal values are written into - the file. The input ranges are as follows for integer samples. - - +--------+-------------+------------------------+---------------+ - | N Bits | y Data Type | y Data Range | Output Format | - +========+=============+========================+===============+ - | 8 | uint8 | 0 <= y <= 255 | uint8 | - +--------+-------------+------------------------+---------------+ - | 16 | int16 | –32768 <= y <= +32767 | int16 | - +--------+-------------+------------------------+---------------+ - | 24 | int32 | –2^23 <= y <= 2^23 – 1 | int32 | - +--------+-------------+------------------------+---------------+ - - If samples contains floating point values, the input data ranges - are the following. - - +--------+------------------+-------------------+---------------+ - | N Bits | y Data Type | y Data Range | Output Format | - +========+==================+===================+===============+ - | 8 | single or double | –1.0 <= y < +1.0 | uint8 | - +--------+------------------+-------------------+---------------+ - | 16 | single or double | –1.0 <= y < +1.0 | int16 | - +--------+------------------+-------------------+---------------+ - | 24 | single or double | –1.0 <= y < +1.0 | int32 | - +--------+------------------+-------------------+---------------+ - | 32 | single or double | –1.0 <= y <= +1.0 | single | - +--------+------------------+-------------------+---------------+ - - The following functions are also defined to make this function - compatible with MATLAB: - - wavwrite(y::Array) = wavwrite(y, @options) - wavwrite(y::Array, Fs::Real, filename::String) = wavwrite(y, filename, @options sample_rate=Fs) - wavwrite(y::Array, Fs::Real, N::Real, filename::String) = wavwrite(y, filename, @options sample_rate=Fs nbits=N) - -"), - -("TextWrap","TextWrap","wrap","wrap(string[, options]) - - Returns a string in which newlines are inserted as appropriate in - order for each line to fit within a specified width. - - The options are passed via an \"Options\" object (provided by the - \"OptionsMod\" module). The available options, and their default - values, are: - - * \"width\" (default = \"70\"): the maximum width of the wrapped - text, including indentation. - - * \"initial_indent\" (default = \"\"\"\"): indentation of the first - line. This can be any string (shorter than \"width\"), or it can - be an integer number (lower than \"width\"). - - * \"subsequent_indent\" (default = \"\"\"\"): indentation of all - lines except the first. Works the same as \"initial_indent\". - - * \"break_on_hyphens\" (default = \"true\"): this flag determines - whether words can be broken on hyphens, e.g. whether \"high- - precision\" can be split into \"high-\" and \"precision\". - - * \"break_long_words\" (default = \"true\"): this flag determines - what to do when a word is too long to fit in any line. If - \"true\", the word will be broken, otherwise it will go beyond - the desired text width. - - * \"replace_whitespace\" (default = \"true\"): if this flag is - true, all whitespace characters in the original text (including - newlines) will be replaced by spaces. - - * \"expand_tabs\" (default = \"true\"): if this flag is true, tabs - will be expanded in-place into spaces. The expansion happens - before whitespace replacement. - - * \"fix_sentence_endings\" (default = \"false\"): if this flag is - true, the wrapper will try to recognize sentence endings in the - middle of a paragraph and put two spaces before the next sentence - in case only one is present. - -"), - -("TextWrap","TextWrap","println_wrapped","print_wrapped(text...[, options]) -print_wrapped(io, text...[, options]) -println_wrapped(text...[, options]) -println_wrapped(io, text...[, options]) - - These are just like the standard \"print()\" and \"println()\" - functions (they print multiple arguments and accept an optional - \"IO\" first argument), except that they wrap the result, and - accept an optional last argument with the options to pass to - \"wrap()\". - -"), - -("Zlib","Zlib","compress_bound","compress_bound(input_size) - - Returns the maximum size of the compressed output buffer for a - given uncompressed input size. - -"), - -("Zlib","Zlib","compress","compress(source[, level]) - - Compresses source using the given compression level, and returns - the compressed buffer (\"Array{Uint8,1}\"). \"level\" is an - integer between 0 and 9, or one of \"Z_NO_COMPRESSION\", - \"Z_BEST_SPEED\", \"Z_BEST_COMPRESSION\", or - \"Z_DEFAULT_COMPRESSION\". It defaults to - \"Z_DEFAULT_COMPRESSION\". - - If an error occurs, \"compress\" throws a \"ZError\" with more - information about the error. - -"), - -("Zlib","Zlib","compress_to_buffer","compress_to_buffer(source, dest, level=Z_DEFAULT_COMPRESSION) - - Compresses the source buffer into the destination buffer, and - returns the number of bytes written into dest. - - If an error occurs, \"uncompress\" throws a \"ZError\" with more - information about the error. - -"), - -("Zlib","Zlib","uncompress","uncompress(source[, uncompressed_size]) - - Allocates a buffer of size \"uncompressed_size\", uncompresses - source to this buffer using the given compression level, and - returns the compressed buffer. If \"uncompressed_size\" is not - given, the size of the output buffer is estimated as - \"2*length(source)\". If the uncompressed_size is larger than - uncompressed_size, the allocated buffer is grown and the - uncompression is retried. - - If an error occurs, \"uncompress\" throws a \"ZError\" with more - information about the error. - -"), - -("Zlib","Zlib","uncompress_to_buffer","uncompress_to_buffer(source, dest) - - Uncompresses the source buffer into the destination buffer. Returns - the number of bytes written into dest. An error is thrown if the - destination buffer does not have enough space. - - If an error occurs, \"uncompress_to_buffer\" throws a \"ZError\" - with more information about the error. - -"), - } diff --git a/doc/stdlib/argparse.rst b/doc/stdlib/argparse.rst deleted file mode 100644 index 58f576017a662..0000000000000 --- a/doc/stdlib/argparse.rst +++ /dev/null @@ -1,861 +0,0 @@ -:mod:`ArgParse` --- Module for command-line argument parsing -============================================================ - -.. module:: ArgParse - :synopsis: Command line argument parser - -.. note:: located in ``argparse.jl`` - -This module allows the creation of user-friendly command-line interfaces to Julia programs: -the program defines which arguments, options and sub-commands it accepts, and the ``ArgParse`` module -does the actual parsing, issues errors when the input is invalid, and automatically generates help -and usage messages. - -Users familiar with Python's argparse module will find many similarities, but some important differences -as well. - -.. _argparse-overview: - ------------------------------------ -Quick overview and a simple example ------------------------------------ - -First of all, the module needs to be loaded and imported:: - - require("argparse") - using ArgParse - -Note that in the second line we imported all names in the current namespace; this should be completely safe in most cases. - -There are two main steps for defining a command-line interface: creating an ``ArgParseSettings`` object, and -populating it with allowed arguments and options using either the macro ``@add_arg_table`` or the function ``add_arg_table`` -(see :ref:`this section ` for the difference between the two):: - - s = ArgParseSettings() - @add_arg_table s begin - "--opt1" - help = "an option with an argument" - "--opt2", "-o" - help = "another option with an argument" - arg_type = Int - default = 0 - "--flag1" - help = "an option without argument, i.e. a flag" - action = :store_true - "arg1" - help = "a positional argument" - required = true - end - -In the macro, options and positional arguments are specified within a ``begin...end`` block, by one or more names -in a line, optionally followed by a list of settings. -So, in the above example, there are three options: - -* the first one, ``"--opt1"`` takes an argument, but doesn't check for its type, and it doesn't have a default value -* the second one can be invoked in two different forms (``"--opt2"`` and ``"-o"``); it also takes an argument, but - it must be of ``Int`` type (or convertible to it) and its default value is ``0`` -* the third one, ``--flag1``, is a flag, i.e. it doesn't take any argument. - -There is also only one positional argument, ``"arg1"``, which is declared mandatory. - -When the settings are in place, the actual argument parsing is performed via the ``parse_args`` function:: - - parsed_args = parse_args(ARGS, s) - -The parameter ``ARGS`` can be omitted. In case no errors are found, the result will be a ``Dict{String,Any}`` object. -In the above example, it will contain the keys ``"opt1"``, ``"opt2"``, ``"flag1"`` and ``"arg1"``, so that e.g. -``parsed_args["arg1"]`` will yield the value associated with the positional argument. - -Putting all this together in a file, we can see how a basic command-line interface is created:: - - require("argparse") - using ArgParse - - function parse_commandline() - s = ArgParseSettings() - - @add_arg_table s begin - "--opt1" - help = "an option with an argument" - "--opt2", "-o" - help = "another option with an argument" - arg_type = Int - default = 0 - "--flag1" - help = "an option without argument, i.e. a flag" - action = :store_true - "arg1" - help = "a positional argument" - required = true - end - - return parse_args(s) - end - - function main() - parsed_args = parse_commandline() - println("Parsed args:") - for pa in parsed_args - println(" $(pa[1]) => $(pa[2])") - end - end - - main() - -If we save this as a file called ``myprog1.jl``, we can see how a ``--help`` option is added by default, -and a help message is automatically generated and formatted:: - - $ julia myprog1.jl --help - usage: [--opt1 OPT1] [-o OPT2] [--flag1] [-h] arg1 - - positional arguments: - arg1 a positional argument - - optional arguments: - --opt1 OPT1 an option with an argument - -o, --opt2 OPT2 another option with an argument (type: Int64, - default: 0) - --flag1 an option without argument, i.e. a flag - -h, --help show this help message and exit - -Also, we can see how invoking it with the wrong arguments produces errors:: - - $ julia myprog1.jl - required argument arg1 was not provided - usage: [--opt1 OPT1] [-o OPT2] [--flag1] [-h] arg1 - - $ julia myprog1.jl somearg anotherarg - too many arguments - usage: [--opt1 OPT1] [-o OPT2] [--flag1] [-h] arg1 - - $ julia myprog1.jl --opt2 1.5 somearg - invalid argument: 1.5 (must be of type Int64) - usage: [--opt1 OPT1] [-o OPT2] [--flag1] [-h] arg1 - -When everything goes fine instead, our program will print the resulting ``Dict``:: - - $ julia myprog1.jl somearg - Parsed args: - arg1 => somearg - opt2 => 0 - opt1 => nothing - flag1 => false - - $ julia myprog1.jl --opt1 "2+2" --opt2 "2+2" somearg --flag - Parsed args: - arg1 => somearg - opt2 => 4 - opt1 => 2+2 - flag1 => true - -From these examples, a number of things can be noticed: - -* ``opt1`` defaults to ``nothing``, since no ``default`` setting was used for it in ``@add_arg_table`` -* ``opt1`` argument type, begin unspecified, defaults to ``Any``, but in practice it's parsed as a - string (e.g. ``"2+2"``) -* ``opt2`` instead has ``Int`` argument type, so ``"2+2"`` will be parsed as an expression and converted - to an integer -* positional arguments can be passed in between options -* long options can be passed in abbreviated form (e.g. ``--flag`` instead of ``--flag1``) as long as - there's no ambiguity - -.. _argparse-parse_args: - ---------------------------- -The ``parse_args`` function ---------------------------- - -.. function:: parse_args([args,] settings) - - This is the central function of the ``ArgParse`` module. It takes a ``Vector`` of arguments and an ``ArgParseSettings`` - objects (see :ref:`this section `), and returns a ``Dict{String,Any}``. - If ``args`` is not provided, the global variable ``ARGS`` will be used. - - The returned ``Dict`` keys are defined (possibly implicitly) in ``settings``, and their associated values are parsed - from ``args``. Special keys are used for more advanced purposes; at the moment, one such key exists: ``%COMMAND%`` - (see :ref:`this section `). - - Arguments are parsed in sequence and matched against the argument table in ``settings`` to determine whether they are - long options, short options, option arguments or positional arguments: - - * long options begin with a doule dash ``"--"``; if a ``'='`` character is found, the remainder is the option argument; - therefore, ``["--opt=arg"]`` and ``["--opt", "arg"]`` are equivalent if ``--opt`` takes at least one argument. - Long options can be abbreviated (e.g. ``--opt`` instead of ``--option``) as long as there is no ambiguity. - * short options begin with a single dash ``"-"`` and their name consists of a single character; they can be grouped - togheter (e.g. ``["-x", "-y"]`` can become ``["-xy"]``), but in that case only the last option in the group can - take an argument (which can also be grouped, e.g. ``["-a", "-f", "file.txt"]`` can be passed as - ``["-affile.txt"]`` if ``-a`` does not take an argument and ``-f`` does). The ``'='`` character can be used to - separate option names from option arguments as well (e.g. ``-af=file.txt``). - * positional arguments are anything else; they can appear anywhere. - - The special string ``"--"`` can be used to signal the end of all options; after that, everything is considered as a - positional argument (e.g. if ``args = ["--opt1", "--", "--opt2"]``, the parser will recognize ``--opt1`` as a long - option without argument, and ``--opt2`` as a positional argument). - - The special string ``"-"`` is always parsed as a positional argument. - - The parsing can stop early if a ``:show_help`` or ``:show_version`` action is triggered, or if a parsing error is - found. - - Some ambiguities can arise in parsing, see :ref:`this section ` for a detailed description - of how they're solved. - -.. _argparse-settings-overview: - ------------------ -Settings overview ------------------ - -The ``ArgParseSettings`` object contains all the settings to be used during argument parsing. Settings are divided -in two groups: general settings and argument-table-related settings. -While the argument table requires specialized functions such as ``add_arg_table`` to be defined and manipulated, -general settings are simply object fields (most of them are ``Bool`` or ``String``) and can be set directly at any -time. - -.. _argparse-general-settings: - ----------------- -General settings ----------------- - -This is the list of general settings currently available: - -* ``prog`` (default = ``""``): the name of the program, as displayed in the auto-generated help and usage screens. - If left empty, ``""`` will be used. -* ``description`` (default = ``""``): a description of what the program does, to be displayed in the auto-generated - help-screen, between the usage lines and the arguments description. It will be automatically formatted. -* ``epilog`` (default = ``""``): like ``description``, but will be discplayed at the end of the help-screen, after the - arguments description. -* ``usage`` (default = ``""``): the usage line(s) to be displayed in the help screen and when an error is found during parsing. - If left empty, it will be auto-generated. -* ``version`` (default = ``""Unknown version"``): version information. It's used by the ``:show_version`` action. -* ``add_help`` (default = ``true``): if ``true``, a ``--help, -h`` option (triggering the ``:show_help`` action) is added - to the argument table. -* ``add_version`` (default = ``false``): if ``true``, a ``--version`` option (triggering the ``:show_version`` action) is added - to the argument table. -* ``error_on_conflict`` (default = ``true``): if ``true``, throw an error in case conflicting entries are added to the argument table; - if ``false``, later entries will silently take precedence. - See :ref:`this section ` for a detailed description of what conflicts are and what is the exact behavior - when this setting is ``false``. -* ``suppress_warnings`` (default = ``false``): is ``true``, all warnings will be suppressed. -* ``allow_ambiguous_opts`` (default = ``false``): if ``true``, ambiguous options such as ``-1`` will be accepted. -* ``commands_are_required`` (default = ``true``): if ``true``, commands will be mandatory. See :ref:`this section ` - for more information on commands. -* ``exc_handler``: this is a function which is invoked when an error is detected during parsing (e.g. an option is not - recognized, a required argument is not passed etc.). It takes two arguments: the ``settings::ArgParseSettings`` object and the - ``err::ArgParseError`` exception. The default handler prints the error text and the usage screen on standard error and exits. - -Here is a usage example:: - - settings = ArgParseSettings() - settings.prog = "myprogram" - settings.description = "This program does something." - settings.add_version = true - settings.allow_ambiguous_opts = true - -As a shorthand for most common settings, the ``ArgParseSettings`` contructor accepts two optional fields, ``prog`` and -``description``. - -Most settings won't take effect until ``parse_args`` is invoked, but a few will have immediate effects: ``error_on_conflict``, -``suppress_warnings``, ``allow_ambiguous_opts``. - -.. _argparse-argument-table-basics: - ---------------------- -Argument table basics ---------------------- - -The argument table is used to store allowed arguments and options in an ``ArgParseSettings`` object. There are two very similar -methods to populate it: - -.. function:: @add_arg_table(settings, table...) - - This macro adds a table of arguments and options to the given ``settings``. It can be invoked multiple times. The arguments groups - are determined automatically, or the current default group is used if specified (see :ref:`this section ` for - more details). - - The ``table`` is a list in which each element can be either ``String``, or a tuple or a vector of ``String``, or an assigmment - expression, or a block: - - * a ``String``, a tuple or a vector introduces a new positional argument or option. Tuples and vectors are only allowed for options and - provide alternative names (e.g. ``["--opt", "-o"]``) - * assignment expressions (i.e. expressions using ``=``, ``:=`` or ``=>``) describe the previous argument behavior (e.g. - ``help = "an option"`` or ``required => false``). See :ref:`this section ` for a complete description - * blocks (``begin...end`` or lists of expressions in parentheses separated by semicolons) are useful to group entries and span - multiple lines. - - These rules allow for a variety usage styles, which are discussed in :ref:`this section `. - In the rest of this document, we will mostly use this style:: - - @add_arg_table settings begin - "--opt1", "-o" - help = "an option with an argument" - "--opt2" - "arg1" - help = "a positional argument" - required = true - end - - In the above example, the ``table`` is put in a single ``begin...end`` block and the line ``"-opt1", "-o"`` is parsed as a tuple; - indentation is used to help readability. - -.. function:: add_arg_table(settings, [arg_name [,arg_options]]...) - - This function is almost equivalent to the macro version. Its syntax is stricter (tuples and blocks are not allowed and argument options - are explicitly specified as ``Options`` objects) but the ``arg_name`` entries need not be explicit, they can be anything which evaluates - to a ``String`` or a ``Vector{String}``. - - Example:: - - add_arg_table(settings, - ["--opt1", "-o"], - @options begin - help = "an option with an argument" - end, - "--opt2", - "arg1", - @options begin - help = "a positional argument" - required = true - end) - - Note that the :mod:`OptionsMod` module must be imported in order to use this function. - -.. _argparse-argument-table-entries: - ----------------------- -Argument table entries ----------------------- - -Argument table entries consist of an argument name and a list of argument settings, e.g.:: - - "--verbose" - help = "verbose output" - action = :store_true - -.. _argparse-argument-names: - -Argument names --------------- - -Argument names are strings or, in the case of options, lists of strings. An argument is an option if it begins with a ``'-'`` -character, otherwise it'a positional argument. A single ``'-'`` introduces a short option, which must consist of a single -character; long options begin with ``"--"`` instead. - -Positional argument names can be any string, except all-uppercase strings between ``'%'`` characters, which are reserved -(e.g. ``"%COMMAND%"``). -Option names can contain any character except ``'='``, whitespaces and non-breakable spaces. -Depending on the value of the ``add_help`` and ``add_version`` settings, options ``--help``, ``-h`` and ``--version`` may -be reserved. -If the ``allow_ambiguous_opts`` setting is ``false``, some characters are not allowed as short options: all digits, the dot, -the underscore and the opening parethesis (e.g. ``-1``, ``-.``, ``-_``, ``-(``). - -For positional arguments, the argument name will be used as the key in the ``Dict`` object returned by the ``parse_args`` function. -For options, it will be used to produce a default key in case a ``dest_name`` is not explicitly specified in the table entry, using -either the first long option name in the list or the first short option name if no long options are present. For example: - -+--------------------------------+---------------------------+ -| argument name | default ``dest_name`` | -+================================+===========================+ -| ``"--long"`` | ``"long"`` | -+--------------------------------+---------------------------+ -| ``"--long", "-s"`` | ``"long"`` | -+--------------------------------+---------------------------+ -| ``"-s", "--long1", "--long2"`` | ``"long1"`` | -+--------------------------------+---------------------------+ -| ``"-s", "-x"`` | ``"s"`` | -+--------------------------------+---------------------------+ - -The argument name is also used to generate a default metavar in case ``metavar`` is not explicitly set in the table entry. The rules -are the same used to determine the default ``dest_name``, but for options the result will be uppercased (e.g. ``"--long"`` will -become ``LONG``). Note that this poses additional constraints on the positional argument names (e.g. whitespaces are not allowed in -metavars). - -.. _argparse-arg-entry-settings: - -Argument entry settings ------------------------ - -Argument entry settings determine all aspects of an argument's behavior. Some settings combinations are contradictory and will produce -an error (e.g. using both ``action = :store_true`` and ``nargs = 1``, or using ``action = :store_true`` with a positional argument). -Also, some settings are only meaningful under some conditions (e.g. passing a ``metavar`` to a flag-like option does not make sense) -and will be ignored with a warning (unless the ``suppress_warnings`` general setting is ``true``). - -This is the list of all available settings: - -* ``nargs`` (default = ``'A'``): the number of extra command-line tokens parsed with the entry. See - :ref:`this section ` for a complete desctiption. -* ``action``: the action performed when the argument is parsed. It can be passed as a ``String`` or as a ``Symbol`` (e.g. both - ``:store_arg`` and ``"store_arg"`` are accepted). The default action is ``:store_arg`` unless ``nargs`` is ``0``, in which case the - default is ``:store_true``. See :ref:`this section ` for a list of all available actions and a detailed - explanation. -* ``arg_type`` (default = ``Any``): the type of the argument. Makes only sense with non-flag arguments. -* ``default`` (default = ``nothing``): the default value if the option or positional argument is not parsed. Makes only sense with - non-flag arguments, or when the action is ``:store_const`` or ``:append_const``. Unless it's ``nothing``, it must be coherent with - ``arg_type`` and ``range_tester``. -* ``constant`` (default = ``nothing``): this value is used by the ``:store_const`` and ``:append_const`` actions, or when ``nargs = '?'`` - and the option argument is not provided. -* ``required`` (default = ``false``): determines if a positional argument is required (this setting is ignored by options, which are always - optional). -* ``range_tester`` (default = ``x->true``): a function returning a ``Bool`` value which tests whether an argument is allowed (e.g. - you could use ``arg_type = Integer`` and ``range_tester = isodd`` to allow only odd integer values) -* ``dest_name`` (default = auto-generated): the key which will be associated with the argument in the ``Dict`` object returned by - ``parse_args``. The auto-generation rules are explained in :ref:`this section `. Multiple arguments can share - the same destination, provided their actions and types are compatible. -* ``help`` (default = ``""``): the help string which will be shown in the auto-generated help screen. It's a ``String`` which will - be automaticaly formatted; also, ``arg_type`` and ``default`` will be automatically appended to it if provided. -* ``metavar`` (default = auto-generated): a token which will be used in usage and help screens to describe the argument syntax. For - positional arguments, it will also be used as an identifier in all other messages (e.g. in reporting errors), therefore it must - be unique. The auto-generations rules are explained in :ref:`this section `. -* ``force_override``: if ``true``, conflicts are ignored when adding this entry in the argument table (see also :ref:`this section - `). By default, - it follows the general ``error_on_conflict`` settings). -* ``group``: the option group to which the argument will be assigned to (see :ref:`this section `). By default, the - current default group is used if specified, otherwise the assignment is automatic. - -.. _argparse-actions-and-nargs: - -Available actions and nargs values ----------------------------------- - -The ``nargs`` and ``action`` argument entry settings are used together to determine how many tokens will be parsed from the command -line and what action will be performed on them. - -The ``nargs`` setting can be a number or a character; the possible values are: - -* ``'A'``: automatic, i.e. inferred from the action (this is the default). In practice, it means ``0`` for flag-like options and ``1`` - for non-flag-like options (but it's different from using an explicit ``1`` because the result is not stored in a ``Vector``). -* ``0``: this is the only option (besides ``'A'``) for flag-like actions (see below), and it means no extra tokens will be parsed from - the command line. If ``action`` is not specified, setting ``nargs`` to ``0`` will make ``action`` default to ``:store_true``. -* a positive integer number ``N``: exactly ``N`` tokens will be parsed from the command-line, and the result stored into a ``Vector`` - of length ``N`` (even for ``N=1``). -* ``'?'``: optional, i.e. a token will only be parsed if it does not look like an option (see :ref:`this section ` - for a discussion of how exactly this is established), otherwise the ``constant`` argument entry setting will be used instead. - This only makes sense with options. -* ``'*'``: any number, i.e. all subsequent tokens which do not look like an option are stored into a ``Vector``. -* ``'+'``: like ``'*'``, but at least one token is required. -* ``'R'``: all remainder tokens, i.e. like ``'*'`` but it does not stop at options. - -Actions can be categorized in many ways; one prominent distinction is flag vs. non-flag: some actions are for options which take no -argument (i.e. flags), all others (except ``command``, which is special) are for other options and positional arguments: - -* flag actions are only compatible with ``nargs = 0`` or ``nargs = 'A'`` -* non-flag actions are not compatible with ``nargs = 0``. - -This is the list of all available actions (in each examples, suppose we defined ``settings = ArgParseSettings()``): - -* ``store_arg`` (non-flag): store the argument. This is the default unless ``nargs`` is ``0``. Example:: - - julia> @add_arg_table(settings, "arg", action => :store_arg); - - julia> parse_args(["x"], settings) - {"arg"=>"x"} - - The result is a vector if ``nargs`` is a non-zero number, or one of ``'*'``, ``'+'``, ``'R'``:: - - julia> @add_arg_table(settings, "arg", action => :store_arg, nargs => 2); - - julia> parse_args(["x", "y"], settings) - {"arg"=>{"x", "y"}} - -* ``store_true`` (flag): store ``true`` if given, otherwise ``false``. Example:: - - julia> @add_arg_table(settings, "-v", action => :store_true); - - julia> parse_args([], settings) - {"v"=>false} - - julia> parse_args(["-v"], settings) - {"v"=>true} - -* ``store_false`` (flag): store ``false`` if given, otherwise ``true``. Example:: - - julia> @add_arg_table(settings, "-v", action => :store_false); - - julia> parse_args([], settings) - {"v"=>true} - - julia> parse_args(["-v"], settings) - {"v"=>false} - -* ``store_const`` (flag): store the value passed as ``constant`` in the entry settings if given, otherwise ``default``. - Example:: - - julia> @add_arg_table(settings, "-v", action => :store_const, constant => 1, default => 0); - - julia> parse_args([], settings) - {"v"=>0} - - julia> parse_args(["-v"], settings) - {"v"=>1} - -* ``append_arg`` (non-flag): append the argument to the result. Example:: - - julia> @add_arg_table(settings, "-x", action => :append_arg); - - julia> parse_args(["-x", "1", "-x", "2"], settings) - {"x"=>{"1", "2"}} - - The result will be a ``Vector{Vector}`` if ``nargs`` is a non-zero number, or one of ``'*'``, ``'+'``, ``'R'``:: - - julia> @add_arg_table(settings, "-x", action => :append_arg, nargs => '*'); - - julia> parse_args(["-x", "1", "2", "-x", "3"], settings) - {"x"=>{{"1", "2"}, {"3"}} - -* ``append_const`` (flag): append the value passed as ``constant`` in the entry settings. Example:: - - julia> @add_arg_table(settings, "-x", action => :append_const, constant => 1); - - julia> parse_args(["-x", "-x", "-x"], settings) - {"x"=>{1, 1, 1}} - -* ``count_invocations`` (flag): increase a counter; the final result will be the number of times the option was - invoked. Example:: - - julia> @add_arg_table(settings, "-x", action => :count_invocations); - - julia> parse_args(["-x", "-x", "-x"], settings) - {"x"=>3} - -* ``show_help`` (flag): show the help screen and exit. This is useful if the ``add_help`` general setting is - ``false``. Example:: - - julia> settings.add_help = false; - - julia> @add_arg_table(settings, "-x", action => :show_help); - - julia> parse_args(["-x"], settings) - usage: [-x] - - optional arguments: - -x - -* ``show_version`` (flag): show the version information and exit. This is useful if the ``add_version`` general - setting is ``false``. Example:: - - julia> settings.version = "1.0"; - - julia> @add_arg_table(settings, "-x", action => :show_version); - - julia> parse_args(["-v"], settings) - 1.0 - -* ``command`` (special): the argument or option is a command, i.e. it starts a sub-parsing session (see :ref:`this section - `) - -.. _argparse-commands: - -Commands --------- - -Commands are a special kind of arguments which introduce sub-parsing sessions as soon as they are encountered by ``parse_args`` -(and are therefore mutually exclusive). -The ``ArgParse`` module allows commands to look both as positional arguments or as flags, with minor differences between the two. - -Commands are introduced by the ``action = :command`` setting in the argument table. Suppose we save the following script in -a file called ``cmd_example.jl``:: - - require("argparse") - using ArgParse - - function parse_commandline() - s = ArgParseSettings("cmd_example.jl") - - @add_arg_table s begin - "cmd1" - help = "first command" - action = :command - "cmd2" - help = "second command" - action = :command - end - - return parse_args(s) - end - - parsed_args = parse_commandline() - println(parsed_args) - -Invoking the script from the command line, we would get the following help screen:: - - $ julia cmd_example.jl --help - usage: cmd_example.jl [-h] {cmd1|cmd2} - - commands: - cmd1 first command - cmd2 second command - - optional arguments: - -h, --help show this help message and exit - -If commands are present in the argument table, ``parse_args`` will set the special key ``"%COMMAND%"`` in the returned ``Dict`` and -fill it with the invoked command (or ``nothing`` if no command was given):: - - $ julia cmd_example.jl cmd1 - {"%COMMAND%"=>"cmd1", "cmd1"=>{}} - -Since commands introduce sub-parsing sessions, an additional key will be added for the called command (``"cmd1"`` in this case) whose -associated value is another ``Dict{String, Any}`` containing the result of the sub-parsing (in the above case it's empty). In fact, -with the default settings, commands have their own help screens:: - - $ julia cmd_example.jl cmd1 --help - usage: cmd_example.jl cmd1 [-h] - - optional arguments: - -h, --help show this help message and exit - -The argument settings and tables for commands can be accessed by using a dict-like notation, i.e. ``settings["cmd1"]`` is an -``ArgParseSettings`` object specific to the ``"cmd1"`` command. Therefore, to populate a command sub-argument-table, simply -use ``@add_arg_table(settings["cmd1"], table...)`` and similar. - -These sub-settings are created when a command is added to the argument table, and by default they inherit their parent general -settings except for the ``prog`` setting (which is auto-generated, as can be seen in the above example) and the -``description``, ``epilog`` and ``usage`` settings (which are left empty). - -Commands can also have sub-commands. - -By default, if commands exist, they are required; this can be avoided by setting the ``commands_are_required = false`` general setting. - -The only meaningful settings for commands in an argument entry besides ``action`` are ``help``, ``force_override``, ``group`` and -(for flags only) ``dest_name``. - -The only differences between positional-arguments-like and flag-like commands are in the way they are parsed, the fact that flags -accept a ``dest_name`` setting, and that flags can have multiple names (e.g. a long and short form). - -Note that short-form flag-like commands will be still be recognized in the middle of a short options group and trigger a sub-parsing -session: for example, if a flag ``-c`` is associated to a command, then ``-xch`` will parse option ``-x`` according to the parent -settings, and option ``-h`` according to the command sub-settings. - -.. _argparse-groups: - -Argument groups ---------------- - -By default, the auto-generated help screen divides arguments into three groups: commands, positional arguments and optional -arguments, displayed in that order. Example:: - - julia> settings = ArgParseSettings(); - - julia> @add_arg_table settings begin - "--opt" - "arg" - required = true - "cmd1" - action = :command - "cmd2" - action = :command - end; - - julia> parse_args(["--help"], settings) - usage: [--opt OPT] [-h] arg {cmd1|cmd2} - - commands: - cmd1 - cmd2 - - positional arguments: - arg - - optional arguments: - --opt OPT - -h, --help show this help message and exit - -It is possible to partition the arguments differently by defining and using customized argument groups. - -.. function:: add_arg_group(settings, description, [name , [set_as_default]]) - - This function adds an argument group to the argument table in ``settings``. The ``description`` is a ``String`` used in - the help screen as a title for that group. The ``name`` is a unique name which can be provided to refer to that group - at a later time. - - After invoking this function, all subsequent invocations of the ``@add_arg_table`` macro and ``add_arg_table`` function - will use the new group as the default, unless ``set_as_default`` is set to ``false`` (the default is ``true``, and the option - can only be set if providing a ``name``). Therefore, the most obvious usage pattern is: for each group, add it and populate - the argument table of that group. Example:: - - julia> settings = ArgParseSettings(); - - julia> add_arg_group(settings, "custom group"); - - julia> @add_arg_table settings begin - "--opt" - "arg" - end; - - julia> parse_args(["--help"], settings) - usage: [--opt OPT] [-h] [arg] - - optional arguments: - -h, --help show this help message and exit - - custom group: - --opt OPT - arg - - As seen from the example, new groups are always added at the end of existing ones. - - The ``name`` can also be passed as a ``Symbol``. Forbidden names are the standard groups names (``"command"``, - ``"positional"`` and ``"optional"``) and those beginning with a hash character ``'#'``. - -.. function:: set_default_arg_group(settings, [name]) - - Set the default group for subsequent invocations of the ``@add_arg_table`` macro and ``add_arg_table`` function. - ``name`` is a ``String``, and must be one of the standard group names (``"command"``, ``"positional"`` or - ``"optional"``) or one of the user-defined names given in ``add_arg_group`` (groups with no assigned name cannot be - used with this function). - - If ``name`` is not provided or is the empty string ``""``, then the default behavior is reset (i.e. arguments will be - automatically assigned to the standard groups). - The ``name`` can also be passed as a ``Symbol``. - -Besides setting a default group with ``add_arg_group`` and ``set_default_group``, it's also possible to assign individual arguments -to a group by using the ``group`` setting in the argument table entry, which follows the same rules as ``set_default_group``. - -Note that if the ``add_help`` or ``add_version`` general settings are ``true``, the ``--help, -h`` and ``--version`` options -will always be added to the ``optional`` group. - -.. _argparse-import-settings: - ------------------- -Importing settings ------------------- - -It may be useful in some cases to import an argument table into the one which is to be used, for example to create -specialized versions of a common interface. - -.. function:: import_settings(settings, other_settings [,args_only]) - - Imports ``other_settings`` into ``settings``, where both are ``ArgParseSettings`` objects. If ``args_only`` is - ``true`` (this is the default), only the argument table will be imported; otherwise, the default argument group - will also be imported, and all general settings except ``prog``, ``description``, ``epilog`` and ``usage``. - - Sub-settings associated with commands will also be imported recursively; the ``args_only`` setting applies to - those as well. If there are common commands, their sub-settings will be merged. - - While importing, conflicts may arise: if ``settings.error_on_conflict`` is ``true``, this will result in an error, - otherwise conflicts will be resolved in favor of ``other_settings`` (see :ref:`this section ` - for a detailed discussion of how conflicts are handled). - - Argument groups will also be imported; if two groups in ``settings`` and ``other_settings`` match, they are merged - (groups match either by name, or, if unnamed, by their description). - - Note that the import will have effect immediately: any subsequent modification of ``other_settings`` will not have - any effect on ``settings``. - - This function can be used at any time. - -.. _argparse-conflicts: - ------------------------ -Conflicts and overrides ------------------------ - -Conflicts between arguments, be them options, positional arguments or commands, can arise for a variety of reasons: - -* Two options have the same name (either long or short) -* Two arguments have the same destination key, but different types (e.g. one is ``Any`` and the other ``String``) -* Two arguments have the same destination key, but incompatible actions (e.g. one does ``:store_arg`` and the other - ``:append_arg``) -* Two positional arguments have the same metavar (and are therefore indistinguishable in the usage and help screens - and in error messages) -* An argument and a command, or two commands, have the same destination key. - -When the general setting ``error_on_conflict`` is ``true``, or any time the specific ``force_override`` table entry -setting is ``false``, any of the above conditions leads to an error. - -On the other hand, setting ``error_on_conflict`` to ``false``, or ``force_override`` to ``true``, will try to force -the resolution of most of the conflicts in favor of the newest added entry. The general rules are the following: - -* In case of duplicate options, all conflicting forms of the older options are removed; if all forms of an - option are removed, the option is deleted entirely -* In case of duplicate destination key and incompatible types or actions, the older argument is deleted -* In case of duplicate positional arguments metavars, the older argument is deleted -* A command can override an argument with the same destination key -* However, an argument can never override a command if they have the same destination key; neither can - a command override another command when added with ``@add_arg_table`` (compatible commands are merged - by ``import_settings`` though) - -.. _argparse-details: - ---------------- -Parsing details ---------------- - -During parsing, ``parse_args`` must determine whether an argument is an option, an option argument, a positional -argument, or a command. The general rules are explained in :ref:`this section `, but -ambiguities may arise under particular circumstances. In particular, negative numbers like ``-1`` or ``-.1e5`` -may look like options. Under the default settings, such options are forbidden, and therefore those tokens are -always recognized as non-options. However, if the ``allow_ambiguous_opts`` general setting is ``true``, existing -options in the argument table will take precedence: for example, if the option ``-1`` is added, and it takes an -argument, then ``-123`` will be parsed as that option, and ``23`` will be its argument. - -Some ambiguities still remains though, because the ``ArgParse`` module will actually accept and parse expressions, -not only numbers, and therefore one may try to pass arguments like ``-e`` or ``-pi``; in that case, these will -always be at risk of being recognized as options. The easiest workaround is to put them in parentheses, -e.g. ``(-e)``. - -When an option is declared to accept a fixed positive number of arguments or the remainder of the command line -(i.e. if ``nargs`` is a non-zero number, or ``'A'``, or ``'R'``), ``parse_args`` will not try to check if the -argument(s) looks like an option. - -If ``nargs`` is one of ``'?'`` or ``'*'`` or ``'+'``, then ``parse_args`` will take in only arguments which do not -look like options. - -When ``nargs`` is ``'+'`` or ``'*'`` and an option is being parsed, then using the ``'='`` character will mark what -follows as an argument (i.e. not an option); all which follows goes under the rules explained above. The same is true -when short option groups are being parsed. For example, if the option in question is ``-x``, then both -``-y -x=-2 4 -y`` and ``-yx-2 4 -y`` will parse ``"-2"`` and ``"4"`` as the arguments of ``-x``. - -Finally, since expressions may be evaluated during parsing, note that there is no safeguard against passing -things like ``run(`rm -fr ~`)`` and seeing your data evaporate. Be careful. - -.. _argparse-table-styles: - ---------------------- -Argument table styles ---------------------- - -Here are some examples of styles for the ``@add_arg_table`` marco and ``add_arg_table`` function invocation:: - - @add_arg_table settings begin - "--opt", "-o" - help = "an option" - "arg" - help = "a positional argument" - end - - @add_arg_table(settings - , ["--opt", "-o"] - , help => "an option" - , "arg" - , help => "a positional argument" - ) - - @add_arg_table settings begin - (["--opt", "-o"]; help = an option) - ("arg"; help = "a positional argument") - end - - @add_arg_table(settings, - ["-opt", "-o"], - begin - help = "an option" - end, - "arg", - begin - help = "a positional argument" - end) - - add_arg_table(settings, - ["-opt", "-o"], @options(help := "an option"), - "arg" , @options(help := "a positional argument") - ) - -The restrictions are: - -* when using the function-like notation for macros (i.e. passing arguments in a comma-separated list - between parentheses), assignments can only use ``=>`` or ``:=``. In the examples above, this can be seen - both when using ``@add_arg_table`` and ``@options`` -* groups introduced by ``begin...end`` blocks or semicolon-separated list between parentheses cannot introduce - argument names unless the first item in the block is an argument name. diff --git a/doc/stdlib/glpk.rst b/doc/stdlib/glpk.rst deleted file mode 100644 index 241c3945239c3..0000000000000 --- a/doc/stdlib/glpk.rst +++ /dev/null @@ -1,1151 +0,0 @@ -:mod:`GLPK` --- Wrapper for the GNU Linear Programming Kit (GLPK) -================================================================= - -.. module:: GLPK - :synopsis: GLPK wrapper - -.. note:: located in ``glpk.jl`` - -This file provides a wrapper for the GNU Linear Programming Kit -(`GLPK `_), which is a C library, in Julia. -It is designed for making it easy to port C code to Julia, while at the same time having the -benefits of the higher level language features of Julia, like the automatic management of memory, the possibility -of returning tuples/strings/vectors etc. - -It's currently based on GLPK version 4.47. - --------- -Preamble --------- - -Almost all GLPK functions can be called in Julia with basically the same syntax as in the original C library, -with some simple translation rules (with very :ref:`few exceptions `). -Some functionality is still missing (see :ref:`this list `); most of it will be -added in the future. - -Let's start with an example. This is an excerpt from the beginning of the :file:`sample.c` example program -which ships with GLPK: - -.. code-block:: c - - /* C code */ - glp_prob *lp = glp_create_prob(); - glp_set_prob_name(lp, "sample"); - glp_set_obj_dir(lp, GLP_MAX); - glp_add_rows(lp, 3); - glp_set_row_name(lp, 1, "p"); - glp_set_row_bnds(lp, 1, GLP_UP, 0.0, 100.0); - -This is the Julia translation of the above:: - - # Julia code - lp = GLPK.Prob() - GLPK.set_prob_name(lp, "sample") - GLPK.set_obj_dir(lp, GLPK.MAX) - GLPK.add_rows(lp, 3) - GLPK.set_row_name(lp, 1, "p") - GLPK.set_row_bnds(lp, 1, GLPK.UP, 0.0, 100.0) - -Apart from the first line, which is different, the translation of subsequent lines follows the very simple -rule that function names and constants drop the prefixes ``glp_`` and ``GLP_``, and take the ``GLPK`` -module prefix instead (at the moment, constants are integer values, like in C, but this may change -in the future). -Note that, as with all Julia modules, the ``GLPK`` prefix could be omitted by adding a ``using GLPK`` -line in the code, but this is not advised in this case due to the very high number of functions with -relatively common names in the library. - -Because of the strict adherence of the Julia functions to their C counterparts, and since the GLPK -documentation is extremely well written and complete, this manual page is not going to document -the whole GLPK library in detail, but rather provide :ref:`the rules ` needed to translate -from C to Julia, detail the :ref:`few exceptions ` to these rules and then -:ref:`list all the available functions ` with a brief description of their -usage. - -Please, refer to the original GLPK manual (available at http://www.gnu.org/software/glpk) for a detailed -description of the library API. - -.. _glpk-translation-rules: - --------------------------------------- -GLPK translation rules from C to Julia --------------------------------------- - -1) functions and constants drop their prefix -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Almost all functions in the C library start with the prefix ``glp_``, and all constants start with -the prefix ``GLP_``. These prefixes are dropped in Julia, and the module prefix ``GLPK.`` is used -instead. For example, the function ``glp_simplex`` becomes ``GLPK.simplex``, and the constant -``GLP_UP`` becomes ``GLPK.UP``. - -2) from C stucts to Julia objects -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -All structs in the original GLPK are wrapped up in composite types, which initialize and destroy themselves -as needed. For example, the ``glp_prob`` C struct becomes the ``GLPK.Prob`` Julia type. -Whenever in C you would pass a pointer to a struct, in Julia you pass a corresponding composite object. -This is the table relating C structs with Julia types: - -+---------------+----------------------------+ -| C | Julia | -+===============+============================+ -| ``glp_prob`` | ``GLPK.Prob`` | -+---------------+----------------------------+ -| ``glp_smcp`` | ``GLPK.SimplexParam`` | -+---------------+----------------------------+ -| ``glp_iptcp`` | ``GLPK.InteriorParam`` | -+---------------+----------------------------+ -| ``glp_iocp`` | ``GLPK.IntoptParam`` | -+---------------+----------------------------+ -| ``glp_bfcp`` | ``GLPK.BasisFactParam`` | -+---------------+----------------------------+ -| ``glp_tran`` | ``GLPK.MathProgWorkspace`` | -+---------------+----------------------------+ -| ``glp_data`` | ``GLPK.Data`` | -+---------------+----------------------------+ - -Therefore, the original C GLPK API: - -.. code-block:: c - - int glp_simplex(glp_prob * lp, glp_smpc * param) - -becomes:: - - GLPK.simplex(lp::GLPK.Prob, param::GLPL.SimplexParam) - -In the C GLPK API, objects are created by functions, such as: - -.. code-block:: c - - glp_prob * lp = glp_create_prob(); - glp_smcp * param = glp_smcp_init(); - -and need to be destroyed when the program is finished: - -.. code-block:: c - - glp_delete_prob(lp); - glp_smcp_delete(smcp); - -In Julia, objects are created by calling the object constructor (without parameters):: - - lp = GLPK.Prob() - param = GLPK.SimplexParam() - -and they are automatically destroyed by the garbage collector when no longer needed. - - -3) setting the parameters to the solvers -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In all GLPK solver functions, like ``glp_simplex``, options are passed via structs. As stated before, these become -composite object types in Julia; but instead of setting a field, like in C: - -.. code-block:: c - - param = glp_smcp_init(); - param.msg_lev = GLP_MSG_ERR; - param.presolve = GLP_ON; - -in Julia one uses an array-like referencing syntax:: - - param = GLPK.SimplexParam() - param["msg_lev"]= GLPK.MSG_ERR - param["presolve"] = GLPK.ON - -Note that the field names are passed as strings, and that all GLPK constants are available in Julia. -Also note that no test is currently performed at assignment to check that the provided values are valid. - -This part of the API may change in the future. - - -4) scalar and array types translate in a natural way -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following C-to-Julia type conversion rules apply: - -+--------------+-------------+ -| C | Julia | -+==============+=============+ -| ``int`` | ``Int32`` | -+--------------+-------------+ -| ``double`` | ``Float64`` | -+--------------+-------------+ -| ``char[]`` | ``String`` | -+--------------+-------------+ -| ``glp_long`` | ``Int64`` | -+--------------+-------------+ - -On output, these rules apply exactly. On input, on the other hand, Julia requirements are more relaxed: - -+--------------+-------------+ -| C | Julia | -+==============+=============+ -| ``int`` | ``Integer`` | -+--------------+-------------+ -| ``glp_long`` | ``Integer`` | -+--------------+-------------+ -| ``double`` | ``Real`` | -+--------------+-------------+ - -Whenever the C version expects a pointer to an array, a Julia Array can be passed. In the GLPK API, all indexing -starts from 1 even in the C version, so no special care is required on that side (in C, you would leave an -unused element at the beginning of each array; in Julia you don't). - -The relaxed requirements for inputs are also valid for arrays (e.g. one can pass an ``Array{Int64}`` when an array -of ``int`` is expected, and it will be converted automatically). The only exception is for functions which -return an array of values by filling out an allocated array whose pointer is provided by the user. -In that case, the strict version of the rules applies (i.e. you can only pass an ``Array{Int32}`` if an -array of ``int`` is expected). Those functions almost always have an alternative, more convenient formulation -as well, though. - - -5) optional arguments -^^^^^^^^^^^^^^^^^^^^^ - -Whenever the C version accepts the value ``NULL`` to indicate an optional pointer argument, the Julia version -accepts the constant ``nothing``. In case the optional pointer argument is an array, an empty array is -also accepted (it can be of the expected type, e.g. ``Int32[]``, or even just ``[]``) -Most of the time, alternative ways to call the function are also provided. - - -6) fatal errors become exceptions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Whenever an invalid condition is detected (e.g. if you pass an invalid parameter, such as a negative length), -the Julia GLPK wrapper throws a ``GLPK.Error`` exception with some message detailing what went wrong. -Ideally, all invalid input combinations should be captured by Julia before being passed -over to the library, so that all errors could be catched via a ``try ... catch`` block; -in practice, it is likely that some conditions exist which will leak to the C API and break Julia: this should be -considered as a bug (and reported as such). - -.. _glpk-not-available: - ---------------------------------------------------- -GLPK functions which are not avaliable yet in Julia ---------------------------------------------------- - -In general, all parts of the GLPK API which rely on callback functions are not avaliable in Julia. -In particular, you should not set the callback fields (``cb_func`` and ``cb_info``) in the ``GLPK.IntoptParam`` -type, unless you *really* know what you're doing. - -There are 5 groups of functions which are not wrapped: - -1. The branch & cut API function for mixed integer programming, because they are supposed to be called from - within a callback (see chapter 5 in the GLPK manual); they all start with this prefix: - - * ``glp_ios_*`` - -2. All graph and network routines (anything involving ``glp_graph`` objects); these will be added in the future) - -3. Some misc functions which either have a variable argument list or involve callbacks (see section 6.1 in the GLPK - manual): - - * ``glp_printf`` - * ``glp_vprintf`` - * ``glp_term_hook`` - * ``glp_error`` - * ``glp_assert`` - * ``glp_error_hook`` - -4. Some plain data file reading routines which involve long jumps / varargs (see section 6.2 in the GLPK manual): - - * ``glp_sdf_set_jump`` - * ``glp_sdf_error`` - * ``glp_sdf_warning`` - - -5. One additional routine, which may be included in the future: - - * ``lpx_check_kkt`` - -.. _glpk-different-than-C: - ------------------------------------------------- -Functions which differ from their C counterparts ------------------------------------------------- - -Some library functions return multiple values; as C cannot do this directly, this is obtained via some "pointer gymnastics". -In Julia, on the other hand, this is not necessary, and providing an exact counterpart to the C version would be awkward and -pointless. There are 3 such functions: - -* ``GLPK.analyze_bound`` -* ``GLPK.analyze_coef`` -* ``GLPK.mem_usage`` - -For example the C declaration for ``glp_analyze_bound`` is: - -.. code-block:: c - - void glp_analyze_bound(glp_prob *lp, int k, int *limit1, int *var1, int *limit2, int *var2) - -In Julia, this becomes:: - - GLPK.analyze_bound(glp_prob::GLPK.Prob, k::Integer) - -which returns a tuple:: - - julia> (limit1, var1, limit2, var2) = GLPK.analyze_bound(glp_prob, k) - -The other 2 functions work in the same way, by just returning the values which in C you would pass -as pointers. - -Some other functions have both a strictly-compatible calling form, for simplifying C code porting, -and some more convenient Julia counterparts. See :ref:`the list below ` for more details. - -One function has a different return value: ``GLPK.version`` returns a tuple of integer with the major and minor -version numbers, rather then a string. - -.. _glpk-function-list: - -------------------------------- -List of GLPK functions in Julia -------------------------------- - -As stated above, this list only offers a brief explanation of what each function does and presents alternative -calling forms when available. Refer to the GLPK manual for a complete description. - -.. function:: set_prob_name(glp_prob, name) - - Assigns a name to the problem object (or deletes it if ``name`` is empty or ``nothing``). - -.. function:: set_obj_name(glp_prob, name) - - Assigns a name to the objective function (or deletes it if ``name`` is empty or ``nothing``). - -.. function:: set_obj_dir(glp_prob, dir) - - Sets the optimization direction, ``GLPK.MIN`` (minimization) or ``GLPK.MAX`` (maximization). - -.. function:: add_rows(glp_prob, rows) - - Adds the given number of rows (constraints) to the problem object; returns the number of - the first new row added. - -.. function:: add_cols(glp_prob, cols) - - Adds the given number of columns (structural variables) to the problem object; returns the number of - the first new column added. - -.. function:: set_row_name(glp_prob, row, name) - - Assigns a name to the specified row (or deletes it if ``name`` is empty or ``nothing``). - -.. function:: set_col_name(glp_prob, col, name) - - Assigns a name to the specified column (or deletes it if ``name`` is empty or ``nothing``). - -.. function:: set_row_bnds(glp_prob, row, bounds_type, lb, ub) - - Sets the type and bounds on a row. ``type`` must be one of ``GLPK.FR`` (free), ``GLPK.LO`` (lower bounded), - ``GLPK.UP`` (upper bounded), ``GLPK.DB`` (double bounded), ``GLPK.FX`` (fixed). - - At initialization, each row is free. - -.. function:: set_col_bnds(glp_prob, col, bounds_type, lb, ub) - - Sets the type and bounds on a column. ``type`` must be one of ``GLPK.FR`` (free), ``GLPK.LO`` (lower bounded), - ``GLPK.UP`` (upper bounded), ``GLPK.DB`` (double bounded), ``GLPK.FX`` (fixed). - - At initialization, each column is fixed at 0. - -.. function:: set_obj_coef(glp_prob, col, coef) - - Sets the objective coefficient to a column (``col`` can be 0 to indicate the constant term of the objective function). - -.. function:: set_mat_row(glp_prob, row, [len,] ind, val) - - Sets (replaces) the content of a row. The content is specified in sparse format: ``ind`` is a vector of indices, - ``val`` is the vector of corresponding values. ``len`` is the number of vector elements which will be considered, - and must be less or equal to the length of both ``ind`` and ``val``. If ``len`` is 0, ``ind`` and/or ``val`` can be ``nothing``. - - In Julia, ``len`` can be omitted, and then it is inferred from ``ind`` and ``val`` (which need to have the same length - in such case). - -.. function:: set_mat_col(glp_prob, col, [len,] ind, val) - - Sets (replaces) the content of a column. Everything else is like ``set_mat_row``. - -.. function:: load_matrix(glp_prob, [numel,] ia, ja, ar) - load_matrix(glp_prob, A) - - Sets (replaces) the content matrix (i.e. sets all rows/coluns at once). The matrix is passed in sparse - format. - - In the first form (original C API), it's passed via 3 vectors: ``ia`` and ``ja`` are for rows/columns - indices, ``ar`` is for values. ``numel`` is the number of elements which will be read and must be less or - equal to the length of any of the 3 vectors. If ``numel`` is 0, any of the vectors can be passed as ``nothing``. - - In Julia, ``numel`` can be omitted, and then it is inferred from ``ia``, ``ja`` and ``ar`` (which need to have the same length - in such case). - - Also, in Julia there's a second, simpler calling form, in which the matrix is passed as a ``SparseMatrixCSC`` object. - -.. function:: check_dup(rows, cols, [numel,] ia, ja) - - Check for duplicates in the indices vectors ``ia`` and ``ja``. ``numel`` has the same meaning and (optional) use as in - ``load_matrix``. Returns 0 if no duplicates/out-of-range indices are found, or a positive number indicating where a duplicate - occurs, or a negative number indicating an out-of-bounds index. - -.. function:: sort_matrix(glp_prob) - - Sorts the elements of the problem object's matrix. - -.. function:: del_rows(glp_prob, [num_rows,] rows_ids) - - Deletes rows from the problem object. Rows are specified in the ``rows_ids`` vector. ``num_rows`` is the number of elements - of ``rows_ids`` which will be considered, and must be less or equal to the length id ``rows_ids``. If ``num_rows`` is 0, ``rows_ids`` - can be ``nothing``. In Julia, ``num_rows`` is optional (it's inferred from ``rows_ids`` if not given). - -.. function:: del_cols(glp_prob, cols_ids) - - Deletes columns from the problem object. See ``del_rows``. - -.. function:: copy_prob(glp_prob_dest, glp_prob, copy_names) - - Makes a copy of the problem object. The flag ``copy_names`` determines if names are copied, and must be either ``GLPK.ON`` or ``GLPK.OFF``. - -.. function:: erase_prob(glp_prob) - - Resets the problem object. - -.. function:: get_prob_name(glp_prob) - - Returns the problem object's name. Unlike the C version, if the problem has no assigned name, returns an empty string. - -.. function:: get_obj_name(glp_prob) - - Returns the objective function's name. Unlike the C version, if the objective has no assigned name, returns an empty string. - -.. function:: get_obj_dir(glp_prob) - - Returns the optimization direction, ``GLPK.MIN`` (minimization) or ``GLPK.MAX`` (maximization). - -.. function:: get_num_rows(glp_prob) - - Returns the current number of rows. - -.. function:: get_num_cols(glp_prob) - - Returns the current number of columns. - -.. function:: get_row_name(glp_prob, row) - - Returns the name of the specified row. Unlike the C version, if the row has no assigned name, returns an empty string. - -.. function:: get_col_name(glp_prob, col) - - Returns the name of the specified column. Unlike the C version, if the column has no assigned name, returns an empty string. - -.. function:: get_row_type(glp_prob, row) - - Returns the type of the specified row: ``GLPK.FR`` (free), ``GLPK.LO`` (lower bounded), - ``GLPK.UP`` (upper bounded), ``GLPK.DB`` (double bounded), ``GLPK.FX`` (fixed). - -.. function:: get_row_lb(glp_prob, row) - - Returns the lower bound of the specified row, ``-DBL_MAX`` if unbounded. - -.. function:: get_row_ub(glp_prob, row) - - Returns the upper bound of the specified row, ``+DBL_MAX`` if unbounded. - -.. function:: get_col_type(glp_prob, col) - - Returns the type of the specified column: ``GLPK.FR`` (free), ``GLPK.LO`` (lower bounded), - ``GLPK.UP`` (upper bounded), ``GLPK.DB`` (double bounded), ``GLPK.FX`` (fixed). - -.. function:: get_col_lb(glp_prob, col) - - Returns the lower bound of the specified column, ``-DBL_MAX`` if unbounded. - -.. function:: get_col_ub(glp_prob, col) - - Returns the upper bound of the specified column, ``+DBL_MAX`` if unbounded. - -.. function:: get_obj_coef(glp_prob, col) - - Return the objective coefficient to a column (``col`` can be 0 to indicate the constant term of the objective function). - -.. function:: get_num_nz(glp_prob) - - Return the number of non-zero elements in the constraint matrix. - -.. function:: get_mat_row(glp_prob, row, ind, val) - get_mat_row(glp_prob, row) - - Returns the contents of a row. In the first form (original C API), it fills the ``ind`` and ``val`` vectors provided, - which must be of type ``Vector{Int32}`` and ``Vector{Float64}`` respectively, and have a sufficient length to hold the result - (or they can be empty or ``nothing``, and then they're not filled). It returns the length of the result. - - In Julia, there's a second, simpler calling form which allocates and returns the two vectors as ``(ind, val)``. - -.. function:: get_mat_col(glp_prob, col, ind, val) - get_mat_col(glp_prob, col) - - Returns the contents of a column. See ``get_mat_row``. - -.. function:: create_index(glp_prob) - - Creates the name index (used by ``find_row``, ``find_col``) for the problem object. - -.. function:: find_row(glp_prob, name) - - Finds the numeric id of a row by name. Returns 0 if no row with the given name is found. - -.. function:: find_col(glp_prob, name) - - Finds the numeric id of a column by name. Returns 0 if no column with the given name is found. - -.. function:: delete_index(glp_prob) - - Deletes the name index for the problem object. - -.. function:: set_rii(glp_prob, row, rii) - - Sets the rii scale factor for the specified row. - -.. function:: set_sjj(glp_prob, col, sjj) - - Sets the sjj scale factor for the specified column. - -.. function:: get_rii(glp_prob, row) - - Returns the rii scale factor for the specified row. - -.. function:: get_sjj(glp_prob, col) - - Returns the sjj scale factor for the specified column. - -.. function:: scale_prob(glp_prob, flags) - - Performs automatic scaling of problem data for the problem object. The parameter ``flags`` can be ``GLPK.SF_AUTO`` (automatic) - or a bitwise OR of the forllowing: ``GLPK.SF_GM`` (geometric mean), ``GLPK.SF_EQ`` (equilibration), ``GLPK.SF_2N`` (nearest power of 2), - ``GLPK.SF_SKIP`` (skip if well scaled). - -.. function:: unscale_prob(glp_prob) - - Unscale the problem data (cancels the scaling effect). - -.. function:: set_row_stat(glp_prob, row, stat) - - Sets the status of the specified row. ``stat`` must be one of: ``GLPK.BS`` (basic), ``GLPK.NL`` (non-basic lower bounded), - ``GLPK.NU`` (non-basic upper-bounded), ``GLPK.NF`` (non-basic free), ``GLPK.NS`` (non-basic fixed). - -.. function:: set_col_stat(glp_prob, col, stat) - - Sets the status of the specified column. ``stat`` must be one of: ``GLPK.BS`` (basic), ``GLPK.NL`` (non-basic lower bounded), - ``GLPK.NU`` (non-basic upper-bounded), ``GLPK.NF`` (non-basic free), ``GLPK.NS`` (non-basic fixed). - -.. function:: std_basis(glp_prob) - - Constructs the standard (trivial) initial LP basis for the problem object. - -.. function:: adv_basis(glp_prob, [flags]) - - Constructs an advanced initial LP basis for the problem object. The flag ``flags`` is optional; it must be 0 if given. - -.. function:: cpx_basis(glp_prob) - - Constructs an initial LP basis for the problem object with the algorithm proposed by R. Bixby. - -.. function:: simplex(glp_prob, [glp_param]) - - The routine ``simplex`` is a driver to the LP solver based on the simplex - method. This routine retrieves problem data from the specified problem - object, calls the solver to solve the problem instance, and stores results of - computations back into the problem object. - - The parameters are specified via the optional ``glp_param`` argument, which is of type ``GLPK.SimplexParam`` - (or ``nothing`` to use the default settings). - - Returns 0 in case of success, or a non-zero flag specifying the reason for failure: ``GLPK.EBADB`` (invalid base), - ``GLPK.ESING`` (singular matrix), ``GLPK.ECOND`` (ill-conditioned matrix), ``GLPK.EBOUND`` (incorrect bounds), - ``GLPK.EFAIL`` (solver failure), ``GLPK.EOBJLL`` (lower limit reached), ``GLPK.EOBJUL`` (upper limit reached), - ``GLPK.ITLIM`` (iterations limit exceeded), ``GLPK.ETLIM`` (time limit exceeded), ``GLPK.ENOPFS`` (no primal feasible - solution), ``GLPK.ENODFS`` (no dual feasible solution). - -.. function:: exact(glp_prob, [glp_param]) - - A tentative implementation of the primal two-phase simplex method based on exact (rational) arithmetic. Similar to - ``simplex``. The optional ``glp_param`` is of type ``GLPK.SimplexParam``. - - The possible return values are ``0`` (success) or ``GLPK.EBADB``, ``GLPK.ESING``, ``GLPK.EBOUND``, - ``GLPK.EFAIL``, ``GLPK.ITLIM``, ``GLPK.ETLIM`` (see :func:`simplex`). - -.. function:: init_smcp(glp_param) - - Initializes a ``GLPK.SimplexParam`` object with the default values. In Julia, this is done at object creation time; this - function can be used to reset the object. - -.. function:: get_status(glp_prob) - - Returns the generic status of the current basic solution: ``GLPK.OPT`` (optimal), - ``GLPK.FEAS`` (feasible), ``GLPK.INFEAS`` (infeasible), ``GLPK.NOFEAS`` (no feasible solution), ``GLPK.UNBND`` - (unbounded solution), ``GLPK.UNDEF`` (undefined). - -.. function:: get_prim_stat(glp_prob) - - Returns the status of the primal basic solution: ``GLPK.FEAS``, ``GLPK.INFEAS``, ``GLPK.NOFEAS``, - ``GLPK.UNDEF`` (see :func:`get_status`). - -.. function:: get_dual_stat(glp_prob) - - Returns the status of the dual basic solution: ``GLPK.FEAS``, ``GLPK.INFEAS``, ``GLPK.NOFEAS``, - ``GLPK.UNDEF`` (see :func:`get_status`). - -.. function:: get_obj_val(glp_prob) - - Returns the current value of the objective function. - -.. function:: get_row_stat(glp_prob, row) - - Returns the status of the specified row: ``GLPK.BS``, ``GLPK.NL``, ``GLPK.NU``, ``GLPK.NF``, - ``GLPK.NS`` (see :func:`set_row_stat`). - -.. function:: get_row_prim(glp_prob, row) - - Returns the primal value of the specified row. - -.. function:: get_row_dual(glp_prob, row) - - Returns the dual value (reduced cost) of the specified row. - -.. function:: get_col_stat(glp_prob, col) - - Returns the status of the specified column: ``GLPK.BS``, ``GLPK.NL``, ``GLPK.NU``, ``GLPK.NF``, - ``GLPK.NS`` (see :func:`set_row_stat`). - -.. function:: get_col_prim(glp_prob, col) - - Returns the primal value of the specified column. - -.. function:: get_col_dual(glp_prob, col) - - Returns the dual value (reduced cost) of the specified column. - -.. function:: get_unbnd_ray(glp_prob) - - Returns the number k of a variable, which causes primal or dual unboundedness (if 1 <= k <= rows - it's row k; if rows+1 <= k <= rows+cols it's column k-rows, if k=0 such variable is not defined). - -.. function:: interior(glp_prob, [glp_param]) - - The routine ``interior`` is a driver to the LP solver based on the primal-dual - interior-point method. This routine retrieves problem data from the - specified problem object, calls the solver to solve the problem instance, and - stores results of computations back into the problem object. - - The parameters are specified via the optional ``glp_param`` argument, which is of type ``GLPK.InteriorParam`` - (or ``nothing`` to use the default settings). - - Returns 0 in case of success, or a non-zero flag specifying the reason for failure: ``GLPK.EFAIL`` (solver failure), - ``GLPK.ENOCVG`` (very slow convergence, or divergence), ``GLPK.ITLIM`` (iterations limit exceeded), - ``GLPK.EINSTAB`` (numerical instability). - -.. function:: init_iptcp(glp_param) - - Initializes a ``GLPK.InteriorParam`` object with the default values. In Julia, this is done at object creation time; this - function can be used to reset the object. - -.. function:: ipt_status(glp_prob) - - Returns the status of the interior-point solution: ``GLPK.OPT`` (optimal), - ``GLPK.INFEAS`` (infeasible), ``GLPK.NOFEAS`` (no feasible solution), ``GLPK.UNDEF`` (undefined). - -.. function:: ipt_obj_val(glp_prob) - - Returns the current value of the objective function for the interior-point solution. - -.. function:: ipt_row_prim(glp_prob, row) - - Returns the primal value of the specified row for the interior-point solution. - -.. function:: ipt_row_dual(glp_prob, row) - - Returns the dual value (reduced cost) of the specified row for the interior-point solution. - -.. function:: ipt_col_prim(glp_prob, col) - - Returns the primal value of the specified column for the interior-point solution. - -.. function:: ipt_col_dual(glp_prob, col) - - Returns the dual value (reduced cost) of the specified column for the interior-point solution. - -.. function:: set_col_kind(glp_prob, col, kind) - - Sets the kind for the specified column (for mixed-integer programming). ``kind`` must be one of: - ``GLPK.CV`` (continuous), ``GLPK.IV`` (integer), ``GLPK.BV`` (binary, 0/1). - -.. function:: get_col_kind(glp_prob, col) - - Returns the kind for the specified column (see :func:`set_col_kind`). - -.. function:: get_num_int(glp_prob) - - Returns the number of columns marked as integer (including binary). - -.. function:: get_num_bin(glp_prob) - - Returns the number of columns marked binary. - -.. function:: intopt(glp_prob, [glp_param]) - - The routine ``intopt`` is a driver to the mixed-integer-programming (MIP) solver - based on the branch- and-cut method, which is a hybrid of branch-and-bound - and cutting plane methods. - - The parameters are specified via the optional ``glp_param`` argument, which is of type ``GLPK.IntoptParam`` - (or ``nothing`` to use the default settings). - - Returns 0 in case of success, or a non-zero flag specifying the reason for failure: ``GLPK.EBOUND`` (incorrect bounds), - ``GLPK.EROOT`` (no optimal LP basis given), ``GLPK.ENOPFS`` (no primal feasible LP solution), ``GLPK.ENODFS`` (no dual - feasible LP solution), ``GLPK.EFAIL`` (solver failure), ``GLPK.EMIPGAP`` (mip gap tolearance reached), ``GLPK.ETLIM`` - (time limit exceeded), ``GLPK.ESTOP`` (terminated by application). - -.. function:: init_iocp(glp_param) - - Initializes a ``GLPK.IntoptParam`` object with the default values. In Julia, this is done at object creation time; this - function can be used to reset the object. - -.. function:: mip_status(glp_prob) - - Returns the generic status of the MIP solution: ``GLPK.OPT`` (optimal), - ``GLPK.FEAS`` (feasible), ``GLPK.NOFEAS`` (no feasible solution), ``GLPK.UNDEF`` (undefined). - -.. function:: mip_obj_val(glp_prob) - - Returns the current value of the objective function for the MIP solution. - -.. function:: mip_row_val(glp_prob, row) - - Returns the value of the specified row for the MIP solution. - -.. function:: mip_col_val(glp_prob, col) - - Returns the value of the specified column for the MIP solution. - -.. function:: read_mps(glp_prob, format, [param,] filename) - - Reads problem data in MPS format from a text file. ``format`` must be one of ``GLPK.MPS_DECK`` (fixed, old) or ``GLPK.MPS_FILE`` - (free, modern). ``param`` is optional; if given it must be ``nothing``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: write_mps(glp_prob, format, [param,] filename) - - Writes problem data in MPS format from a text file. See ``read_mps``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: read_lp(glp_prob, [param,] filename) - - Reads problem data in CPLEX LP format from a text file. ``param`` is optional; if given it must be ``nothing``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: write_lp(glp_prob, [param,] filename) - - Writes problem data in CPLEX LP format from a text file. See ``read_lp``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: read_prob(glp_prob, [flags,] filename) - - Reads problem data in GLPK LP/MIP format from a text file. ``flags`` is optional; if given it must be 0. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: write_prob(glp_prob, [flags,] filename) - - Writes problem data in GLPK LP/MIP format from a text file. See ``read_prob``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: mpl_read_model(glp_tran, filename, skip) - - Reads the model section and, optionally, the data section, from a text file in MathProg format, and stores it - in ``glp_tran``, which is a ``GLPK.MathProgWorkspace`` object. If ``skip`` is nonzero, the data section is skipped - if present. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: mpl_read_data(glp_tran, filename) - - Reads data section from a text file in MathProg format and stores it in ``glp_tran``, which is a - ``GLPK.MathProgWorkspace`` object. May be called more than once. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: mpl_generate(glp_tran, [filename]) - - Generates the model using its description stored in the ``GLPK.MathProgWorkspace`` translator workspace ``glp_tran``. - The optional ``filename`` specifies an output file; if not given or ``nothing``, the terminal is used. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: mpl_build_prob(glp_tran, glp_prob) - - Transfer information from the ``GLPK.MathProgWorkspace`` translator workspace ``glp_tran`` to the ``GLPK.Prob`` problem - object ``glp_prob``. - -.. function:: mpl_postsolve(glp_tran, glp_prob, sol) - - Copies the solution from the ``GLPK.Prob`` problem object ``glp_prob`` to the ``GLPK.MathProgWorkspace`` translator workspace - ``glp_tran`` and then executes all the remaining model statements, which follow the solve statement. - - The parameter ``sol`` specifies which solution should be copied from the problem object to the workspace: ``GLPK.SOL`` (basic), - ``GLPK.IPT`` (interior-point), ``GLPK.MIP`` (MIP). - - Returns 0 upon success; throws an error in case of failure. - -.. function:: print_sol(glp_prob, filename) - - Writes the current basic solution to a text file, in printable format. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: read_sol(glp_prob, filename) - - Reads the current basic solution from a text file, in the format used by ``write_sol``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: write_sol(glp_prob, filename) - - Writes the current basic solution from a text file, in a format which can be read by ``read_sol``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: print_ipt(glp_prob, filename) - - Writes the current interior-point solution to a text file, in printable format. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: read_ipt(glp_prob, filename) - - Reads the current interior-point solution from a text file, in the format used by ``write_ipt``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: write_ipt(glp_prob, filename) - - Writes the current interior-point solution from a text file, in a format which can be read by ``read_ipt``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: print_mip(glp_prob, filename) - - Writes the current MIP solution to a text file, in printable format. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: read_mip(glp_prob, filename) - - Reads the current MIP solution from a text file, in the format used by ``write_mip``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: write_mip(glp_prob, filename) - - Writes the current MIP solution from a text file, in a format which can be read by ``read_mip``. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: print_ranges(glp_prob, [[len,] list,] [flags,] filename) - - Performs sensitivity analysis of current optimal basic solution and writes the analysis report - in human-readable format to a text file. ``list`` is a vector specifying the rows/columns to analyze - (if 1 <= list[i] <= rows, analyzes row list[i]; if rows+1 <= list[i] <= rows+cols, analyzes column - list[i]-rows). ``len`` is the number of elements of ``list`` which will be consideres, and must be smaller - or equal to the length of the list. In Julia, ``len`` is optional (it's inferred from ``len`` if not given). - ``list`` can be empty of ``nothing`` or not given at all, implying all indices will be analyzed. ``flags`` is - optional, and must be 0 if given. - - To call this function, the current basic solution must be optimal, and the basis factorization must exist. - - Returns 0 upon success, non-zero otherwise. - -.. function:: bf_exists(glp_prob) - - Returns non-zero if the basis fatorization for the current basis exists, 0 otherwise. - -.. function:: factorize(glp_prob) - - Computes the basis factorization for the current basis. - - Returns 0 if successful, otherwise: ``GLPK.EBADB`` (invalid matrix), ``GLPK.ESING`` (singluar matrix), - ``GLPK.ECOND`` (ill-conditioned matrix). - -.. function:: bf_updated(glp_prob) - - Returns 0 if the basis factorization was computed from scratch, non-zero otherwise. - -.. function:: get_bfcp(glp_prob, glp_param) - - Retrieves control parameters, which are used on computing and updating the basis factorization - associated with the problem object, and stores them in the ``GLPK.BasisFactParam`` object ``glp_param``. - -.. function:: set_bfcp(glp_prob, [glp_param]) - - Sets the control parameters stored in the ``GLPK.BasisFactParam`` object ``glp_param`` into the problem - object. If ``glp_param`` is ``nothing`` or is omitted, resets the parameters to their defaults. - - The ``glp_param`` should always be retreived via ``get_bfcp`` before changing its values and calling - this function. - -.. function:: get_bhead(glp_prob, k) - - Returns the basis header information for the current basis. ``k`` is a row index. - - Returns either i such that 1 <= i <= rows, if ``k`` corresponds to i-th auxiliary variable, - or rows+j such that 1 <= j <= columns, if ``k`` corresponds to the j-th structural variable. - -.. function:: get_row_bind(glp_prob, row) - - Returns the index of the basic variable ``k`` which is associated with the specified row, or ``0`` if - the variable is non-basic. If ``GLPK.get_bhead(glp_prob, k) == row``, then ``GLPK.get_bind(glp_prob, row) = k``. - -.. function:: get_col_bind(glp_prob, col) - - Returns the index of the basic variable ``k`` which is associated with the specified column, or ``0`` if - the variable is non-basic. If ``GLPK.get_bhead(glp_prob, k) == rows+col``, then ``GLPK.get_bind(glp_prob, col) = k``. - -.. function:: ftran(glp_prob, v) - - Performs forward transformation (FTRAN), i.e. it solves the system Bx = b, where B is the basis matrix, - x is the vector of unknowns to be computed, b is the vector of right-hand sides. At input, ``v`` represents the - vector b; at output, it contains the vector x. ``v`` must be a ``Vector{Float64}`` whose length is the number of rows. - -.. function:: btran(glp_prob, v) - - Performs backward transformation (BTRAN), i.e. it solves the system ``B'x = b``, where ``B`` is the transposed of the basis - matrix, ``x`` is the vector of unknowns to be computed, ``b`` is the vector of right-hand sides. At input, ``v`` represents the - vector ``b``; at output, it contains the vector ``x``. ``v`` must be a ``Vector{Float64}`` whose length is the number of rows. - -.. function:: warm_up(glp_prob) - - "Warms up" the LP basis using current statuses assigned to rows and columns, i.e. computes factorization of the basis - matrix (if it does not exist), computes primal and dual components of basic solution, and determines the solution status. - - Returns 0 if successful, otherwise: ``GLPK.EBADB`` (invalid matrix), ``GLPK.ESING`` (singluar matrix), - ``GLPK.ECOND`` (ill-conditioned matrix). - -.. function:: eval_tab_row(glp_prob, k, ind, val) - eval_tab_row(glp_prob, k) - - Computes a row of the current simplex tableau which corresponds to some basic variable specified by the parameter ``k``. - If 1 <= ``k`` <= rows, uses ``k``-th auxiliary variable; if rows+1 <= ``k`` <= rows+cols, uses (``k``-rows)-th structural - variable. The basis factorization must exist. - - In the first form, stores the result in the provided vectors ``ind`` and ``val``, which must be of type ``Vector{Int32}`` and - ``Vector{Float64}``, respectively, and returns the length of the outcome; in Julia, the vectors will be resized as needed to hold - the result. - - In the second, simpler form, ``ind`` and ``val`` are returned in a tuple as the output of the function. - -.. function:: eval_tab_col(glp_prob, k, ind, val) - eval_tab_col(glp_prob, k) - - Computes a column of the current simplex tableau which corresponds to some non-basic variable specified by the parameter ``k``. - See ``eval_tab_row``. - -.. function:: transform_row(glp_prob, [len,] ind, val) - - Performs the same operation as ``eval_tab_row`` with the exception that the row to be transformed is specified - explicitly as a sparse vector. The parameter ``len`` is the number of elements of ``ind`` and ``val`` which will be used, - and must be smaller or equal to the length of both vectors; in Julia it is optional (and the ``ind`` and ``val`` must have the - same length). The vectors ``int`` and ``val`` must be of type ``Vector{Int32}`` and ``Vector{Float64}``, respectively, since - they will also hold the result; in Julia, they will be resized to the resulting required length. - - Returns the length if the resulting vectors ``ind`` and ``val``. - -.. function:: transform_col(glp_prob, [len,] ind, val) - - Performs the same operation as ``eval_tab_col`` with the exception that the row to be transformed is specified - explicitly as a sparse vector. See ``transform_row``. - -.. function:: prim_rtest(glp_prob, [len,] ind, val, dir, eps) - - Performs the primal ratio test using an explicitly specified column of the simplex table. - The current basic solution must be primal feasible. - The column is specified in sparse format by ``len`` (length of the vector), ``ind`` and ``val`` (indices and values of - the vector). ``len`` is the number of elements which will be considered and must be smaller or equal to the length of - both ``ind`` and ``val``; in Julia, it can be omitted (and then ``ind`` and ``val`` must have the same length). - The indices in ``ind`` must be between 1 and rows+cols; they must correspond to basic variables. - ``dir`` is a direction parameter which must be either +1 (increasing) or -1 (decreasing). - ``eps`` is a tolerance parameter and must be positive. - See the GLPK manual for a detailed explanation. - - Returns the position in ``ind`` and ``val`` which corresponds to the pivot element, or 0 if the choice cannot be made. - -.. function:: dual_rtest(glp_prob, [len,] ind, val, dir, eps) - - Performs the dual ratio test using an explicitly specified row of the simplex table. - The current basic solution must be dual feasible. - The indices in ``ind`` must correspond to non-basic variables. - Everything else is like in ``prim_rtest``. - -.. function:: analyze_bound(glp_prob, k) - - Analyzes the effect of varying the active bound of specified non-basic variable. See the GLPK manual for a - detailed explanation. - In Julia, this function has a different API then C. It returns ``(limit1, var1, limit2, var2)`` rather - then taking them as pointers in the argument list. - -.. function:: analyze_coef(glp_prob, k) - - Analyzes the effect of varying the objective coefficient at specified basic variable. See the GLPK manual for a - detailed explanation. - In Julia, this function has a different API then C. It returns - ``(coef1, var1, value1, coef2, var2, value2)`` rather then taking them as pointers in the argument list. - -.. function:: init_env() - - Initializes the GLPK environment. Not normally needed. - - Returns 0 (initilization successful), 1 (environment already initialized), 2 (failed, insufficient memory) or - 3 (failed, unsupported programming model). - -.. function:: version() - - Returns the GLPK version number. In Julia, instead of returning a string as in C, it returns a tuple of integer - values, containing the major and the minor number. - -.. function:: free_env() - - Frees all resources used by GLPK routines (memory blocks, etc.) which are currently still in use. Not normally needed. - - Returns 0 if successful, 1 if envirnoment is inactive. - -.. function:: term_out(flag) - - Enables/disables the terminal output of glpk routines. ``flag`` is either ``GLPK.ON`` (output enabled) or ``GLPK.OFF`` - (output disabled). - - Returns the previous status of the terminal output. - -.. function:: open_tee(filename) - - Starts copying all the terminal output to an output text file. - - Returns 0 if successful, 1 if already active, 2 if it fails creating the output file. - -.. function:: close_tee() - - Stops copying the terminal output to the output text file previously open by the ``open_tee``. - - Return 0 if successful, 1 if copying terminal output was not started. - -.. function:: malloc(size) - - Replacement of standard C ``malloc``. Allocates uninitialized memeory which must freed with ``free``. - - Returns a pointer to the allocated memory. - -.. function:: calloc(n, size) - - Replacement of standard C ``calloc``, but does not initialize the memeory. - Allocates uninitialized memeory which must freed with ``free``. - - Returns a pointer to the allocated memory. - -.. function:: free(ptr) - - Deallocates a memory block previously allocated by ``malloc`` or ``calloc``. - -.. function:: mem_usage() - - Reports some information about utilization of the memory by the routines ``malloc``, ``calloc``, - and ``free``. - In Julia, this function has a different API then C. It returns ``(count, cpeak, total, tpeak)`` rather - then taking them as pointers in the argument list. - -.. function:: mem_limit(limit) - - Limits the amount of memory avaliable for dynamic allocation to a value in megabyes given by the integer - parameter ``limit``. - -.. function:: time() - - Returns the current universal time (UTC), in milliseconds. - -.. function:: difftime(t1, t0) - - Returns the difference between two time values ``t1`` and ``t0``, expressed in seconds. - -.. function:: sdf_open_file(filename) - - Opens a plain data file. - - If successful, returns a ``GLPK.Data`` object, otherwise throws an error. - -.. function:: sdf_read_int(glp_data) - - Reads an integer number from the plain data file specified by the ``GLPK.Data`` parameter ``glp_data``, skipping initial - whitespace. - -.. function:: sdf_read_num(glp_data) - - Reads a floating point number from the plain data file specified by the ``GLPK.Data`` parameter ``glp_data``, skipping initial - whitespace. - -.. function:: sdf_read_item(glp_data) - - Reads a data item (a String) from the plain data file specified by the ``GLPK.Data`` parameter ``glp_data``, skipping initial - whitespace. - -.. function:: sdf_read_text(glp_data) - - Reads a line of text from the plain data file specified by the ``GLPK.Data`` parameter ``glp_data``, skipping initial and final - whitespace. - -.. function:: sdf_line(glp_data) - - Returns the current line in the ``GLPK.Data`` object ``glp_data`` - -.. function:: sdf_close_file(glp_data) - - Closes the file associated to ``glp_data`` and frees the resources. - -.. function:: read_cnfsat(glp_prob, filename) - - Reads the CNF-SAT problem data in DIMACS format from a text file. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: check_cnfsat(glp_prob) - - Checks if the problem object encodes a CNF-SAT problem instance, in which case it returns 0, - otherwise returns non-zero. - -.. function:: write_cnfsat(glp_prob, filename) - - Writes the CNF-SAT problem data in DIMACS format into a text file. - - Returns 0 upon success; throws an error in case of failure. - -.. function:: minisat1(glp_prob) - - The routine ``minisat1`` is a driver to MiniSat, a CNF-SAT solver developed by - Niklas Eén and Niklas Sörensson, Chalmers University of Technology, Sweden. - - Returns 0 in case of success, or a non-zero flag specifying the reason for failure: ``GLPK.EDATA`` - (problem is not CNF-SAT), ``GLPK.EFAIL`` (solver failure). - -.. function:: intfeas1(glp_prob, use_bound, obj_bound) - - The routine ``glp_intfeas1`` is a tentative implementation of an integer feasibility solver - based on a CNF-SAT solver (currently MiniSat). ``use_bound`` is a flag: if zero, any feasible solution - is seeked, otherwise seraches for an integer feasible solution. ``obj_bound`` is used only if - ``use_bound`` is non-zero, and specifies an upper/lower bound (for maximization/minimazion respectively) - to the objective function. - - All variables (columns) must either be binary or fixed. All constraint and objective coeffient - must be integer. - - Returns 0 in case of success, or a non-zero flag specifying the reason for failure: ``GLPK.EDATA`` - (problem data is not valid), ``GLPK.ERANGE`` (integer overflow occurred), ``GLPK.EFAIL`` (solver failure). diff --git a/doc/stdlib/gzip.rst b/doc/stdlib/gzip.rst deleted file mode 100644 index ae1c2e54466ad..0000000000000 --- a/doc/stdlib/gzip.rst +++ /dev/null @@ -1,129 +0,0 @@ -:mod:`GZip` --- Wrapper for gzip functions in zlib -===================================================== - -.. module:: GZip - :synopsis: Wrapper for gzip functions in zlib - -.. note:: located in ``gzip.jl`` - -This module provides a wrapper for the gzip related functions of -(`zlib `_), a free, general-purpose, legally -unencumbered, lossless data-compression library. These functions -allow the reading and writing of gzip files. - -It is currently based on ``zlib`` 1.2.7. - ------ -Notes ------ - - * This interface is only for gzipped files, not the streaming zlib - compression interface. Internally, it depends on/uses the streaming - interface, but the gzip related functions are higher level - functions pertaining to gzip files only. - - * :class:`GZipStream` is an implementation of :class:`IO` and can be used virtually - anywhere :class:`IO` is used. - - * This implementation mimics the :class:`IOStream` implementation, and should - be a drop-in replacement for :class:`IOStream`, with some exceptions: - - * :func:`seek_end` and :func:`truncate` are not available - * :func:`readuntil` is available, but is not very efficient. - (But :func:`readline` works fine.) - -In addition to :func:`gzopen` and :func:`gzfdio`/:func:`gzdopen`, the -following :class:`IO`/:class:`IOStream` functions are supported: - - :func:`close()` - :func:`flush()` - :func:`seek()` - :func:`skip()` - :func:`position()` - :func:`eof()` - :func:`read()` - :func:`readuntil()` - :func:`readline()` - :func:`write()` - -Due to limitations in ``zlib``, :func:`seek_end` and :func:`truncate` are not available. - ---------- -Functions ---------- - -.. function:: gzopen(fname, [gzmode, [buf_size]]) - - Opens a file with mode (default ``"r"``), setting internal buffer size - to buf_size (default ``Z_DEFAULT_BUFSIZE=8192``), and returns a the - file as a :class:`GZipStream`. - - ``gzmode`` must contain one of - - ==== ================================= - r read - w write, create, truncate - a write, create, append - ==== ================================= - - In addition, gzmode may also contain - - ===== ================================= - x create the file exclusively - (fails if file exists) - 0-9 compression level - ===== ================================= - - and/or a compression strategy: - - ==== ================================= - f filtered data - h Huffman-only compression - R run-length encoding - F fixed code compression - ==== ================================= - - Note that ``+`` is not allowed in gzmode. - - If an error occurs, ``gzopen`` throws a :class:`GZError` - - -.. function:: gzdopen(fd, [gzmode, [buf_size]]) - - Create a :class:`GZipStream` object from an integer file descriptor. - See :func:`gzopen` for ``gzmode`` and ``buf_size`` descriptions. - -.. function:: gzdopen(s, [gzmode, [buf_size]]) - - Create a :class:`GZipStream` object from :class:`IOStream` ``s``. - ------ -Types ------ - -.. type:: GZipStream(name, gz_file, [buf_size, [fd, [s]]]) - - Subtype of :class:`IO` which wraps a gzip stream. Returned by - :func:`gzopen` and :func:`gzdopen`. - -.. type:: GZError(err, err_str) - - gzip error number and string. Possible error values: - - +---------------------+----------------------------------------+ - | ``Z_OK`` | No error | - +---------------------+----------------------------------------+ - | ``Z_ERRNO`` | Filesystem error (consult ``errno()``) | - +---------------------+----------------------------------------+ - | ``Z_STREAM_ERROR`` | Inconsistent stream state | - +---------------------+----------------------------------------+ - | ``Z_DATA_ERROR`` | Compressed data error | - +---------------------+----------------------------------------+ - | ``Z_MEM_ERROR`` | Out of memory | - +---------------------+----------------------------------------+ - | ``Z_BUF_ERROR`` | Input buffer full/output buffer empty | - +---------------------+----------------------------------------+ - | ``Z_VERSION_ERROR`` | zlib library version is incompatible | - | | with caller version | - +---------------------+----------------------------------------+ - diff --git a/doc/stdlib/index.rst b/doc/stdlib/index.rst index f689ff2d3bab3..e2522478f1806 100644 --- a/doc/stdlib/index.rst +++ b/doc/stdlib/index.rst @@ -29,21 +29,6 @@ Built-in Modules sort -****** -Extras -****** - -.. toctree:: - :maxdepth: 1 - - argparse - options - gzip - profile - sound - textwrap - zlib - **************** Math & Numerical **************** @@ -52,5 +37,4 @@ Math & Numerical :maxdepth: 1 blas - glpk diff --git a/doc/stdlib/options.rst b/doc/stdlib/options.rst deleted file mode 100644 index 38a7c23a7d8da..0000000000000 --- a/doc/stdlib/options.rst +++ /dev/null @@ -1,138 +0,0 @@ -:mod:`OptionsMod` --- Optional arguments to functions -===================================================== - -.. module:: OptionsMod - :synopsis: Allows a flexible approach to providing default values for parameters in functions - -.. note:: located in ``options.jl`` - -This module allows a flexible approach to providing default values for parameters in functions. - -.. function:: @options([check_flag,] assignments...) - - Use the ``@options`` macro to set the value of optional parameters for a function that has been written - to use them (see :func:`defaults` to learn how to write such functions). The syntax is:: - - opts = @options a=5 b=7 - - For a function that uses optional parameters ``a`` and ``b``, this will override the default settings - for these parameters. You would likely call that function in the following way:: - - myfunc(requiredarg1, requiredarg2, ..., opts) - - Most functions written to use optional arguments will probably check to make sure that you are not - supplying parameters that are never used by the function or its sub-functions. Typically, supplying - unused parameters will result in an error. You can control the behavior this way:: - - # throw an error if a or b is not used (the default) - opts = @options CheckError a=5 b=2 - # issue a warning if a or b is not used - opts = @options CheckWarn a=5 b=2 - # don't check whether a and b are used - opts = @options CheckNone a=5 b=2 - - As an alternative to the macro syntax, you can also say:: - - opts = Options(CheckWarn, :a, 5, :b, 2) - - The check flag is optional. - -.. function:: @set_options(opts, assigments...) - - The ``@set_options`` macro lets you add new parameters to an existing options structure. For example:: - - @set_options opts d=99 - - would add ``d`` to the set of parameters in ``opts``, or re-set its value if it was already supplied. - -.. function:: @defaults(opts, assignments...) - - The ``@defaults`` macro is for writing functions that take optional parameters. The typical syntax of - such functions is:: - - function myfunc(requiredarg1, requiredarg2, ..., opts::Options) - @defaults opts a=11 b=2a+1 c=a*b d=100 - # The function body. Use a, b, c, and d just as you would - # any other variable. For example, - k = a + b - # You can pass opts down to subfunctions, which might supply - # additional defaults for other variables aa, bb, etc. - y = subfun(k, opts) - # Terminate your function with check_used, then return values - @check_used opts - return y - end - - Note the function calls :func:`@check_used` at the end. - - It is possible to have more than one Options parameter to a function, for example:: - - function twinopts(x, plotopts::Options, calcopts::Options) - @defaults plotopts linewidth=1 - @defaults calcopts n_iter=100 - # Do stuff - @check_used plotopts - @check_used calcopts - end - - Within a given scope, you should only have one call to ``@defaults`` per options variable. - -.. function:: @check_used(opts) - - The ``@check_used`` macro tests whether user-supplied parameters were ever accessed by the :func:`@defaults` - macro. The test is performed at the end of the function body, so that subfunction handling parameters not - used by the parent function may be "credited" for their usage. Each sub-function should also call - ``@check_used``, for example:: - - function complexfun(x, opts::Options) - @defaults opts parent=3 both=7 - println(parent) - println(both) - subfun1(x, opts) - subfun2(x, opts) - @check_used opts - end - - function subfun1(x, opts::Options) - @defaults opts sub1="sub1 default" both=0 - println(sub1) - println(both) - @check_used opts - end - - function subfun2(x, opts::Options) - @defaults opts sub2="sub2 default" both=22 - println(sub2) - println(both) - @check_used opts - end - - -Advanced topics ---------------- - -.. type:: Options(OptionsChecking, param1, val1, param2, val2, ...) - - ``Options`` is the central type used for handling optional arguments. Its fields are briefly described below. - - .. attribute:: key2index - - A ``Dict`` that looks up an integer index, given the symbol for a variable (e.g., ``key2index[:a]`` for - the variable ``a``) - - .. attribute:: vals - - ``vals[key2index[:a]]`` is the value to be assigned to the variable ``a`` - - .. attribute:: used - - A vector of booleans, one per variable, with ``used[key2index[:a]]`` representing the value for variable - ``a``. These all start as ``false``, but access by a ``@defaults`` command sets the corresponding value - to ``true``. This marks the variable as having been used in the function. - - .. attribute:: check_lock - - A vector of booleans, one per variable. This is a "lock" that prevents sub-functions from complaining - that they did not access variables that were intended for the parent function. :func:`@defaults` sets the - lock to true for any options variables that have already been defined; new variables added through - :func:`@set_options` will start with their ``check_lock`` set to ``false``, to be handled by a subfunction. diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst deleted file mode 100644 index 32e6cb7455e0c..0000000000000 --- a/doc/stdlib/profile.rst +++ /dev/null @@ -1,68 +0,0 @@ -profile.jl --- A simple profiler for Julia -========================================== - -.. .. module:: profile.jl - :synopsis: Allows you to determine running times for each line of code. - -.. function:: @profile - - Profiling is controlled via the ``@profile`` macro. Your first step is to determine which code you want to profile and encapsulate it inside a ``@profile begin ... end`` block, like this:: - - @profile begin - function f1(x::Int) - z = 0 - for j = 1:x - z += j^2 - end - return z - end - - function f1(x::Float64) - return x+2 - end - - function f1{T}(x::T) - return x+5 - end - - f2(x) = 2*x - end # @profile begin - - Now load the file and execute the code you want to profile, e.g.:: - - f1(215) - for i = 1:100 - f1(3.5) - end - for i = 1:150 - f1(uint8(7)) - end - for i = 1:125 - f2(11) - end - - To view the execution times, type ``@profile report``. - - Here are the various options you have for controlling profiling: - - * ``@profile report``: display cumulative profiling results - * ``@profile clear``: clear all timings accumulated thus far (start from zero) - * ``@profile off``: turn profiling off (there is no need to remove ``@profile begin ... end`` blocks) - * ``@profile on``: turn profiling back on - - ----- -Tips ----- - -You should always discard the results of your first run: it may include the overhead needed to JIT-compile some of the subfunctions. - -The primary source of variability is the garbage collector---if it runs between two "instrumentation" lines, its execution time gets added to the time that your own line of code contributes. This can make a fast-running line seem puzzlingly slow. One good way to reduce the variance is to run ``gc()`` before profiling. However, if your code tends to accumulate a bunch of temporaries that need to be cleaned up in the middle of the run, then calling ``gc()`` at the beginning can cause the collector to run at the same point in the code each time, a misleading but consistent result. A different approach is to use multiple runs (without an explicit ``gc()``) and hope that the collector runs at different points in each run. The cost of a given line is probably best reflected in those runs with shortest time for that line. - ------------ -Limitations ------------ - -Profiling adds a performance overhead which can be significant. You can prevent a subsection of your code from being profiled by encapsulating it inside a ``begin ... end`` block; in this case, the block as a whole is profiled, but the individual lines inside the block are not separately timed. - -The profiler tries to compensate for its overhead in the reported times. This naturally leads to some degree of uncertainty about the execution time of individual lines. More significantly, currently the profiler does not compensate for its own instrumentation in profiled *subfunctions*. Consequently, it's recommended that you avoid profiling nested code as a big chunk---you probably want to pick out individual functions or groups of functions to profile separately. diff --git a/doc/stdlib/sound.rst b/doc/stdlib/sound.rst deleted file mode 100644 index 7d756ccbd956b..0000000000000 --- a/doc/stdlib/sound.rst +++ /dev/null @@ -1,112 +0,0 @@ -:mod:`Sound` --- Functions for audio -==================================== - -.. module:: Sound - :synopsis: Functions for acoustic processing - -.. note:: located in ``sound.jl`` - -This module contains functions intended to process acoustic samples. - -RIFF/WAVE Functions -------------------- -These functions are used for loading and saving RIFF/WAVE (wav) functions. The API is very similar to -the one found in MATLAB. - -Here is a quick example that copies an existing file:: - - julia> require("sound") - - julia> using Sound - - julia> in_filename = ARGS[1] - - julia> y, Fs, nbits, extra = wavread(in_filename) - - julia> wavwrite(y, Fs, nbits, string("out-", in_filename)) - -.. note:: This implementation only supports little endian machines right now. - -.. function:: wavread(io, [options]) - - Reads and returns the samples from a RIFF/WAVE file. The samples are converted to floating - point values in the range from -1.0 to 1.0 by default. The ``io`` argument accepts either an - ``IO`` object or a filename (``String``). The options are passed via an ``Options`` object - (see the :mod:`OptionsMod` module). - - The available options, and the default values, are: - - * ``format`` (default = ``double``): changes the format of the returned samples. The string - ``double`` returns double precision floating point values in the range -1.0 to 1.0. The string - ``native`` returns the values as encoded in the file. The string ``size`` returns the number - of samples in the file, rather than the actual samples. - * ``subrange`` (default = ``Any``): controls which samples are returned. The default, ``Any`` - returns all of the samples. Passing a number (``Real``), ``N``, will return the first ``N`` - samples of each channel. Passing a range (``Range1{Real}``), ``R``, will return the samples - in that range of each channel. - - The returned values are: - - * ``y``: The acoustic samples; A matrix is returned for files that contain multiple channels. - * ``Fs``: The sampling frequency - * ``nbits``: The number of bits used to encode each sample - * ``extra``: Any additional bytes used to encode the samples (is always ``None``) - - The following functions are also defined to make this function compatible with MATLAB:: - - wavread(filename::String) = wavread(filename, @options) - wavread(filename::String, fmt::String) = wavread(filename, @options format=fmt) - wavread(filename::String, N::Int) = wavread(filename, @options subrange=N) - wavread(filename::String, N::Range1{Int}) = wavread(filename, @options subrange=N) - wavread(filename::String, N::Int, fmt::String) = wavread(filename, @options subrange=N format=fmt) - wavread(filename::String, N::Range1{Int}, fmt::String) = wavread(filename, @options subrange=N format=fmt) - -.. function:: wavwrite(samples, io, [options]) - - Writes samples to a RIFF/WAVE file io object. The ``io`` argument - accepts either an ``IO`` object or a filename (``String``). The - function assumes that the sample rate is 8 kHz and uses 16 bits to - encode each sample. Both of these values can be changed with the - options parameter. Each column of the data represents a different - channel. Stereo files should contain two columns. The options are - passed via an ``Options`` object (see the :mod:`OptionsMod` module). - - The available options, and the default values, are: - - * ``sample_rate`` (default = ``8000``): sampling frequency - * ``nbits`` (default = ``16``): number of bits used to encode each - sample - * ``compression`` (default = ``WAVE_FORMAT_PCM``): The desired - compression technique; accepted values are: WAVE_FORMAT_PCM, WAVE_FORMAT_IEEE_FLOAT - - The type of the input array, samples, also affects the generated - file. "Native" WAVE files are written when integers are passed into - wavwrite. This means that the literal values are written into the - file. The input ranges are as follows for integer samples. - - ====== =========== ====================== ============= - N Bits y Data Type y Data Range Output Format - ====== =========== ====================== ============= - 8 uint8 0 <= y <= 255 uint8 - 16 int16 –32768 <= y <= +32767 int16 - 24 int32 –2^23 <= y <= 2^23 – 1 int32 - ====== =========== ====================== ============= - - If samples contains floating point values, the input data ranges - are the following. - - ====== ================ ================= ============= - N Bits y Data Type y Data Range Output Format - ====== ================ ================= ============= - 8 single or double –1.0 <= y < +1.0 uint8 - 16 single or double –1.0 <= y < +1.0 int16 - 24 single or double –1.0 <= y < +1.0 int32 - 32 single or double –1.0 <= y <= +1.0 single - ====== ================ ================= ============= - - The following functions are also defined to make this function - compatible with MATLAB:: - - wavwrite(y::Array) = wavwrite(y, @options) - wavwrite(y::Array, Fs::Real, filename::String) = wavwrite(y, filename, @options sample_rate=Fs) - wavwrite(y::Array, Fs::Real, N::Real, filename::String) = wavwrite(y, filename, @options sample_rate=Fs nbits=N) diff --git a/doc/stdlib/textwrap.rst b/doc/stdlib/textwrap.rst deleted file mode 100644 index 11cd62b77b94c..0000000000000 --- a/doc/stdlib/textwrap.rst +++ /dev/null @@ -1,63 +0,0 @@ -:mod:`TextWrap` --- Text wrapping module -======================================== - -.. module:: TextWrap - :synopsis: TextWrap module - -.. note:: located in ``textwrap.jl`` - -This module provides the function ``wrap`` which parses an input text and reorganizes its white space so that -it can be printed with a fixed screen width, optionally indenting it. It also provides the two convenience -functions ``print_wrapped`` and ``println_wrapped``. - -Here is a quick example: - -:: - - julia> require("textwrap") - - julia> using TextWrap - - julia> using OptionsMod - - julia> text = "This text is going to be wrapped around in lines no longer than 20 characters."; - - julia> println_wrapped(text, @options(width=>20)) - This text is going - to be wrapped around - in lines no longer - than 20 characters. - -It's very similar to Python's textwrap module, but the interface is slightly different. - -.. function:: wrap(string , [options]) - - Returns a string in which newlines are inserted as appropriate in order for each line - to fit within a specified width. - - The options are passed via an ``Options`` object (provided by the :mod:`OptionsMod` module). - The available options, and their default values, are: - - * ``width`` (default = ``70``): the maximum width of the wrapped text, including indentation. - * ``initial_indent`` (default = ``""``): indentation of the first line. This can be any string (shorter than ``width``), - or it can be an integer number (lower than ``width``). - * ``subsequent_indent`` (default = ``""``): indentation of all lines except the first. Works the same as ``initial_indent``. - * ``break_on_hyphens`` (default = ``true``): this flag determines whether words can be broken on hyphens, e.g. whether - "high-precision" can be split into "high-" and "precision". - * ``break_long_words`` (default = ``true``): this flag determines what to do when a word is too long to fit in any line. - If ``true``, the word will be broken, otherwise it will go beyond the desired text width. - * ``replace_whitespace`` (default = ``true``): if this flag is true, all whitespace characters in the original text - (including newlines) will be replaced by spaces. - * ``expand_tabs`` (default = ``true``): if this flag is true, tabs will be expanded in-place into spaces. The expansion - happens before whitespace replacement. - * ``fix_sentence_endings`` (default = ``false``): if this flag is true, the wrapper will try to recognize sentence endings - in the middle of a paragraph and put two spaces before the next sentence in case only one is present. - -.. function:: print_wrapped(text... , [options]) - print_wrapped(io, text... , [options]) - println_wrapped(text... , [options]) - println_wrapped(io, text... , [options]) - - These are just like the standard :func:`print` and :func:`println` functions (they print multiple arguments and - accept an optional ``IO`` first argument), except that they wrap the result, and accept an optional - last argument with the options to pass to :func:`wrap`. diff --git a/doc/stdlib/zlib.rst b/doc/stdlib/zlib.rst deleted file mode 100644 index 60b8e31225de5..0000000000000 --- a/doc/stdlib/zlib.rst +++ /dev/null @@ -1,72 +0,0 @@ -:mod:`Zlib` --- Wrapper for zlib compress/uncompress -==================================================== - -.. module:: Zlib - :synopsis: Zlib compress/uncompress wrapper - -.. note:: located in ``zlib.jl`` - -This module provides a wrapper for the compress/uncompress and related -utility functions of (`zlib `_), a free, -general-purpose, legally unencumbered, lossless data-compression -library. These functions allow the compression and decompression of -byte buffers (``Array{Uint8,1}``). - -Note that the zlib stream functions are not yet wrapped. - -It is currently based on zlib 1.2.7. - -Utility Functions ------------------ - -.. function:: compress_bound(input_size) - - Returns the maximum size of the compressed output buffer for a - given uncompressed input size. - - -.. function:: compress(source, [level]) - - Compresses source using the given compression level, and returns - the compressed buffer (``Array{Uint8,1}``). ``level`` is an - integer between 0 and 9, or one of ``Z_NO_COMPRESSION``, - ``Z_BEST_SPEED``, ``Z_BEST_COMPRESSION``, or - ``Z_DEFAULT_COMPRESSION``. It defaults to - ``Z_DEFAULT_COMPRESSION``. - - If an error occurs, ``compress`` throws a :class:`ZError` with more - information about the error. - - -.. function:: compress_to_buffer(source, dest, level=Z_DEFAULT_COMPRESSION) - - Compresses the source buffer into the destination buffer, and - returns the number of bytes written into dest. - - If an error occurs, ``uncompress`` throws a :class:`ZError` with more - information about the error. - - -.. function:: uncompress(source, [uncompressed_size]) - - Allocates a buffer of size ``uncompressed_size``, uncompresses - source to this buffer using the given compression level, and - returns the compressed buffer. If ``uncompressed_size`` is not - given, the size of the output buffer is estimated as - ``2*length(source)``. If the uncompressed_size is larger than - uncompressed_size, the allocated buffer is grown and the - uncompression is retried. - - If an error occurs, ``uncompress`` throws a :class:`ZError` with more - information about the error. - - -.. function:: uncompress_to_buffer(source, dest) - - Uncompresses the source buffer into the destination buffer. - Returns the number of bytes written into dest. An error is thrown - if the destination buffer does not have enough space. - - If an error occurs, ``uncompress_to_buffer`` throws a :class:`ZError` - with more information about the error. -