<commit_before>/*
 * This source file forms part of libsxbp, a library which generates
 * experimental 2D spiral-like shapes based on input binary data.
 */

/**
 * @file
 *
 * @brief This compilation unit provides basic functions to initialise a spiral.
 *
 * @author <NAME> <j<EMAIL>.a.saxby+TNOPLuc8vM==@gmail.<EMAIL>
 * @date 2016
 *
 * @copyright Copyright (C) <NAME> 2016
 *
 * @copyright This program is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Affero General Public License
 * (version 3), as published by the Free Software Foundation.
 *
 * @copyright This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * @copyright You should have received a copy of the GNU Affero General Public
 * License along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
#ifndef SAXBOPHONE_SAXBOSPIRAL_INITIALISE_H
#define SAXBOPHONE_SAXBOSPIRAL_INITIALISE_H

#include "saxbospiral.h"


#ifdef __cplusplus
extern "C"{
#endif

/*
 * when facing the direction specified by current, return the direction that
 * will be faced when turning in the rotational direction specified by turn.
 */
sxbp_direction_t sxbp_change_direction(
    sxbp_direction_t current, sxbp_rotation_t turn
);

/*
 * returns a spiral struct with all fields initialised to 0
 */
sxbp_spiral_t sxbp_blank_spiral();

/*
 * given a buffer_t full of data, and a pointer to a blank spiral_t
 * struct, populates the spiral struct from the data in the buffer
 * this converts the 0s and 1s in the data into UP, LEFT, DOWN, RIGHT
 * instructions which are then used to build the pattern.
 * returns a status_t struct with error information (if needed)
 *
 * Asserts:
 * - That the spiral struct pointed to has its pointer attributes set to NULL
 */
sxbp_status_t sxbp_init_spiral(sxbp_buffer_t buffer, sxbp_spiral_t* spiral);

#ifdef __cplusplus
} // extern "C"
#endif

// end of header file
#endif<commit_msg>Complete doxygen documentation of initialise unit<commit_after>/*
 * This source file forms part of libsxbp, a library which generates
 * experimental 2D spiral-like shapes based on input binary data.
 */

/**
 * @file
 *
 * @brief This compilation unit provides basic functions to initialise a spiral.
 *
 * @author <NAME> <<EMAIL>
 * @date 2016
 *
 * @copyright Copyright (C) <NAME> 2016
 *
 * @copyright This program is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Affero General Public License
 * (version 3), as published by the Free Software Foundation.
 *
 * @copyright This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * @copyright You should have received a copy of the GNU Affero General Public
 * License along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
#ifndef SAXBOPHONE_SAXBOSPIRAL_INITIALISE_H
#define SAXBOPHONE_SAXBOSPIRAL_INITIALISE_H

#include "saxbospiral.h"


#ifdef __cplusplus
extern "C"{
#endif

/**
 * @brief Gets the direction which is clockwise or anti-clockwise to the current
 * direction.
 * @detail Given a current direction and a rotational direction, return the new
 * direction which would be faced after turning 90 degrees in the given
 * rotational direction.
 *
 * @param current The current direction to turn from.
 * @param turn The rotational direction to turn in.
 * @return The new direction which will be faced after turning.
 */
sxbp_direction_t sxbp_change_direction(
    sxbp_direction_t current, sxbp_rotation_t turn
);

/**
 * @brief Builds a blank spiral struct.
 * @detail This is a convenience function, as the struct has many fields. This
 * function will create a spiral struct with all of these fields initialised to
 * 0 or their default 'blank' state. No memory is allocated.
 *
 * @return A blank spiral struct with all fields initialised to 0 or blank values.
 */
sxbp_spiral_t sxbp_blank_spiral();

/**
 * @brief Builds a partially-complete spiral from binary input data stored in a
 * buffer.
 * @detail This converts the 0s and 1s in the buffer data into UP, LEFT, DOWN,
 * RIGHT instructions which are then used to build the pattern. Only the line
 * directions are calculated at this point, all line lengths are 0.
 *
 * @param buffer A buffer containing at least one byte of data, used to
 * determine the directions of the lines in the spiral it will create.
 * @param spiral [out] Spiral object which the line directions will be written
 * to.
 * @return SXBP_OPERATION_OK on success.
 * @return SXBP_MALLOC_REFUSED on memory allocation failure.
 *
 * @note Asserts:
 * - That all the pointer members of parameter spiral are set to NULL
 */
sxbp_status_t sxbp_init_spiral(sxbp_buffer_t buffer, sxbp_spiral_t* spiral);

#ifdef __cplusplus
} // extern "C"
#endif

// end of header file
#endif
{'fraction_non_alphanumeric': 0.06911279363230441, 'fraction_numerical': 0.006018248883711901, 'mean_word_length': 4.111111111111111, 'pattern_counts': {'":': 0, '<': 14, '<?xml version=': 0, '>': 12, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2924659', 'n_tokens_mistral': 1537, 'n_tokens_neox': 1455, 'n_words': 684}